{ "openapi": "3.1.0", "info": { "title": "DURUM.ai REST API", "version": "1.0.0", "summary": "Read your own ad attribution, funnel, sales and call data; manage goals, ad rules and creatives.", "description": "DURUM.ai connects ad spend (Meta, Google Ads, TikTok, ChatGPT Ads) to real leads, bookings and sales, attributed by identifier. This API returns the data of the single account bound to the key. Paid tiers only: on the Discovery plan every call returns 403 plan_free_no_api. Rate limit: 600 requests per minute per key (X-RateLimit-Limit, X-RateLimit-Remaining). Credentials, AI internals, internal costs and margins are stripped from every response. Full reference: https://docs.durum.ai/en/developers/api-reference. MCP server for AI assistants: https://app.durum.ai/mcp.", "termsOfService": "https://durum.ai/fr/legal/conditions", "contact": { "name": "Durum Marketing LLC", "email": "info@durum.ai", "url": "https://docs.durum.ai/en/contact" } }, "externalDocs": { "description": "API reference", "url": "https://docs.durum.ai/en/developers/api-reference" }, "servers": [ { "url": "https://app.durum.ai/api/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "Meta" }, { "name": "Dashboard" }, { "name": "Ads" }, { "name": "Attribution" }, { "name": "Events" }, { "name": "Sales" }, { "name": "Finance" }, { "name": "Funnel" }, { "name": "Contacts" }, { "name": "Calls" }, { "name": "Journeys" }, { "name": "Creatives" }, { "name": "Settings" } ], "paths": { "/": { "get": { "operationId": "getApiIndex", "summary": "API index", "description": "Lists every read and write route with its method, scope and full path. No authentication required.", "tags": [ "Meta" ], "security": [], "responses": { "200": { "description": "The route index.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIndex" } } } } } } }, "/tools": { "get": { "operationId": "getToolsManifest", "summary": "Tools manifest for this key", "description": "JSON manifest of the routes covered by the key scopes, with an inputSchema per tool, ready for LLM function calling.", "tags": [ "Meta" ], "responses": { "200": { "description": "The tools manifest.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolsManifest" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboard/kpis": { "get": { "operationId": "getDashboardKpis", "summary": "Aggregated KPIs", "description": "KPIs aggregated over the period: leads, applications, bookings, meetings, shows, no-shows, sales, revenue, average ticket.\n\nRequired scope: `read:dashboard`.", "tags": [ "Dashboard" ], "x-required-scope": "read:dashboard", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Kpis" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/dashboard/daily": { "get": { "operationId": "getDashboardDaily", "summary": "Daily series", "description": "One row per day with leads, bookings, sales, revenue and ad spend.\n\nRequired scope: `read:dashboard`.", "tags": [ "Dashboard" ], "x-required-scope": "read:dashboard", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Days", "items": { "$ref": "#/components/schemas/DailyRow" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/dashboard/breakdowns": { "get": { "operationId": "getDashboardBreakdowns", "summary": "Breakdown by dimension", "description": "Results grouped by source, campaign, product or rep.\n\nRequired scope: `read:dashboard`.", "tags": [ "Dashboard" ], "x-required-scope": "read:dashboard", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "dim", "in": "query", "required": false, "description": "Dimension to group by.", "schema": { "type": "string", "enum": [ "source", "campaign", "product", "rep" ], "default": "source" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Rows", "items": { "$ref": "#/components/schemas/BreakdownRow" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/ads/spend": { "get": { "operationId": "getAdSpend", "summary": "Spend per ad", "description": "Spend, clicks, impressions and reach per ad and platform.\n\nRequired scope: `read:ads`.", "tags": [ "Ads" ], "x-required-scope": "read:ads", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Ads", "items": { "$ref": "#/components/schemas/AdSpendRow" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/ads/campaigns": { "get": { "operationId": "getAdCampaigns", "summary": "Spend per campaign", "description": "One row per campaign and platform, sorted by descending spend.\n\nRequired scope: `read:ads`.", "tags": [ "Ads" ], "x-required-scope": "read:ads", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Campaigns", "items": { "$ref": "#/components/schemas/CampaignRow" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/ads/rules": { "get": { "operationId": "listAdRules", "summary": "Automated ad rules", "description": "Your automated ad rules with their state, dry-run mode, parameters and last run.\n\nRequired scope: `read:ads`.", "tags": [ "Ads" ], "x-required-scope": "read:ads", "parameters": [], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Rules", "items": { "$ref": "#/components/schemas/AdRule" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/ads/rules/runs": { "get": { "operationId": "listAdRuleRuns", "summary": "Runs of an ad rule", "description": "The latest runs of one ad rule.\n\nRequired scope: `read:ads`.", "tags": [ "Ads" ], "x-required-scope": "read:ads", "parameters": [ { "name": "rule_id", "in": "query", "required": true, "description": "Rule identifier from listAdRules.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of rows (default 30, max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Runs", "items": { "$ref": "#/components/schemas/AdRuleRun" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/attribution": { "get": { "operationId": "getAttribution", "summary": "Attribution per ad", "description": "Multi-touch attribution per ad: media, leads, bookings, sales and revenue split by first touch, last touch and assisted.\n\nRequired scope: `read:attribution`.", "tags": [ "Attribution" ], "x-required-scope": "read:attribution", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Ads", "items": { "$ref": "#/components/schemas/AttributionRow" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/attribution/health": { "get": { "operationId": "getAttributionHealth", "summary": "Capture health", "description": "How well events are matched to ads (exact id, by name, unresolved) and pixel activity.\n\nRequired scope: `read:attribution`.", "tags": [ "Attribution" ], "x-required-scope": "read:attribution", "parameters": [], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AttributionHealth" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/attribution/report": { "get": { "operationId": "getAttributionReport", "summary": "Attribution report", "description": "Gross and net revenue and ROI per source, campaign and ad.\n\nRequired scope: `read:attribution`.", "tags": [ "Attribution" ], "x-required-scope": "read:attribution", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Rows", "items": { "$ref": "#/components/schemas/AttributionReportRow" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/events": { "get": { "operationId": "listEvents", "summary": "CRM events", "description": "Leads, applications, bookings, no-shows, sales, payments and cancellations, newest first. Cursor pagination: pass the event_datetime of the last row as cursor.\n\nRequired scope: `read:events`.", "tags": [ "Events" ], "x-required-scope": "read:events", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Event type. Without it, all events.", "schema": { "type": "string", "enum": [ "lead", "application", "booking", "no_show", "sale", "cancel", "payment", "sale_lost" ] } }, { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of rows (default 50, max 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "ISO 8601 timestamp: only events strictly older are returned.", "schema": { "type": "string", "format": "date-time" } }, { "name": "rep", "in": "query", "required": false, "description": "Filter on the assigned rep name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Events", "items": { "$ref": "#/components/schemas/Event" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/events/summary": { "get": { "operationId": "getEventsSummary", "summary": "Events per ad", "description": "Event counts and total value per ad and campaign.\n\nRequired scope: `read:events`.", "tags": [ "Events" ], "x-required-scope": "read:events", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Rows", "items": { "$ref": "#/components/schemas/EventSummaryRow" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sales/summary": { "get": { "operationId": "getSalesSummary", "summary": "Sales summary", "description": "Sales KPIs, pipeline and no-show.\n\nRequired scope: `read:sales`.", "tags": [ "Sales" ], "x-required-scope": "read:sales", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SalesSummary" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sales/reps": { "get": { "operationId": "getRepPerformance", "summary": "Per-rep performance", "description": "Bookings, shows, sales, revenue, close rate and no-show rate per sales rep.\n\nRequired scope: `read:sales`.", "tags": [ "Sales" ], "x-required-scope": "read:sales", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Reps", "items": { "$ref": "#/components/schemas/RepRow" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sales/cycle": { "get": { "operationId": "getSalesCycle", "summary": "Sales cycle", "description": "Days from first touch to sale: average, median, percentiles and weekly trend.\n\nRequired scope: `read:sales`.", "tags": [ "Sales" ], "x-required-scope": "read:sales", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SalesCycle" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/finance/pnl": { "get": { "operationId": "getFinancePnl", "summary": "Profit and loss", "description": "P&L and revenue. Margins are never exposed.\n\nRequired scope: `read:finance`.", "tags": [ "Finance" ], "x-required-scope": "read:finance", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Pnl" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/funnel": { "get": { "operationId": "getFunnel", "summary": "Funnel", "description": "Funnel stages, conversion by source, campaign and product, time to conversion.\n\nRequired scope: `read:funnel`.", "tags": [ "Funnel" ], "x-required-scope": "read:funnel", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Funnel" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contacts": { "get": { "operationId": "listContacts", "summary": "Contacts", "description": "Contacts with their events, sources, value and form answers.\n\nRequired scope: `read:contacts`.", "tags": [ "Contacts" ], "x-required-scope": "read:contacts", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of rows (default 100, max 500).", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of rows to skip (offset pagination).", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "search", "in": "query", "required": false, "description": "Text search (email, name, domain).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Contacts", "items": { "$ref": "#/components/schemas/Contact" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contacts/customers": { "get": { "operationId": "listCustomers", "summary": "Customers", "description": "One row per customer with revenue, purchases and commission state.\n\nRequired scope: `read:contacts`.", "tags": [ "Contacts" ], "x-required-scope": "read:contacts", "parameters": [], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Customers", "items": { "$ref": "#/components/schemas/Customer" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contacts/purchases": { "get": { "operationId": "listPurchases", "summary": "Purchases", "description": "One row per purchase.\n\nRequired scope: `read:contacts`.", "tags": [ "Contacts" ], "x-required-scope": "read:contacts", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Purchases", "items": { "$ref": "#/components/schemas/Purchase" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contacts/calls": { "get": { "operationId": "getContactCalls", "summary": "Calls of a contact", "description": "Calls of the last 365 days this email took part in, with their analysis.\n\nRequired scope: `read:calls`.", "tags": [ "Calls" ], "x-required-scope": "read:calls", "parameters": [ { "name": "email", "in": "query", "required": true, "description": "Contact email.", "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Calls", "items": { "$ref": "#/components/schemas/Call" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/calls": { "get": { "operationId": "listCalls", "summary": "Analyzed calls", "description": "Analyzed calls, newest first, with summary, qualification, next step and scorecard.\n\nRequired scope: `read:calls`.", "tags": [ "Calls" ], "x-required-scope": "read:calls", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of rows (default 50, max 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of rows to skip (offset pagination).", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Calls", "items": { "$ref": "#/components/schemas/Call" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/calls/transcript": { "get": { "operationId": "getCallTranscript", "summary": "Call transcript", "description": "Raw transcript of one call, as ordered segments.\n\nRequired scope: `read:calls`.", "tags": [ "Calls" ], "x-required-scope": "read:calls", "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Call identifier: the artifact_id returned by listCalls.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Segments", "items": { "$ref": "#/components/schemas/TranscriptSegment" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/calls/recording": { "get": { "operationId": "getCallRecording", "summary": "Call recording", "description": "Signed URLs, valid one hour, to download the audio or video of one call.\n\nRequired scope: `read:calls`.", "tags": [ "Calls" ], "x-required-scope": "read:calls", "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Call identifier: the artifact_id returned by listCalls.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CallRecording" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/journeys": { "get": { "operationId": "listJourneys", "summary": "Customer journeys", "description": "Customer journeys with the UTM captured at the first and last touch. from and to filter on last activity.\n\nRequired scope: `read:journeys`.", "tags": [ "Journeys" ], "x-required-scope": "read:journeys", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of rows (default 50, max 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of rows to skip (offset pagination).", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "search", "in": "query", "required": false, "description": "Email fragment.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Journeys" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/journeys/contact": { "get": { "operationId": "getContactJourney", "summary": "Journey of one contact", "description": "Full chronological touchpoint chain of one contact, with UTM, ad ids and click ids at each touch.\n\nRequired scope: `read:journeys`.", "tags": [ "Journeys" ], "x-required-scope": "read:journeys", "parameters": [ { "name": "email", "in": "query", "required": true, "description": "Contact email.", "schema": { "type": "string", "format": "email" } }, { "name": "pageviews", "in": "query", "required": false, "description": "true or 1 to include page views.", "schema": { "type": "string", "enum": [ "true", "1" ] } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ContactJourney" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/touchpoints": { "get": { "operationId": "listTouchpoints", "summary": "Touchpoint feed", "description": "All touchpoints, newest first, for syncing into a warehouse.\n\nRequired scope: `read:journeys`.", "tags": [ "Journeys" ], "x-required-scope": "read:journeys", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (inclusive), YYYY-MM-DD. Without a period the route applies its own default window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (inclusive), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of rows (default 100, max 500).", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of rows to skip (offset pagination).", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "kind", "in": "query", "required": false, "description": "Touchpoint kind.", "schema": { "type": "string", "enum": [ "web", "conversion" ] } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Touchpoints" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/creatives/requests": { "get": { "operationId": "listCreativeRequests", "summary": "Creative needs", "description": "Requests DURUM writes when creatives are missing, oldest first. Without status: open and partial.\n\nRequired scope: `read:creatives`.", "tags": [ "Creatives" ], "x-required-scope": "read:creatives", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Exact status to return.", "schema": { "type": "string" } }, { "name": "unnotified", "in": "query", "required": false, "description": "1 or true: only requests never relayed to a team.", "schema": { "type": "string", "enum": [ "1", "true" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of rows (default 50, max 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Requests", "items": { "$ref": "#/components/schemas/CreativeRequest" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/icp/criteria": { "get": { "operationId": "getIcpCriteria", "summary": "ICP criteria", "description": "Your ideal customer profile criteria.\n\nRequired scope: `read:icp`.", "tags": [ "Settings" ], "x-required-scope": "read:icp", "parameters": [], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/IcpCriteria" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/capi/pixels": { "get": { "operationId": "listPixels", "summary": "Meta pixels", "description": "Connected Meta pixels and the default one. Access tokens are never returned.\n\nRequired scope: `read:capi`.", "tags": [ "Settings" ], "x-required-scope": "read:capi", "parameters": [], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Pixels" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/goals": { "put": { "operationId": "replaceGoals", "summary": "Replace KPI goals", "description": "Replaces your monthly KPI goals. POST is accepted as an alias.\n\nRequired scope: `write:goals`.", "tags": [ "Settings" ], "x-required-scope": "write:goals", "parameters": [], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Success" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "goals" ], "properties": { "goals": { "type": "array", "description": "Goals", "items": { "type": "object", "required": [ "metric_key", "target_value" ], "properties": { "metric_key": { "type": "string", "description": "Metric key, for example revenue" }, "target_value": { "type": "number", "description": "Monthly target" } } } } } } } } } } }, "/sale-rule": { "put": { "operationId": "setSaleRule", "summary": "Set the sale counting rule", "description": "Sets how a sale is counted and deduplicated. POST is accepted as an alias.\n\nRequired scope: `write:settings`.", "tags": [ "Settings" ], "x-required-scope": "write:settings", "parameters": [], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Success" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sale_rule" ], "properties": { "sale_rule": { "type": "object", "description": "Sale counting rule", "properties": {}, "additionalProperties": true } } } } } } } }, "/icp": { "put": { "operationId": "setIcpCriteria", "summary": "Set ICP criteria", "description": "Replaces your ideal customer profile criteria. POST is accepted as an alias.\n\nRequired scope: `write:icp`.", "tags": [ "Settings" ], "x-required-scope": "write:icp", "parameters": [], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Success" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "icp" ], "properties": { "icp": { "type": "object", "description": "ICP criteria", "properties": {}, "additionalProperties": true } } } } } } } }, "/ads/rules/enable": { "post": { "operationId": "enableAdRule", "summary": "Enable or disable an ad rule", "description": "Enables (default) or disables an ad rule. PUT is accepted as an alias.\n\nRequired scope: `write:ads`.", "tags": [ "Ads" ], "x-required-scope": "write:ads", "parameters": [], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Success" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rule_id" ], "properties": { "rule_id": { "type": "string", "description": "Rule identifier" }, "enabled": { "type": "boolean", "default": true, "description": "false to disable" } } } } } } } }, "/ads/rules/dry-run": { "post": { "operationId": "setAdRuleDryRun", "summary": "Switch an ad rule to dry-run", "description": "Dry-run computes without acting on the ad network. dry_run false arms the rule for real (paid tier, otherwise plan_free_no_autopilot). PUT is accepted as an alias.\n\nRequired scope: `write:ads`.", "tags": [ "Ads" ], "x-required-scope": "write:ads", "parameters": [], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Success" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rule_id" ], "properties": { "rule_id": { "type": "string", "description": "Rule identifier" }, "dry_run": { "type": "boolean", "default": true, "description": "false to arm the rule" } } } } } } } }, "/ads/rules/delete": { "post": { "operationId": "deleteAdRule", "summary": "Delete an ad rule", "description": "Deletes an ad rule. Final.\n\nRequired scope: `write:ads`.", "tags": [ "Ads" ], "x-required-scope": "write:ads", "parameters": [], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Success" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rule_id" ], "properties": { "rule_id": { "type": "string", "description": "Rule identifier" } } } } } } } }, "/creatives/upload-url": { "post": { "operationId": "createCreativeUploadUrl", "summary": "Get an upload URL for a visual", "description": "Step 1 of a creative import: returns a short-lived upload_url (send the file with PUT and the same Content-Type) and the asset_url to pass to importCreative.\n\nRequired scope: `write:creatives`.", "tags": [ "Creatives" ], "x-required-scope": "write:creatives", "parameters": [], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Upload authorization", "properties": { "asset_url": { "type": "string", "description": "URL to pass as creative.asset_url" }, "upload_url": { "type": "string", "description": "Signed upload URL" }, "token": { "type": "string", "description": "Upload token" }, "path": { "type": "string", "description": "Storage path" }, "content_type": { "type": "string", "description": "Media type" } }, "additionalProperties": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content_type" ], "properties": { "content_type": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "video/mp4" ], "description": "Media type of the file" }, "label": { "type": "string", "maxLength": 60, "description": "Readable label" } } } } } } } }, "/creatives/import": { "post": { "operationId": "importCreative", "summary": "Import a creative into the reserve", "description": "Step 2: adds a creative to the reserve of the creative library. Publishes nothing and touches no budget. Idempotent on external_ref.\n\nRequired scope: `write:creatives`.", "tags": [ "Creatives" ], "x-required-scope": "write:creatives", "parameters": [], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Imported creative", "properties": { "id": { "type": "string", "description": "Creative id" }, "external_ref": { "type": "string", "description": "Your identifier" }, "angle": { "type": [ "string", "null" ], "description": "Angle" }, "score": { "type": [ "number", "null" ], "description": "Score, null until computed" }, "en_attente": { "type": "integer", "description": "Unpublished creatives in the reserve" } }, "additionalProperties": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "external_ref", "creative" ], "properties": { "external_ref": { "type": "string", "maxLength": 200, "description": "Your stable identifier" }, "creative": { "type": "object", "description": "Creative", "properties": { "angle": { "type": "string", "description": "Angle" }, "primary_text": { "type": "string", "description": "Primary text" }, "headline": { "type": "string", "description": "Headline" }, "hook": { "type": "string", "description": "Hook" }, "cta": { "type": "string", "description": "Call to action" }, "destination_url": { "type": "string", "description": "Destination URL" }, "asset_url": { "type": "string", "description": "asset_url from createCreativeUploadUrl" }, "asset_kind": { "type": "string", "enum": [ "image", "video" ], "description": "Asset kind" }, "variant_label": { "type": "string", "description": "Variant label" }, "visual_subtype": { "type": "string", "description": "Visual subtype" }, "funnel": { "type": "string", "description": "Funnel" }, "product": { "type": "string", "description": "Product" }, "audience": { "type": "string", "description": "Audience" }, "video_script": { "type": "string", "description": "Video script" }, "source": { "type": "object", "description": "Free provenance object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true } } } } } } } }, "/creatives/requests/ack": { "post": { "operationId": "ackCreativeRequests", "summary": "Acknowledge creative needs", "description": "Marks creative needs as relayed (sets notified_at). Does not close them. Replaying the same batch has no effect.\n\nRequired scope: `write:creatives`.", "tags": [ "Creatives" ], "x-required-scope": "write:creatives", "parameters": [], "responses": { "200": { "description": "Success: the payload is in data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "integer", "description": "Number of requests updated" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uuid" }, "description": "Request UUIDs" } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "durum_sk_live_...", "description": "API key created in DURUM.ai, Settings, API keys. Authorization: Bearer durum_sk_live_..." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Alternative header for the same key. Authorization is read first when both are present." } }, "schemas": { "Error": { "type": "object", "description": "Every error returns this object with the matching HTTP status.", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code, for example invalid_or_missing_api_key, insufficient_scope, plan_free_no_api, forbidden, unknown_route, method_not_allowed, rate_limited, tenant_barrier, upstream_error, or a validation message for 400." }, "required": { "type": "string", "description": "Only with insufficient_scope: the scope the key is missing." }, "retry_after_seconds": { "type": "integer", "description": "Only with 429: seconds to wait before retrying." }, "route": { "type": "string", "description": "Only with unknown_route: the path that was requested." } }, "additionalProperties": true, "required": [ "error" ] }, "Kpis": { "type": "object", "description": "KPIs aggregated over the period.", "properties": { "leads": { "type": "number", "description": "Leads" }, "applications": { "type": "number", "description": "Applications" }, "bookings": { "type": "number", "description": "Bookings" }, "meetings": { "type": "number", "description": "Meetings held or scheduled" }, "shows": { "type": "number", "description": "Meetings attended" }, "no_shows": { "type": "number", "description": "No-shows" }, "total_sales": { "type": "number", "description": "Sales" }, "revenue": { "type": "number", "description": "Revenue" }, "ticket_moyen": { "type": "number", "description": "Average sale value" } }, "additionalProperties": true }, "DailyRow": { "type": "object", "description": "One row per day.", "properties": { "report_date": { "type": [ "string", "null" ], "description": "Day, YYYY-MM-DD" }, "leads": { "type": [ "number", "null" ], "description": "leads" }, "applications": { "type": [ "number", "null" ], "description": "applications" }, "bookings": { "type": [ "number", "null" ], "description": "bookings" }, "meetings": { "type": [ "number", "null" ], "description": "meetings" }, "no_shows": { "type": [ "number", "null" ], "description": "no shows" }, "sales": { "type": [ "number", "null" ], "description": "sales" }, "revenue": { "type": [ "number", "null" ], "description": "revenue" }, "spend": { "type": [ "number", "null" ], "description": "Ad spend" } }, "additionalProperties": true }, "BreakdownRow": { "type": "object", "description": "One row per dimension value.", "properties": { "dimension_key": { "type": [ "string", "null" ], "description": "Value of the chosen dimension (source, campaign, product or rep)" }, "leads": { "type": [ "number", "null" ], "description": "leads" }, "applications": { "type": [ "number", "null" ], "description": "applications" }, "bookings": { "type": [ "number", "null" ], "description": "bookings" }, "shows": { "type": [ "number", "null" ], "description": "shows" }, "no_shows": { "type": [ "number", "null" ], "description": "no shows" }, "sales": { "type": [ "number", "null" ], "description": "sales" }, "revenue": { "type": [ "number", "null" ], "description": "revenue" } }, "additionalProperties": true }, "AdSpendRow": { "type": "object", "description": "Spend for one ad on one platform.", "properties": { "ad_id": { "type": [ "string", "null" ], "description": "ad id" }, "ad_name": { "type": [ "string", "null" ], "description": "ad name" }, "campaign_name": { "type": [ "string", "null" ], "description": "campaign name" }, "campaign_id": { "type": [ "string", "null" ], "description": "campaign id" }, "adset_name": { "type": [ "string", "null" ], "description": "adset name" }, "adset_id": { "type": [ "string", "null" ], "description": "adset id" }, "platform": { "type": [ "string", "null" ], "description": "meta, google, tiktok..." }, "total_spend": { "type": [ "number", "null" ], "description": "total spend" }, "total_clicks": { "type": [ "number", "null" ], "description": "total clicks" }, "total_impressions": { "type": [ "number", "null" ], "description": "total impressions" }, "total_reach": { "type": [ "number", "null" ], "description": "total reach" } }, "additionalProperties": true }, "CampaignRow": { "type": "object", "description": "Spend for one campaign on one platform.", "properties": { "campaign_id": { "type": [ "string", "null" ], "description": "campaign id" }, "campaign_name": { "type": [ "string", "null" ], "description": "campaign name" }, "platform": { "type": [ "string", "null" ], "description": "platform" }, "total_spend": { "type": [ "number", "null" ], "description": "total spend" }, "total_clicks": { "type": [ "number", "null" ], "description": "total clicks" }, "total_impressions": { "type": [ "number", "null" ], "description": "total impressions" }, "total_reach": { "type": [ "number", "null" ], "description": "total reach" }, "nb_ads": { "type": [ "integer", "null" ], "description": "nb ads" }, "nb_adsets": { "type": [ "integer", "null" ], "description": "nb adsets" } }, "additionalProperties": true }, "AdRule": { "type": "object", "description": "An automated ad rule: label, type, campaign, enabled state, dry-run mode, parameters and last run.", "properties": {}, "additionalProperties": true }, "AdRuleRun": { "type": "object", "description": "One run of an ad rule.", "properties": {}, "additionalProperties": true }, "AttributionRow": { "type": "object", "description": "Attribution for one ad. Columns are prefixed out_.", "properties": { "out_ad_id": { "type": [ "string", "null" ], "description": "out ad id" }, "out_ad_name": { "type": [ "string", "null" ], "description": "out ad name" }, "out_campaign_id": { "type": [ "string", "null" ], "description": "out campaign id" }, "out_campaign_name": { "type": [ "string", "null" ], "description": "out campaign name" }, "out_adset_id": { "type": [ "string", "null" ], "description": "out adset id" }, "out_adset_name": { "type": [ "string", "null" ], "description": "out adset name" }, "out_platform": { "type": [ "string", "null" ], "description": "out platform" }, "out_total_spend": { "type": [ "number", "null" ], "description": "out total spend" }, "out_total_clicks": { "type": [ "number", "null" ], "description": "out total clicks" }, "out_total_impressions": { "type": [ "number", "null" ], "description": "out total impressions" }, "out_total_reach": { "type": [ "number", "null" ], "description": "out total reach" }, "out_leads": { "type": [ "number", "null" ], "description": "out leads" }, "out_applications": { "type": [ "number", "null" ], "description": "out applications" }, "out_bookings": { "type": [ "number", "null" ], "description": "out bookings" }, "out_meetings": { "type": [ "number", "null" ], "description": "out meetings" }, "out_meetings_present": { "type": [ "number", "null" ], "description": "out meetings present" }, "out_meetings_no_show": { "type": [ "number", "null" ], "description": "out meetings no show" }, "out_sales": { "type": [ "number", "null" ], "description": "out sales" }, "out_revenue": { "type": [ "number", "null" ], "description": "out revenue" }, "out_show_rate": { "type": [ "number", "null" ], "description": "out show rate" }, "out_close_rate": { "type": [ "number", "null" ], "description": "out close rate" }, "out_rep_names": { "type": [ "string", "null" ], "description": "out rep names" }, "out_sales_ft": { "type": [ "number", "null" ], "description": "Sales, first touch" }, "out_revenue_ft": { "type": [ "number", "null" ], "description": "Revenue, first touch" }, "out_sales_lt": { "type": [ "number", "null" ], "description": "Sales, last touch" }, "out_revenue_lt": { "type": [ "number", "null" ], "description": "Revenue, last touch" }, "out_sales_assisted": { "type": [ "number", "null" ], "description": "out sales assisted" }, "out_revenue_assisted": { "type": [ "number", "null" ], "description": "out revenue assisted" }, "out_refund_amount": { "type": [ "number", "null" ], "description": "out refund amount" }, "out_dispute_amount": { "type": [ "number", "null" ], "description": "out dispute amount" }, "out_net_revenue": { "type": [ "number", "null" ], "description": "out net revenue" }, "out_is_excluded": { "type": [ "boolean", "null" ], "description": "out is excluded" } }, "additionalProperties": true }, "AttributionHealth": { "type": "object", "description": "Capture health of the attribution.", "properties": { "verdict": { "type": [ "string", "null" ], "description": "verdict" }, "events_pub_30j": { "type": [ "number", "null" ], "description": "Ad-sourced events, last 30 days" }, "pct_exact_id": { "type": [ "number", "null" ], "description": "Share matched by exact ad id" }, "pct_par_nom": { "type": [ "number", "null" ], "description": "Share matched by name" }, "pct_non_resolu": { "type": [ "number", "null" ], "description": "Share unresolved" }, "pixel_sessions_30j": { "type": [ "number", "null" ], "description": "pixel sessions 30j" }, "pixel_derniere_activite": { "type": [ "string", "null" ], "description": "Last pixel activity" }, "pixel_pct_avec_id": { "type": [ "number", "null" ], "description": "pixel pct avec id" }, "issues": { "type": [ "string", "null" ], "description": "Detected issues" } }, "additionalProperties": true }, "AttributionReportRow": { "type": "object", "description": "Attribution report per source, campaign and ad.", "properties": { "out_source": { "type": [ "string", "null" ], "description": "out source" }, "out_campaign": { "type": [ "string", "null" ], "description": "out campaign" }, "out_ad_id": { "type": [ "string", "null" ], "description": "out ad id" }, "out_ad_name": { "type": [ "string", "null" ], "description": "out ad name" }, "out_spend": { "type": [ "number", "null" ], "description": "out spend" }, "out_gross_revenue": { "type": [ "number", "null" ], "description": "out gross revenue" }, "out_refund_amount": { "type": [ "number", "null" ], "description": "out refund amount" }, "out_dispute_amount": { "type": [ "number", "null" ], "description": "out dispute amount" }, "out_net_revenue": { "type": [ "number", "null" ], "description": "out net revenue" }, "out_roi_gross": { "type": [ "number", "null" ], "description": "out roi gross" }, "out_roi_net": { "type": [ "number", "null" ], "description": "out roi net" }, "out_touchpoints": { "type": [ "number", "null" ], "description": "out touchpoints" } }, "additionalProperties": true }, "Event": { "type": "object", "description": "One CRM event, newest first.", "properties": { "id": { "type": [ "string", "null" ], "description": "id" }, "event_type": { "type": [ "string", "null" ], "description": "event type" }, "event_datetime": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp; pass the last one as cursor for the next page" }, "contact_email": { "type": [ "string", "null" ], "description": "contact email" }, "contact_name": { "type": [ "string", "null" ], "description": "contact name" }, "contact_phone": { "type": [ "string", "null" ], "description": "contact phone" }, "contact_id": { "type": [ "string", "null" ], "description": "contact id" }, "value": { "type": [ "number", "null" ], "description": "value" }, "amount": { "type": [ "number", "null" ], "description": "amount" }, "product_key": { "type": [ "string", "null" ], "description": "product key" }, "product_name": { "type": [ "string", "null" ], "description": "product name" }, "assigned_user_name": { "type": [ "string", "null" ], "description": "assigned user name" }, "is_paid": { "type": [ "boolean", "null" ], "description": "is paid" }, "payment_status": { "type": [ "string", "null" ], "description": "payment status" }, "booking_date": { "type": [ "string", "null" ], "description": "booking date" }, "booking_time": { "type": [ "string", "null" ], "description": "booking time" }, "utm_source": { "type": [ "string", "null" ], "description": "utm source" }, "utm_campaign": { "type": [ "string", "null" ], "description": "utm campaign" }, "utm_content": { "type": [ "string", "null" ], "description": "utm content" }, "campaign_name": { "type": [ "string", "null" ], "description": "campaign name" }, "calendar_name": { "type": [ "string", "null" ], "description": "calendar name" }, "meta_ad_id": { "type": [ "string", "null" ], "description": "meta ad id" }, "is_baseline": { "type": [ "boolean", "null" ], "description": "is baseline" }, "cancelled_at": { "type": [ "string", "null" ], "description": "cancelled at" }, "has_more": { "type": [ "boolean", "null" ], "description": "True when a next page exists" }, "counted": { "type": [ "boolean", "null" ], "description": "counted" }, "drop_reason": { "type": [ "string", "null" ], "description": "drop reason" }, "group_key": { "type": [ "string", "null" ], "description": "group key" }, "contact_seq": { "type": [ "integer", "null" ], "description": "contact seq" } }, "additionalProperties": true }, "EventSummaryRow": { "type": "object", "description": "Event counts per ad and campaign.", "properties": { "ad_name": { "type": [ "string", "null" ], "description": "ad name" }, "campaign_name": { "type": [ "string", "null" ], "description": "campaign name" }, "leads": { "type": [ "number", "null" ], "description": "leads" }, "applications": { "type": [ "number", "null" ], "description": "applications" }, "bookings": { "type": [ "number", "null" ], "description": "bookings" }, "sales": { "type": [ "number", "null" ], "description": "sales" }, "no_shows": { "type": [ "number", "null" ], "description": "no shows" }, "cancellations": { "type": [ "number", "null" ], "description": "cancellations" }, "total_value": { "type": [ "number", "null" ], "description": "total value" } }, "additionalProperties": true }, "SalesSummary": { "type": "object", "description": "Sales KPIs, pipeline and no-show.", "properties": {}, "additionalProperties": true }, "RepRow": { "type": "object", "description": "Performance of one sales rep.", "properties": { "rep_name": { "type": [ "string", "null" ], "description": "rep name" }, "bookings": { "type": [ "number", "null" ], "description": "bookings" }, "meetings": { "type": [ "number", "null" ], "description": "meetings" }, "shows": { "type": [ "number", "null" ], "description": "shows" }, "no_shows": { "type": [ "number", "null" ], "description": "no shows" }, "sales": { "type": [ "number", "null" ], "description": "sales" }, "revenue": { "type": [ "number", "null" ], "description": "revenue" }, "close_rate": { "type": [ "number", "null" ], "description": "close rate" }, "no_show_rate": { "type": [ "number", "null" ], "description": "no show rate" }, "ticket_moyen": { "type": [ "number", "null" ], "description": "Average sale value" }, "contacts_met": { "type": [ "number", "null" ], "description": "contacts met" }, "contacts_closed": { "type": [ "number", "null" ], "description": "contacts closed" } }, "additionalProperties": true }, "SalesCycle": { "type": "object", "description": "Time from first touch to sale.", "properties": { "avg_days": { "type": "number", "description": "Average days" }, "median_days": { "type": "number", "description": "Median days" }, "p25_days": { "type": "number", "description": "25th percentile" }, "p75_days": { "type": "number", "description": "75th percentile" }, "sample_size": { "type": "integer", "description": "Sample size" }, "conversions": { "type": "number", "description": "Conversions" }, "weekly_trend": { "type": "array", "description": "Weekly trend", "items": { "type": "object", "description": "One week", "properties": {}, "additionalProperties": true } } }, "additionalProperties": true }, "Pnl": { "type": "object", "description": "Profit and loss. Margin, profit, wholesale, markup, cost_of and cogs fields are stripped.", "properties": {}, "additionalProperties": true }, "Funnel": { "type": "object", "description": "Funnel stages, conversion by source, campaign and product, time to conversion.", "properties": {}, "additionalProperties": true }, "Contact": { "type": "object", "description": "One contact.", "properties": { "email": { "type": [ "string", "null" ], "description": "email" }, "total_events": { "type": [ "integer", "null" ], "description": "total events" }, "event_types": { "type": [ "string", "null" ], "description": "event types" }, "first_event_date": { "type": [ "string", "null" ], "description": "first event date" }, "last_event_date": { "type": [ "string", "null" ], "description": "last event date" }, "name": { "type": [ "string", "null" ], "description": "name" }, "phone": { "type": [ "string", "null" ], "description": "phone" }, "sources": { "type": [ "string", "null" ], "description": "sources" }, "assigned_user_name": { "type": [ "string", "null" ], "description": "assigned user name" }, "value": { "type": [ "number", "null" ], "description": "value" }, "form_titles": { "type": [ "string", "null" ], "description": "form titles" }, "has_campaign": { "type": [ "boolean", "null" ], "description": "has campaign" }, "tags": { "type": [ "string", "null" ], "description": "tags" }, "form_response": { "type": [ "string", "null" ], "description": "form response" } }, "additionalProperties": true }, "Customer": { "type": "object", "description": "One customer.", "properties": { "id": { "type": [ "string", "null" ], "description": "id" }, "contact_email": { "type": [ "string", "null" ], "description": "contact email" }, "contact_name": { "type": [ "string", "null" ], "description": "contact name" }, "contact_phone": { "type": [ "string", "null" ], "description": "contact phone" }, "contact_id": { "type": [ "string", "null" ], "description": "contact id" }, "first_event_type": { "type": [ "string", "null" ], "description": "first event type" }, "first_event_date": { "type": [ "string", "null" ], "description": "first event date" }, "latest_lead_date": { "type": [ "string", "null" ], "description": "latest lead date" }, "first_payment_date": { "type": [ "string", "null" ], "description": "first payment date" }, "commission_status": { "type": [ "string", "null" ], "description": "commission status" }, "commission_expires_at": { "type": [ "string", "null" ], "description": "commission expires at" }, "total_revenue": { "type": [ "number", "null" ], "description": "total revenue" }, "total_purchases": { "type": [ "integer", "null" ], "description": "total purchases" }, "total_commission": { "type": [ "number", "null" ], "description": "total commission" }, "products": { "type": [ "string", "null" ], "description": "products" }, "created_at": { "type": [ "string", "null" ], "description": "created at" } }, "additionalProperties": true }, "Purchase": { "type": "object", "description": "One purchase.", "properties": { "id": { "type": [ "string", "null" ], "description": "id" }, "purchase_date": { "type": [ "string", "null" ], "description": "purchase date" }, "product_key": { "type": [ "string", "null" ], "description": "product key" }, "product_name": { "type": [ "string", "null" ], "description": "product name" }, "contact_email": { "type": [ "string", "null" ], "description": "contact email" }, "contact_name": { "type": [ "string", "null" ], "description": "contact name" }, "amount": { "type": [ "number", "null" ], "description": "amount" }, "commissionable": { "type": [ "boolean", "null" ], "description": "commissionable" }, "commission_rate": { "type": [ "number", "null" ], "description": "commission rate" }, "commission_amount": { "type": [ "number", "null" ], "description": "commission amount" }, "invoice_id": { "type": [ "string", "null" ], "description": "invoice id" } }, "additionalProperties": true }, "Call": { "type": "object", "description": "One analyzed call, newest first.", "properties": { "artifact_id": { "type": "integer", "description": "Call identifier, used as id by getCallTranscript and getCallRecording" }, "starts_at": { "type": "string", "description": "Start time, ISO 8601" }, "title": { "type": "string", "description": "Title" }, "duration_sec": { "type": "integer", "description": "Duration in seconds" }, "call_analysis_id": { "type": [ "string", "null" ], "description": "Analysis identifier" }, "summary": { "type": [ "string", "null" ], "description": "Summary" }, "call_type": { "type": [ "string", "null" ], "description": "Call type" }, "is_qualified": { "type": [ "boolean", "null" ], "description": "Qualified prospect" }, "icp_fit_score": { "type": [ "number", "null" ], "description": "ICP fit score" }, "qualification_reasoning": { "type": [ "string", "null" ], "description": "Qualification reasoning" }, "next_step_type": { "type": [ "string", "null" ], "description": "Next step type" }, "next_step_summary": { "type": [ "string", "null" ], "description": "Next step summary" }, "next_step_proposed": { "type": [ "string", "null" ], "description": "Proposed next step" }, "scorecard_total": { "type": [ "number", "null" ], "description": "Scorecard total" }, "rep_id": { "type": [ "string", "null" ], "description": "Rep identifier" }, "contact_email": { "type": "string", "description": "Only on getContactCalls" }, "markers": { "type": "array", "description": "Timeline markers", "items": { "type": "object", "description": "Marker", "properties": { "ts": { "type": "number", "description": "Timestamp" }, "label": { "type": "string", "description": "Label" }, "status": { "type": "string", "description": "Status" } }, "additionalProperties": true } } }, "additionalProperties": true }, "TranscriptSegment": { "type": "object", "description": "One transcript segment, in order.", "properties": { "idx": { "type": "integer", "description": "Order" }, "start_ms": { "type": "integer", "description": "Start, ms" }, "end_ms": { "type": "integer", "description": "End, ms" }, "speaker_id": { "type": [ "string", "null" ], "description": "Speaker id" }, "speaker_label": { "type": [ "string", "null" ], "description": "Speaker label" }, "speaker_email": { "type": [ "string", "null" ], "description": "Speaker email" }, "text": { "type": "string", "description": "Text" }, "confidence": { "type": [ "number", "null" ], "description": "Confidence" } }, "additionalProperties": true }, "CallRecording": { "type": "object", "description": "Signed download URLs valid for one hour.", "properties": { "artifact_id": { "type": "integer", "description": "Call identifier" }, "content_type": { "type": "string", "description": "Media type" }, "expires_in": { "type": "integer", "description": "Seconds before the URLs expire (3600)" }, "audio_url": { "type": [ "string", "null" ], "description": "Signed audio URL" }, "video_url": { "type": [ "string", "null" ], "description": "Signed video URL" }, "has_video": { "type": "boolean", "description": "Whether a video exists" } }, "additionalProperties": true }, "Utm": { "type": "object", "description": "UTM captured at a touchpoint.", "properties": { "source": { "type": [ "string", "null" ], "description": "source" }, "medium": { "type": [ "string", "null" ], "description": "medium" }, "campaign": { "type": [ "string", "null" ], "description": "campaign" }, "content": { "type": [ "string", "null" ], "description": "content" }, "term": { "type": [ "string", "null" ], "description": "term" }, "campaign_name": { "type": [ "string", "null" ], "description": "campaign_name" }, "adset_name": { "type": [ "string", "null" ], "description": "adset_name" }, "ad_name": { "type": [ "string", "null" ], "description": "ad_name" }, "channel": { "type": [ "string", "null" ], "description": "channel" }, "type": { "type": [ "string", "null" ], "description": "type" }, "sequence": { "type": [ "string", "null" ], "description": "sequence" }, "step": { "type": [ "string", "null" ], "description": "step" } }, "additionalProperties": true }, "Paging": { "type": "object", "description": "Pagination state.", "properties": { "limit": { "type": "integer", "description": "Limit" }, "offset": { "type": "integer", "description": "Offset" }, "returned": { "type": "integer", "description": "Rows returned" } }, "additionalProperties": true }, "Journeys": { "type": "object", "description": "Customer journeys.", "properties": { "coverage": { "type": "object", "description": "Since when web touchpoints exist.", "properties": { "web_touchpoints_since": { "type": [ "string", "null" ], "description": "Date" } }, "additionalProperties": true }, "paging": { "$ref": "#/components/schemas/Paging" }, "journeys": { "type": "array", "description": "One item per contact", "items": { "type": "object", "description": "Journey", "properties": { "contact": { "type": "object", "description": "Contact", "properties": { "email": { "type": "string", "description": "Email" }, "phone": { "type": [ "string", "null" ], "description": "Phone" }, "first_name": { "type": [ "string", "null" ], "description": "First name" }, "last_name": { "type": [ "string", "null" ], "description": "Last name" } }, "additionalProperties": true }, "first_seen_at": { "type": "string", "description": "First seen" }, "last_seen_at": { "type": "string", "description": "Last seen" }, "first_touch": { "type": "object", "description": "First touch", "properties": { "utm": { "$ref": "#/components/schemas/Utm" } }, "additionalProperties": true }, "last_touch": { "type": "object", "description": "Last touch", "properties": { "utm": { "$ref": "#/components/schemas/Utm" } }, "additionalProperties": true }, "touchpoint_counts": { "type": "object", "description": "Counts", "properties": { "web": { "type": "integer", "description": "Web" }, "conversion": { "type": "integer", "description": "Conversion" }, "total": { "type": "integer", "description": "Total" } }, "additionalProperties": true }, "milestones": { "type": "object", "description": "Milestones", "properties": {}, "additionalProperties": true }, "event_types_seen": { "type": "array", "description": "Event types", "items": { "type": "string", "description": "Event type" } } }, "additionalProperties": true } } }, "additionalProperties": true }, "ContactJourney": { "type": "object", "description": "Full touchpoint chain of one contact.", "properties": { "contact": { "type": "object", "description": "Contact", "properties": {}, "additionalProperties": true }, "first_touch_at": { "type": [ "string", "null" ], "description": "First touch" }, "last_touch_at": { "type": [ "string", "null" ], "description": "Last touch" }, "counts": { "type": "object", "description": "Counts", "properties": { "total": { "type": "integer", "description": "Total" }, "web": { "type": "integer", "description": "Web" }, "conversion": { "type": "integer", "description": "Conversion" }, "page_view": { "type": "integer", "description": "Page views" } }, "additionalProperties": true }, "touchpoints": { "type": "array", "description": "Chronological touchpoints", "items": { "type": "object", "description": "Touchpoint", "properties": { "utm": { "$ref": "#/components/schemas/Utm" } }, "additionalProperties": true } } }, "additionalProperties": true }, "Touchpoints": { "type": "object", "description": "Touchpoint feed, newest first.", "properties": { "paging": { "$ref": "#/components/schemas/Paging" }, "touchpoints": { "type": "array", "description": "Touchpoints", "items": { "type": "object", "description": "Touchpoint", "properties": { "utm": { "$ref": "#/components/schemas/Utm" }, "ad_ids": { "type": "object", "description": "Ad ids", "properties": {}, "additionalProperties": true }, "click_ids": { "type": "object", "description": "Click ids", "properties": {}, "additionalProperties": true }, "channel": { "type": [ "string", "null" ], "description": "Channel" }, "value": { "type": [ "number", "null" ], "description": "Value" }, "currency": { "type": [ "string", "null" ], "description": "Currency" }, "product": { "type": [ "string", "null" ], "description": "Product" }, "is_imported": { "type": "boolean", "description": "Imported" } }, "additionalProperties": true } }, "error": { "type": "string", "description": "Only when kind is invalid" } }, "additionalProperties": true }, "CreativeRequest": { "type": "object", "description": "A creative need written by DURUM when creatives are missing.", "properties": { "id": { "type": "string", "description": "UUID", "format": "uuid" }, "reason": { "type": "string", "description": "Reason" }, "status": { "type": "string", "description": "open, partial, filled..." }, "requested_count": { "type": "integer", "description": "Creatives requested" }, "filled_count": { "type": "integer", "description": "Creatives received" }, "context": { "type": "object", "description": "Context", "properties": {}, "additionalProperties": true }, "created_at": { "type": "string", "description": "Created at" }, "notified_at": { "type": [ "string", "null" ], "description": "When it was relayed to a team" } }, "additionalProperties": true }, "IcpCriteria": { "type": "object", "description": "Your ideal customer profile criteria.", "properties": {}, "additionalProperties": true }, "Pixels": { "type": "object", "description": "Connected Meta pixels and the default one. Tokens are never returned.", "properties": {}, "additionalProperties": true }, "ApiIndex": { "type": "object", "description": "Self-documenting index of the API.", "properties": { "service": { "type": "string", "description": "Service name" }, "version": { "type": "string", "description": "API version" }, "base_url": { "type": "string", "description": "Base URL" }, "docs": { "type": "string", "description": "Documentation URL" }, "auth": { "type": "string", "description": "How to authenticate" }, "read_routes": { "type": "array", "description": "Read routes", "items": { "type": "object", "description": "Route", "properties": { "method": { "type": "string", "description": "HTTP method" }, "path": { "type": "string", "description": "Full path" }, "scope": { "type": "string", "description": "Required scope" } }, "additionalProperties": true } }, "write_routes": { "type": "array", "description": "Write routes", "items": { "type": "object", "description": "Route", "properties": { "method": { "type": "string", "description": "HTTP method" }, "path": { "type": "string", "description": "Full path" }, "scope": { "type": "string", "description": "Required scope" } }, "additionalProperties": true } } }, "additionalProperties": true }, "ToolsManifest": { "type": "object", "description": "Tools available to this key.", "properties": { "tools": { "type": "array", "description": "Tools", "items": { "type": "object", "description": "Tool", "properties": { "name": { "type": "string", "description": "Tool name" }, "method": { "type": "string", "description": "HTTP method" }, "path": { "type": "string", "description": "Path" }, "scope": { "type": "string", "description": "Scope" }, "inputSchema": { "type": "object", "description": "JSON Schema of the parameters", "properties": {}, "additionalProperties": true } }, "additionalProperties": true } } }, "additionalProperties": true }, "Success": { "type": "object", "description": "Write acknowledged.", "properties": { "success": { "type": "boolean", "description": "Always true" } }, "additionalProperties": true } }, "responses": { "BadRequest": { "description": "Invalid parameter or body; error holds the message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "invalid_or_missing_api_key: header missing, key malformed, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "insufficient_scope (see required), plan_free_no_api (Discovery plan) or forbidden (resource of another account).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "unknown_route, not_found or no_recording_available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "MethodNotAllowed": { "description": "method_not_allowed: method not supported for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "rate_limited (600 requests per minute per key) or too_many_failed_attempts; wait retry_after_seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } }, "ServerError": { "description": "tenant_barrier (response blocked by the account check) or upstream_error (retry later).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }