{ "openapi": "3.1.0", "info": { "title": "Conversion API", "version": "2.0.0", "description": "The Conversion API lets you programmatically manage contacts, track custom events, and manage their associated data." }, "servers": [ { "url": "https://pub-api.conversion.ai/api" } ], "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Your Conversion API key. Found in **Settings > Integrations** in the dashboard. Format: `sk_live__`." }, "apiKeyQuery": { "type": "apiKey", "in": "query", "name": "api_key", "description": "Your Conversion API key, sent as a query parameter instead of the `X-API-Key` header. Prefer the header: URLs can end up in logs and browser history." } }, "schemas": { "FieldSchema": { "type": "object", "properties": { "key": { "type": "string", "description": "Key used in record field maps." }, "label": { "type": "string" }, "objectType": { "type": "string", "enum": [ "CONTACT", "COMPANY", "OPPORTUNITY", "CAMPAIGN", "CAMPAIGN_MEMBER", "CUSTOM_OBJECT" ] }, "customObjectId": { "type": "string", "format": "uuid", "description": "Present for custom-object fields." }, "dataType": { "type": "string", "enum": [ "STRING", "NUMBER", "BOOLEAN", "DATE", "DATETIME", "PICKLIST", "RELATIONSHIP" ] }, "readOnly": { "type": "boolean", "description": "Whether this field is unavailable for writes through the custom-object batch endpoint." }, "relationshipTargets": { "type": "array", "items": { "$ref": "#/components/schemas/RelationshipFieldReference" }, "description": "Fields on the other side of this relationship, identified by key and object. For a reverse field, this points to its writable source field." } }, "required": [ "key", "label", "objectType", "dataType", "readOnly" ] }, "RelationshipFieldReference": { "type": "object", "properties": { "key": { "type": "string" }, "objectType": { "type": "string", "enum": [ "CONTACT", "COMPANY", "OPPORTUNITY", "CAMPAIGN", "CAMPAIGN_MEMBER", "CUSTOM_OBJECT" ] }, "customObjectId": { "type": "string", "format": "uuid" } }, "required": [ "key", "objectType" ] }, "RelationshipFieldSide": { "type": "object", "properties": { "objectType": { "type": "string", "enum": [ "CONTACT", "COMPANY", "OPPORTUNITY", "CAMPAIGN", "CAMPAIGN_MEMBER", "CUSTOM_OBJECT" ] }, "customObjectId": { "type": "string", "format": "uuid", "description": "Required when objectType is CUSTOM_OBJECT; omit for standard objects." }, "key": { "type": "string", "description": "Required field key. Leading and trailing whitespace is trimmed. Use letters, numbers, or underscores, including Unicode letters." }, "label": { "type": "string", "description": "Display name; leading and trailing whitespace is trimmed." } }, "required": [ "objectType", "key", "label" ] }, "SubscriptionStatus": { "type": "string", "enum": ["SUBSCRIBED", "UNSUBSCRIBED", "NO_STATUS"], "description": "The contact's email subscription status. System-managed statuses (`BOUNCED`, `COMPLAINED`, etc.) cannot be set through the API." }, "Error": { "type": "object", "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string", "description": "A machine-readable error code.", "examples": ["invalid_email"] }, "message": { "type": "string", "description": "A human-readable error description.", "examples": ["invalid email format: not-an-email"] } } } } }, "ContactFields": { "type": "object", "additionalProperties": {}, "description": "A map of contact field keys to values. Keys must match existing field definitions in your Conversion account.", "examples": [ { "first_name": "Jane", "last_name": "Smith", "job_title": "VP of Marketing" } ] }, "CompanyFields": { "type": "object", "additionalProperties": {}, "description": "A map of company field keys to values for the contact's associated company.", "examples": [ { "company_name": "Acme Corp", "industry": "Technology" } ] }, "Contact": { "type": "object", "required": [ "cnvContactId", "fields", "createdAt", "updatedAt" ], "properties": { "cnvContactId": { "type": "string", "format": "uuid", "description": "The Conversion contact ID." }, "email": { "type": [ "string", "null" ], "format": "email", "description": "The contact's email address, or `null` when not set." }, "userId": { "type": [ "string", "null" ], "description": "An external user identifier for the contact, or `null` when not set." }, "subscriptionStatus": { "$ref": "#/components/schemas/SubscriptionStatus" }, "fields": { "$ref": "#/components/schemas/ContactFields" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the contact was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the contact was last updated." } } } } }, "paths": { "/v2/contacts": { "post": { "operationId": "upsertContact", "summary": "Upsert Contact", "description": "Create a new contact or update an existing one. Contacts are identified by `email` or `cnvContactId`. If the contact exists, its fields are updated; if not, a new contact is created.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "The contact's email address. At least one of `email` or `cnvContactId` is required. When both are provided, `cnvContactId` identifies the contact and `email` updates the contact's email address.", "examples": ["jane@example.com"] }, "cnvContactId": { "type": "string", "format": "uuid", "description": "The Conversion contact ID. Use this to identify an existing contact by its internal ID instead of email. At least one of `email` or `cnvContactId` is required.", "examples": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"] }, "subscriptionStatus": { "$ref": "#/components/schemas/SubscriptionStatus" }, "fields": { "$ref": "#/components/schemas/ContactFields" }, "companyFields": { "$ref": "#/components/schemas/CompanyFields" }, "updateOnly": { "type": "boolean", "default": false, "description": "When `true`, restricts the operation to updates only. Returns a `contact_not_found` error if no existing contact matches the provided identifier." }, "syncToCRM": { "type": "boolean", "default": false, "description": "When `true`, syncs the contact to the connected CRM (e.g., Salesforce) if the contact does not already have an external CRM record." }, "preserveExistingFields": { "type": "boolean", "default": false, "description": "When `true`, prevents overwriting existing non-empty field values. New values are only written to fields that are currently empty or unset. Useful for enrichment workflows." } } }, "examples": { "create-with-fields": { "summary": "Create contact with fields", "value": { "email": "jane@example.com", "subscriptionStatus": "SUBSCRIBED", "fields": { "first_name": "Jane", "last_name": "Smith", "job_title": "VP of Marketing" }, "companyFields": { "company_name": "Acme Corp" } } }, "update-by-id": { "summary": "Update by contact ID", "value": { "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "fields": { "job_title": "Director of Marketing" } } }, "enrich": { "summary": "Enrich without overwriting", "value": { "email": "jane@example.com", "preserveExistingFields": true, "fields": { "first_name": "Jane", "last_name": "Smith", "phone": "+1-555-0100" } } } } } } }, "responses": { "200": { "description": "Contact upserted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": ["cnvContactId", "contactCreated"], "properties": { "cnvContactId": { "type": "string", "format": "uuid", "description": "The Conversion contact ID of the created or updated contact." }, "contactCreated": { "type": "boolean", "description": "`true` if a new contact was created, `false` if an existing contact was updated." } } } } }, "examples": { "created": { "summary": "Contact created", "value": { "data": { "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "contactCreated": true } } }, "updated": { "summary": "Contact updated", "value": { "data": { "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "contactCreated": false } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing-identifier": { "summary": "Missing identifier", "value": { "error": { "code": "missing_identifier", "message": "either 'email' or 'cnvContactId' is required" } } }, "invalid-email": { "summary": "Invalid email", "value": { "error": { "code": "invalid_email", "message": "invalid email format: not-an-email" } } }, "invalid-field": { "summary": "Unknown field", "value": { "error": { "code": "invalid_field", "message": "field 'nonexistent_key' does not exist" } } }, "invalid-subscription-status": { "summary": "Invalid subscription status", "value": { "error": { "code": "invalid_subscription_status", "message": "invalid subscription status value" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "404": { "description": "Contact not found (when `updateOnly` is true).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not-found": { "summary": "Contact not found", "value": { "error": { "code": "contact_not_found", "message": "no contact found with the provided identifier" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to upsert contact" } } } } } } } } }, "get": { "operationId": "getContact", "summary": "Get Contact", "description": "Fetch a single contact by `email` or `cnvContactId`. Provide exactly one identifier; `cnvContactId` takes precedence when both are provided.\n\nWhen looking up by `email`, the most recently updated contact with that email address is returned.\n\n> **Request access.** This endpoint is not enabled by default, contact the Conversion team to request access. Calls from accounts without it return `403 export_not_enabled`.", "parameters": [ { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "format": "email" }, "description": "The contact's email address. When multiple contacts share the same email, the most recently updated contact is returned.", "examples": { "example": { "value": "jane@example.com" } } }, { "name": "cnvContactId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "The Conversion contact ID.", "examples": { "example": { "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } ], "responses": { "200": { "description": "Contact retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "contact" ], "properties": { "contact": { "$ref": "#/components/schemas/Contact" } } } } }, "examples": { "found": { "summary": "Contact found", "value": { "data": { "contact": { "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "email": "jane@example.com", "userId": "user_12345", "subscriptionStatus": "SUBSCRIBED", "fields": { "first_name": "Jane", "last_name": "Smith", "job_title": "VP of Marketing" }, "createdAt": "2026-01-10T08:00:00Z", "updatedAt": "2026-02-03T14:22:05Z" } } } } } } } }, "400": { "description": "The request was malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing-identifier": { "summary": "Missing identifier", "value": { "error": { "code": "missing_identifier", "message": "at least one of email or cnvContactId is required" } } }, "invalid-email": { "summary": "Invalid email", "value": { "error": { "code": "invalid_email", "message": "invalid email format: not-an-email" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "403": { "description": "This endpoint is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not-enabled": { "summary": "Endpoint not enabled", "value": { "error": { "code": "export_not_enabled", "message": "business is not authorized to use this endpoint" } } } } } } }, "404": { "description": "The contact was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "contact-not-found": { "summary": "Contact not found", "value": { "error": { "code": "contact_not_found", "message": "no contact found matching the provided identifier" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to get contact" } } } } } } } } } }, "/v2/contacts/batch": { "post": { "operationId": "batchUpsertContacts", "summary": "Batch Upsert Contacts", "description": "Create or update up to 1,000 contacts in a single request, with a result for each contact. Optionally pass `audienceId` to add successfully upserted contacts to a static audience.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contacts" ], "properties": { "contacts": { "type": "array", "minItems": 1, "maxItems": 1000, "description": "An array of contact objects to upsert.", "items": { "type": "object", "description": "A single contact to upsert. Provide at least one of `email`, `cnvContactId`, or `userId`. Matching prioritizes `cnvContactId`, then `userId`, then email.", "properties": { "email": { "type": "string", "format": "email", "description": "The contact's email address. Required when creating a new contact; updates the email when matching an existing contact by ID.", "examples": [ "jane@example.com" ] }, "cnvContactId": { "type": "string", "format": "uuid", "description": "The Conversion contact ID. Takes precedence over `userId` and email when identifying an existing contact.", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "userId": { "type": "string", "description": "Your stable contact identifier, scoped to your workspace. If unmatched, email can match a contact with no user ID and assign this ID; a different existing user ID creates a separate contact unless `updateOnly` is true. Blank values are ignored and do not clear the ID.", "examples": ["user_12345"] }, "subscriptionStatus": { "$ref": "#/components/schemas/SubscriptionStatus" }, "fields": { "$ref": "#/components/schemas/ContactFields" }, "companyFields": { "$ref": "#/components/schemas/CompanyFields" } } } }, "updateOnly": { "type": "boolean", "default": false, "description": "When `true`, restricts all operations to updates only. Contacts that are not found will be returned with a `contact_not_found` error in their result item." }, "syncToCRM": { "type": "boolean", "default": false, "description": "When `true`, syncs upserted contacts to the connected CRM (e.g., Salesforce) if they do not already have an external CRM record." }, "preserveExistingFields": { "type": "boolean", "default": false, "description": "When `true`, prevents overwriting existing non-empty field values for all contacts in the batch. New values are only written to fields that are currently empty or unset." }, "audienceId": { "type": "string", "format": "uuid", "description": "Optional Conversion static audience ID. Add successfully upserted contacts to this audience. The audience must belong to the API key workspace." } } }, "examples": { "basic": { "summary": "Basic batch upsert", "value": { "contacts": [ { "email": "jane@example.com", "subscriptionStatus": "SUBSCRIBED", "fields": { "first_name": "Jane", "last_name": "Smith" } }, { "email": "bob@example.com", "subscriptionStatus": "SUBSCRIBED", "fields": { "first_name": "Bob", "last_name": "Jones" }, "companyFields": { "company_name": "Acme Corp" } } ] } }, "enrichment": { "summary": "Enrichment mode", "value": { "preserveExistingFields": true, "contacts": [ { "email": "jane@example.com", "fields": { "first_name": "Jane", "phone": "+1-555-0100" } } ] } }, "audience": { "summary": "Upsert contacts and add audience membership", "value": { "audienceId": "8e112222-3333-4444-8555-666677778888", "contacts": [ { "email": "jane@example.com", "fields": { "first_name": "Jane" } } ] } } } } } }, "responses": { "200": { "description": "Batch processed. Check data.failed and each result for contact or audience failures. An invalid audience is reported for each contact before any writes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "processed", "succeeded", "failed", "results" ], "properties": { "processed": { "type": "integer", "description": "The total number of contacts in the batch." }, "succeeded": { "type": "integer", "description": "The number of contacts with all requested operations completed." }, "failed": { "type": "integer", "description": "The number of contacts that failed." }, "results": { "type": "array", "description": "An array of result objects in the same order as the input `contacts` array.", "items": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "description": "True if the contact was upserted and, when audienceId is supplied, added to that audience." }, "cnvContactId": { "type": "string", "format": "uuid", "description": "The saved contact ID, including when the audience add fails." }, "contactCreated": { "type": "boolean", "description": "True if a new contact was created. Retained if the audience add fails." }, "error": { "type": "string", "description": "A machine-readable error code. Present on failure." }, "message": { "type": "string", "description": "A human-readable error description. Present on failure." } } } } } } } }, "examples": { "all-success": { "summary": "All contacts upserted", "value": { "data": { "processed": 2, "succeeded": 2, "failed": 0, "results": [ { "success": true, "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "contactCreated": true }, { "success": true, "cnvContactId": "f9e8d7c6-b5a4-3210-fedc-ba9876543210", "contactCreated": false } ] } } }, "partial-failure": { "summary": "Partial failure", "value": { "data": { "processed": 2, "succeeded": 1, "failed": 1, "results": [ { "success": true, "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "contactCreated": true }, { "success": false, "error": "invalid_email", "message": "invalid email format: not-an-email" } ] } } }, "audience-add-failure": { "summary": "Contact saved but audience add failed", "value": { "data": { "processed": 1, "succeeded": 0, "failed": 1, "results": [ { "success": false, "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "contactCreated": true, "error": "audience_add_failed", "message": "contact saved, but audience membership could not be confirmed" } ] } } } } } } }, "400": { "description": "Malformed request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid-request": { "summary": "Invalid request body", "value": { "error": { "code": "invalid_request", "message": "request validation failed" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "500": { "description": "An internal error prevented batch processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to upsert contacts" } } } } } } }, "403": { "description": "The API key lacks contact write permissions or edit access to the audience.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/events": { "post": { "operationId": "trackEvent", "summary": "Track Event", "description": "Record a custom event for a contact.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["event"], "properties": { "userId": { "type": "string", "description": "An external user identifier for the contact. At least one of `userId` or `email` is required. If `userId` matches a contact, that contact is used. If not, falls back to `email`. If the email matches a contact that has a different `userId`, a `conflicting_identifier` error is returned.", "examples": ["user_12345"] }, "email": { "type": "string", "format": "email", "description": "The contact's email address. At least one of `userId` or `email` is required.", "examples": ["jane@example.com"] }, "event": { "type": "string", "description": "The name of the custom event to track (e.g. `order_completed`, `log_in`). This is a freeform string.", "examples": ["page_viewed"] }, "eventId": { "type": "string", "description": "An optional client-generated identifier for the event. Use stable identifiers (like order IDs) to make retries idempotent: if an event with this ID already exists, the duplicate is ignored, the existing event is left unchanged, and the response reports success with `duplicate: true` and the original event's `cnvEventId`. If omitted, a new event is always created.", "examples": ["evt_abc123"] }, "data": { "type": "object", "additionalProperties": {}, "description": "An optional map of custom data to attach to the event.", "examples": [ { "product_id": "1234567890", "quantity": 2 } ] }, "timestamp": { "type": "string", "format": "date-time", "description": "An optional ISO 8601 timestamp for when the event occurred. Defaults to the current time if omitted.", "examples": ["2026-03-31T14:30:00Z"] }, "createContact": { "type": "boolean", "default": false, "description": "When `true`, creates the contact if no existing contact matches `userId` or `email`. Creating a contact requires an `email`.", "examples": [true] } } }, "examples": { "track-with-email": { "summary": "Track event by email", "value": { "email": "jane@example.com", "event": "log_in", "data": { "device": "mobile", "location": "US" } } }, "track-with-userId": { "summary": "Track event by userId", "value": { "userId": "user_12345", "event": "plan_upgraded", "data": { "plan": "pro", "annual": true } } }, "track-with-idempotency": { "summary": "Track event with idempotency key", "value": { "email": "jane@example.com", "event": "order_completed", "eventId": "evt_abc123", "data": { "product_id": "1234567890", "quantity": 2 }, "timestamp": "2026-03-31T14:30:00Z" } }, "track-and-create-contact": { "summary": "Track event and create the contact if missing", "value": { "userId": "user_67890", "email": "new-user@example.com", "event": "signed_up", "createContact": true } } } } } }, "responses": { "200": { "description": "Event tracked successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cnvEventId": { "type": "string", "format": "uuid", "description": "The Conversion engagement ID for the recorded event. For a duplicate, this is the ID of the originally recorded event." }, "cnvContactId": { "type": "string", "format": "uuid", "description": "The Conversion contact ID of the contact the event was recorded against. Omitted for duplicates." }, "duplicate": { "type": "boolean", "description": "`true` when an event with the same `eventId` was already tracked. The request is an idempotent no-op: the existing event is unchanged and no new event is created. Omitted when `false`." } } } } }, "examples": { "tracked": { "summary": "Event tracked", "value": { "data": { "cnvEventId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } }, "duplicate": { "summary": "Duplicate event (already tracked)", "value": { "data": { "cnvEventId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "duplicate": true } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing-identifier": { "summary": "Missing identifier", "value": { "error": { "code": "missing_identifier", "message": "either 'userId' or 'email' is required" } } }, "missing-event": { "summary": "Missing event name", "value": { "error": { "code": "missing_event", "message": "'event name' is required" } } }, "invalid-email": { "summary": "Invalid email", "value": { "error": { "code": "invalid_email", "message": "invalid email format: not-an-email" } } }, "missing-email": { "summary": "createContact without an email for a new contact", "value": { "error": { "code": "missing_email", "message": "'email' is required to create a contact that does not exist" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "404": { "description": "The contact could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "contact-not-found": { "summary": "Contact not found", "value": { "error": { "code": "contact_not_found", "message": "contact not found" } } }, "contact-id-not-found": { "summary": "Contact ID not found", "value": { "error": { "code": "contact_id_not_found", "message": "contact not found with the provided contactId" } } } } } } }, "409": { "description": "The provided identifiers conflict with an existing contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conflicting-identifier": { "summary": "Conflicting identifier", "value": { "error": { "code": "conflicting_identifier", "message": "contact found by email but has a different userId" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to track event" } } } } } } } } } }, "/v2/events/batch": { "post": { "operationId": "batchTrackEvents", "summary": "Batch Track Events", "description": "Record up to 200 custom events in a single request. Each event is processed independently.\n\nThe response includes summary counts and a per-event error list for any failures. Partial failures do not cause the entire request to fail.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["events"], "properties": { "events": { "type": "array", "minItems": 1, "maxItems": 200, "description": "An array of event objects to track.", "items": { "type": "object", "description": "A single event to track.", "required": ["event"], "properties": { "userId": { "type": "string", "description": "An external user identifier for the contact. At least one of `userId` or `email` is required. If `userId` matches a contact, that contact is used. If not, falls back to `email`. If the email matches a contact that has a different `userId`, a `conflicting_identifier` error is returned.", "examples": ["user_12345"] }, "email": { "type": "string", "format": "email", "description": "The contact's email address. At least one of `userId` or `email` is required.", "examples": ["jane@example.com"] }, "event": { "type": "string", "description": "The name of the custom event to track. This is a freeform string.", "examples": ["log_in"] }, "eventId": { "type": "string", "description": "An optional client-generated identifier for the event. Use stable identifiers (like order IDs) to make retries idempotent: if an event with this ID already exists, the duplicate is ignored, the existing event is left unchanged, and the response reports success with `duplicate: true` and the original event's `cnvEventId`. If omitted, a new event is always created.", "examples": ["evt_abc123"] }, "data": { "type": "object", "additionalProperties": {}, "description": "An optional map of custom data to attach to the event." }, "timestamp": { "type": "string", "format": "date-time", "description": "An optional ISO 8601 timestamp for when the event occurred. Defaults to the current time if omitted." }, "createContact": { "type": "boolean", "default": false, "description": "When `true`, creates the contact for this event if no existing contact matches `userId` or `email`. Overrides a `false` top-level `createContacts`. Creating a contact requires an `email`." } } } }, "createContacts": { "type": "boolean", "default": false, "description": "When `true`, creates the contact for every event in the batch whose `userId` or `email` matches no existing contact. Creating a contact requires an `email`.", "examples": [true] } } }, "examples": { "basic": { "summary": "Basic batch track", "value": { "events": [ { "email": "jane@example.com", "event": "log_in", "data": { "device": "mobile", "location": "US" }, "timestamp": "2026-03-31T14:30:00Z" }, { "userId": "user_12345", "event": "plan_upgraded", "data": { "plan": "pro" }, "timestamp": "2026-03-31T14:30:00Z" } ] } }, "create-missing-contacts": { "summary": "Batch track and create missing contacts", "value": { "createContacts": true, "events": [ { "email": "new-user@example.com", "userId": "user_67890", "event": "signed_up" }, { "email": "jane@example.com", "event": "log_in" } ] } } } } } }, "responses": { "200": { "description": "Batch processed. Check `errors` for individual failures.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": ["processed", "tracked", "failed", "results"], "properties": { "processed": { "type": "integer", "description": "Total number of events in the request." }, "tracked": { "type": "integer", "description": "Number of events successfully tracked, including idempotent duplicates of already-tracked events." }, "failed": { "type": "integer", "description": "Number of events that failed." }, "results": { "type": "array", "description": "An array of result objects in the same order as the input `events` array.", "items": { "type": "object", "required": ["success"], "properties": { "success": { "type": "boolean", "description": "`true` if the event was successfully tracked (including idempotent duplicates)." }, "cnvEventId": { "type": "string", "format": "uuid", "description": "The Conversion engagement ID. Present on success. For a duplicate, this is the ID of the originally recorded event." }, "cnvContactId": { "type": "string", "format": "uuid", "description": "The Conversion contact ID. Present on success, but omitted for duplicates." }, "duplicate": { "type": "boolean", "description": "`true` when an event with the same `eventId` was already tracked. The row is an idempotent no-op: the existing event is unchanged and no new event is created. Omitted when `false`." }, "error": { "type": "string", "description": "A machine-readable error code. Present on failure." }, "message": { "type": "string", "description": "A human-readable error description. Present on failure." } } } } } } } }, "examples": { "all-success": { "summary": "All events tracked", "value": { "data": { "processed": 2, "tracked": 2, "failed": 0, "results": [ { "success": true, "cnvEventId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, { "success": true, "cnvEventId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ] } } }, "partial-failure": { "summary": "Partial failure", "value": { "data": { "processed": 4, "tracked": 2, "failed": 2, "results": [ { "success": false, "error": "invalid_email", "message": "invalid email format: not-an-email" }, { "success": true, "cnvEventId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, { "success": false, "error": "contact_not_found", "message": "contact not found" }, { "success": true, "cnvEventId": "d4e5f6a7-b8c9-0123-def1-234567890123", "duplicate": true } ] } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to track events" } } } } } } } } } }, "/v2/fields": { "get": { "operationId": "listFields", "summary": "List Fields", "description": "List field definitions, including IDs, keys, data types, and relationship metadata. With no filters, returns standard-object fields. Pass `customObjectId` to list fields for one custom object. Requires field view permission and view access to that custom object.\n\nPass `pagination.nextCursor` as `cursor` for the next page. A null cursor means there are no more results.", "parameters": [ { "name": "objectType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "CONTACT", "COMPANY", "OPPORTUNITY", "CAMPAIGN", "CAMPAIGN_MEMBER", "CUSTOM_OBJECT" ] }, "description": "Optional object type, case-insensitive. CUSTOM_OBJECT requires customObjectId.", "examples": { "contact": { "value": "CONTACT" } } }, { "name": "customObjectId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "List fields for this custom object. Omit objectType or use CUSTOM_OBJECT." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "The maximum number of fields to return per page. Defaults to 50. Values are clamped to the range [1, 100] rather than rejected; values above 100 return 100 results." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The opaque pagination cursor returned as `pagination.nextCursor` by a previous call. Omit to fetch the first page. An invalid or malformed cursor returns an `invalid_cursor` error.", "examples": { "next-page": { "value": "eyJjcmVhdGVkQXQiOiIyMDI2LTAxLTE1VDEwOjMwOjAwWiJ9" } } } ], "responses": { "200": { "description": "Field schemas retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "fields" ], "properties": { "fields": { "type": "array", "description": "The current page of field schemas.", "items": { "$ref": "#/components/schemas/FieldSchema" } } } }, "pagination": { "type": "object", "required": [ "nextCursor" ], "properties": { "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or `null` when there are no more results. This is the single source of truth for whether more results exist." } } } } }, "examples": { "with-more-pages": { "summary": "More pages available", "value": { "data": { "fields": [ { "key": "first_name", "label": "First Name", "objectType": "CONTACT", "dataType": "STRING", "readOnly": false }, { "key": "annual_revenue", "label": "Annual Revenue", "objectType": "COMPANY", "dataType": "NUMBER", "readOnly": false } ] }, "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTAxLTE1VDEwOjMwOjAwWiJ9" } } }, "last-page": { "summary": "Last page", "value": { "data": { "fields": [ { "key": "signup_date", "label": "Signup Date", "objectType": "CONTACT", "dataType": "DATETIME", "readOnly": false } ] }, "pagination": { "nextCursor": null } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid-object-type": { "summary": "Unsupported object type", "value": { "error": { "code": "invalid_object_type", "message": "unsupported object type 'DEAL'; supported values: [CONTACT COMPANY OPPORTUNITY CAMPAIGN_MEMBER]" } } }, "invalid-cursor": { "summary": "Invalid cursor", "value": { "error": { "code": "invalid_cursor", "message": "invalid pagination cursor" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to load field schemas" } } } } } } }, "403": { "description": "The API key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Custom object not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createField", "summary": "Create Field", "description": "Create a field on a standard or custom object. Use `POST /v2/fields/relationships` to link two objects.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label", "objectType", "dataType" ], "properties": { "label": { "type": "string", "description": "The human-readable display name of the field.", "examples": [ "Lead Score" ] }, "key": { "type": "string", "description": "Key used in record field maps. Leading and trailing whitespace is trimmed. Use letters, numbers, or underscores, including Unicode letters. Optional; derived from the label when omitted, preserving Unicode letters. Must be unique within this object.", "examples": [ "lead_score" ] }, "objectType": { "type": "string", "enum": [ "CONTACT", "COMPANY", "OPPORTUNITY", "CAMPAIGN", "CAMPAIGN_MEMBER", "CUSTOM_OBJECT" ], "description": "The object the field belongs to (case-insensitive). An unsupported value returns an `invalid_object_type` error." }, "dataType": { "type": "string", "enum": [ "STRING", "NUMBER", "BOOLEAN", "DATE", "DATETIME", "PICKLIST" ], "description": "The data type of the field's value (case-insensitive)." }, "customObjectId": { "type": "string", "format": "uuid", "description": "Required for CUSTOM_OBJECT; omit for standard objects." } } }, "examples": { "create-contact-field": { "summary": "Create a contact field", "value": { "label": "Lead Score", "objectType": "CONTACT", "dataType": "NUMBER" } }, "create-with-explicit-key": { "summary": "Create with an explicit key", "value": { "key": "renewal_date", "label": "Renewal Date", "objectType": "COMPANY", "dataType": "DATE" } }, "custom-object": { "summary": "Create a custom-object field", "value": { "key": "dashboard_region", "label": "Dashboard Region", "objectType": "CUSTOM_OBJECT", "customObjectId": "f4f9ae15-12e8-4b3f-9822-22166d455f40", "dataType": "STRING" } } } } } }, "responses": { "200": { "description": "Field created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "field" ], "properties": { "field": { "$ref": "#/components/schemas/FieldSchema" } } } } }, "examples": { "created": { "summary": "Field created", "value": { "data": { "field": { "key": "lead_score", "label": "Lead Score", "objectType": "CONTACT", "dataType": "NUMBER", "readOnly": false } } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid-object-type": { "summary": "Unsupported object type", "value": { "error": { "code": "invalid_object_type", "message": "invalid objectType or customObjectId" } } }, "duplicate-key": { "summary": "Field key already exists", "value": { "error": { "code": "invalid_field", "message": "key already exists on this object" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "403": { "description": "The API key lacks permission, or custom objects are not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to create field" } } } } } } }, "404": { "description": "Custom object not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/fields/relationships": { "post": { "operationId": "createRelationshipField", "summary": "Create Relationship Fields", "description": "Create a field on `source` that links each record to one `target` record, plus a read-only reverse field on `target` that lists those records. This doesn't link any records.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/RelationshipFieldSide" }, "target": { "$ref": "#/components/schemas/RelationshipFieldSide" } }, "required": [ "source", "target" ] }, "example": { "source": { "objectType": "CUSTOM_OBJECT", "customObjectId": "528f0cc5-431c-4f3b-9d3c-7204740a3f76", "key": "organization", "label": "Organization" }, "target": { "objectType": "CUSTOM_OBJECT", "customObjectId": "f4f9ae15-12e8-4b3f-9822-22166d455f40", "key": "dashboard_users", "label": "Dashboard Users" } } } } }, "responses": { "200": { "description": "Relationship fields created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sourceField": { "$ref": "#/components/schemas/RelationshipFieldReference" }, "relatedFields": { "type": "array", "items": { "$ref": "#/components/schemas/RelationshipFieldReference" } } }, "required": [ "sourceField", "relatedFields" ] } } }, "example": { "data": { "sourceField": { "key": "organization", "objectType": "CUSTOM_OBJECT", "customObjectId": "528f0cc5-431c-4f3b-9d3c-7204740a3f76" }, "relatedFields": [ { "key": "dashboard_users", "objectType": "CUSTOM_OBJECT", "customObjectId": "f4f9ae15-12e8-4b3f-9822-22166d455f40" } ] } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks permission, or custom objects are not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/custom-objects/{customObjectId}/records/batch": { "post": { "operationId": "batchUpsertCustomObjectRecords", "summary": "Batch Upsert Custom Object Records", "description": "Create or update up to 200 records of one custom object in a single request, with a result for each record. Records are matched by `objectId`.", "parameters": [ { "name": "customObjectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the existing custom object created in Conversion." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "records": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "objectId": { "type": "string", "minLength": 1, "description": "Your system's ID for the record, unique within this custom object. Creates the record if no match exists, otherwise updates it. Repeated values in one batch are applied in order. Leading or trailing whitespace is rejected." }, "fields": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "description": "Existing field keys mapped to values. Omitted fields stay unchanged; null or an empty string clears a field. A relationship value names the related record by its `objectId`, or a contact by its `userId` or email. A link to a record that doesn't exist yet stays pending and completes if that record is created within a few days; related records are never created. Reverse relationship and system-owned fields are read-only. JSON numbers retain their supplied precision; identifiers must be strings." } }, "required": [ "objectId" ] } } }, "required": [ "records" ] }, "example": { "records": [ { "objectId": "org-123", "fields": { "dashboard_region": "us" } } ] } } } }, "responses": { "200": { "description": "Per-record write results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "processed": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string", "format": "uuid", "description": "Conversion ID of the saved record. Returned on success; not an input identifier for this endpoint." }, "objectId": { "type": "string", "description": "The `objectId` sent for this record." }, "operation": { "type": "string", "enum": [ "CREATE", "UPDATE" ] }, "error": { "type": "string", "description": "Per-record error code: invalid_identifier, invalid_field, upsert_skipped, or upsert_failed." }, "message": { "type": "string" }, "skipped": { "type": "boolean", "description": "True when CRM intentionally did not write the record." }, "fieldErrors": { "type": "array", "description": "Field keys and reasons reported by CRM when a record fails field validation.", "items": { "type": "object", "required": [ "key", "reason" ], "properties": { "key": { "type": "string" }, "reason": { "type": "string", "description": "CRM rejection reason, such as DROPPED_TYPE_MISMATCH." } } } } }, "required": [ "success" ] } } }, "required": [ "processed", "succeeded", "failed", "results" ] } } }, "example": { "data": { "processed": 1, "succeeded": 1, "failed": 0, "results": [ { "success": true, "id": "1cfa4f66-5db2-4ce5-b4b0-b9c801f3ad7c", "objectId": "org-123", "operation": "CREATE" } ] } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks permission, or custom objects are not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/forms": { "get": { "operationId": "listForms", "summary": "List Forms", "description": "List tracked, published Conversion-native forms with basic metadata. External forms (custom HTML) and ad lead-gen forms (LinkedIn, Meta) are excluded, as are untracked, archived, and never-published forms.\n\nResults are paginated with an opaque cursor returned as `pagination.nextCursor`. Pass it back as the `cursor` query parameter to fetch the next page. A `null` cursor means there are no more results.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "The maximum number of forms to return per page. Defaults to 50. Values are clamped to the range [1, 100] rather than rejected; values above 100 return 100 results." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The opaque pagination cursor returned as `pagination.nextCursor` by a previous call. Omit to fetch the first page. An invalid or malformed cursor returns an `invalid_cursor` error.", "examples": { "next-page": { "value": "eyJjcmVhdGVkQXQiOiIyMDI2LTAxLTE1VDEwOjMwOjAwWiJ9" } } } ], "responses": { "200": { "description": "Forms retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "forms" ], "properties": { "forms": { "type": "array", "description": "The current page of forms.", "items": { "type": "object", "required": [ "id", "name", "createdAt", "updatedAt", "submissionCount", "lastSubmittedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The Conversion form id. Use it as the `formId` path parameter of `GET /v2/forms/{formId}`.", "examples": [ "9f3c1a2e-6b7d-4e2a-9c1f-1a2b3c4d5e6f" ] }, "name": { "type": "string", "description": "The form's display name.", "examples": [ "Demo Request" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When the form was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the form was last updated." }, "submissionCount": { "type": "integer", "description": "The total number of submissions received by the form.", "examples": [ 412 ] }, "lastSubmittedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the form last received a submission, or `null` if it has never been submitted." } } } } } }, "pagination": { "type": "object", "required": [ "nextCursor" ], "properties": { "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or `null` when there are no more results. This is the single source of truth for whether more results exist." } } } } }, "examples": { "success": { "summary": "A page of forms", "value": { "data": { "forms": [ { "id": "9f3c1a2e-6b7d-4e2a-9c1f-1a2b3c4d5e6f", "name": "Demo Request", "createdAt": "2026-05-01T12:00:00Z", "updatedAt": "2026-06-11T09:30:00Z", "submissionCount": 412, "lastSubmittedAt": "2026-07-10T08:15:00Z" }, { "id": "2d4e6f8a-1b3c-4d5e-8f9a-0b1c2d3e4f5a", "name": "Newsletter Signup", "createdAt": "2026-03-14T10:00:00Z", "updatedAt": "2026-03-14T10:00:00Z", "submissionCount": 0, "lastSubmittedAt": null } ] }, "pagination": { "nextCursor": null } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid-cursor": { "summary": "Invalid cursor", "value": { "error": { "code": "invalid_cursor", "message": "invalid pagination cursor" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to load forms" } } } } } } } } } }, "/v2/forms/{formId}": { "get": { "operationId": "getForm", "summary": "Get Form", "description": "Get a tracked, published Conversion-native form by id, including the fields of its published definition. Each field's `fieldId` is the key used to reference the field in the forms JavaScript API and in submission data. `DROPDOWN` and `MULTI_CHECKBOX` fields also list their selectable `options`, so you can map a submitted value back to the option label a visitor saw. A `MULTI_CHECKBOX` submits the values of every ticked option as a single semicolon-separated string, such as `analytics;automation`.\n\nOnly tracked, published Conversion-native forms resolve; unknown ids, forms belonging to another workspace, external and ad forms, and untracked, archived, or never-published forms all return a `form_not_found` error.", "parameters": [ { "name": "formId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Conversion form id, as returned by `GET /v2/forms`.", "examples": { "form": { "value": "9f3c1a2e-6b7d-4e2a-9c1f-1a2b3c4d5e6f" } } } ], "responses": { "200": { "description": "Form retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "form" ], "properties": { "form": { "type": "object", "required": [ "id", "name", "createdAt", "updatedAt", "submissionCount", "lastSubmittedAt", "fields" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The Conversion form id. Use it as the `formId` path parameter of `GET /v2/forms/{formId}`.", "examples": [ "9f3c1a2e-6b7d-4e2a-9c1f-1a2b3c4d5e6f" ] }, "name": { "type": "string", "description": "The form's display name.", "examples": [ "Demo Request" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When the form was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the form was last updated." }, "submissionCount": { "type": "integer", "description": "The total number of submissions received by the form.", "examples": [ 412 ] }, "lastSubmittedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the form last received a submission, or `null` if it has never been submitted." }, "fields": { "type": "array", "description": "The fields of the published form definition, including hidden fields.", "items": { "type": "object", "required": [ "fieldId", "name", "type", "required", "hidden" ], "properties": { "fieldId": { "type": "string", "description": "The field's id in the form definition. Use this id to reference the field in the forms JavaScript API; submission data is keyed by it.", "examples": [ "aa8b2c1d-4e5f-4a6b-8c9d-0e1f2a3b4c5d" ] }, "name": { "type": "string", "description": "The field's name as configured in the form editor, unique within the form. It also labels the field's values in submission data.", "examples": [ "email" ] }, "type": { "type": "string", "enum": [ "SHORT_ANSWER", "LONG_ANSWER", "DROPDOWN", "NUMBER", "EMAIL", "PHONE_NUMBER", "LINK", "SINGLE_CHECKBOX", "MULTI_CHECKBOX", "HIDDEN" ], "description": "The field input type. `DROPDOWN` and `MULTI_CHECKBOX` fields submit option values listed under `options`, a `MULTI_CHECKBOX` joining its ticked values with `;`. `HIDDEN` fields are populated from the page rather than typed by the visitor." }, "required": { "type": "boolean", "description": "Whether the field must be filled to submit. Always `false` for hidden fields." }, "hidden": { "type": "boolean", "description": "Whether the field is a hidden field." }, "options": { "type": "array", "description": "The selectable options of a `DROPDOWN` or `MULTI_CHECKBOX` field, in the order they are configured in the form editor. Omitted for every other field type.\n\nA submission carries option values, never labels: a `DROPDOWN` field submits one option value, and a `MULTI_CHECKBOX` field submits the selected option values as a single semicolon-separated string, such as `analytics;automation`. A submitted value that does not match one of these options is rejected.", "items": { "type": "object", "required": [ "label", "value" ], "properties": { "label": { "type": "string", "description": "The option's text as shown on the form. Labels are optional in the form editor; when empty, the form displays `value` instead.", "examples": [ "1-10 employees" ] }, "value": { "type": "string", "description": "The value a submission carries for the field when this option is selected. Unique within the field.", "examples": [ "1-10" ] } } } } } } } } } } } } }, "examples": { "success": { "summary": "A form with visible and hidden fields", "value": { "data": { "form": { "id": "9f3c1a2e-6b7d-4e2a-9c1f-1a2b3c4d5e6f", "name": "Demo Request", "createdAt": "2026-05-01T12:00:00Z", "updatedAt": "2026-06-11T09:30:00Z", "submissionCount": 412, "lastSubmittedAt": "2026-07-10T08:15:00Z", "fields": [ { "fieldId": "aa8b2c1d-4e5f-4a6b-8c9d-0e1f2a3b4c5d", "name": "email", "type": "EMAIL", "required": true, "hidden": false }, { "fieldId": "bb9c3d2e-5f6a-4b7c-9d0e-1f2a3b4c5d6e", "name": "company_size", "type": "DROPDOWN", "required": false, "hidden": false, "options": [ { "label": "1-10 employees", "value": "1-10" }, { "label": "11-50 employees", "value": "11-50" }, { "label": "51+ employees", "value": "51+" } ] }, { "fieldId": "cc0d4e3f-6a7b-4c8d-0e1f-2a3b4c5d6e7f", "name": "message", "type": "LONG_ANSWER", "required": false, "hidden": false }, { "fieldId": "dd1e5f4a-7b8c-4d9e-1f2a-3b4c5d6e7f8a", "name": "utm_source", "type": "HIDDEN", "required": false, "hidden": true } ] } } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "form-not-found": { "summary": "Form not found", "value": { "error": { "code": "form_not_found", "message": "form not found" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to load form" } } } } } } } } } }, "/v2/workflows/{workflowId}/trigger": { "post": { "operationId": "triggerWorkflow", "summary": "Trigger Workflow", "description": "Trigger an API-triggered workflow for a specific contact.", "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the workflow to trigger.", "examples": { "example": { "value": "d4e5f6a7-b8c9-0123-def0-456789abcdef" } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "The contact's email address. At least one of `cnvContactId`, `userId`, or `email` is required.", "examples": ["jane@example.com"] }, "cnvContactId": { "type": "string", "format": "uuid", "description": "The Conversion contact ID. At least one of `cnvContactId`, `userId`, or `email` is required.", "examples": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"] }, "userId": { "type": "string", "description": "An external user identifier for the contact. At least one of `cnvContactId`, `userId`, or `email` is required.", "examples": ["user_12345"] }, "data": { "type": "object", "additionalProperties": {}, "description": "An optional map of custom data to pass to the workflow as trigger data.", "examples": [ { "source": "backend", "action": "onboarding_complete", "plan": "pro", "trial_days_remaining": 7 } ] } } }, "examples": { "trigger-by-email": { "summary": "Trigger by email", "value": { "email": "jane@example.com", "data": { "form_id": "contact_us", "page_url": "https://example.com/pricing", "message": "Interested in enterprise plan" } } }, "trigger-by-contact-id": { "summary": "Trigger by contact ID", "value": { "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "data": { "source": "backend", "action": "onboarding_complete", "plan": "pro", "trial_days_remaining": 7 } } }, "trigger-by-userId": { "summary": "Trigger by userId", "value": { "userId": "user_12345", "data": { "event": "plan_upgraded", "old_plan": "starter", "new_plan": "pro", "annual": true } } } } } } }, "responses": { "200": { "description": "Workflow triggered successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": ["triggered"], "properties": { "triggered": { "type": "boolean", "description": "`true` if the workflow was successfully triggered." } } } } }, "examples": { "triggered": { "summary": "Workflow triggered", "value": { "data": { "triggered": true } } } } } } }, "400": { "description": "The request was malformed or the workflow cannot be triggered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing-identifier": { "summary": "Missing identifier", "value": { "error": { "code": "missing_identifier", "message": "at least one of 'cnvContactId', 'userId', or 'email' is required" } } }, "workflow-not-active": { "summary": "Workflow not active", "value": { "error": { "code": "workflow_not_active", "message": "workflow is not active" } } }, "invalid-trigger-type": { "summary": "Invalid trigger type", "value": { "error": { "code": "invalid_trigger_type", "message": "workflow trigger type is not API" } } }, "contact-not-eligible": { "summary": "Contact not eligible", "value": { "error": { "code": "contact_not_eligible", "message": "contact did not meet eligibility criteria" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "404": { "description": "The workflow or contact was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "workflow-not-found": { "summary": "Workflow not found", "value": { "error": { "code": "workflow_not_found", "message": "workflow not found" } } }, "contact-not-found": { "summary": "Contact not found", "value": { "error": { "code": "contact_not_found", "message": "contact not found" } } } } } } }, "409": { "description": "The provided identifiers conflict with an existing contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conflicting-identifier": { "summary": "Conflicting identifier", "value": { "error": { "code": "conflicting_identifier", "message": "contact found by email but has a different userId" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to trigger workflow" } } } } } } } } } }, "/v2/audiences/{audienceId}/contacts": { "post": { "operationId": "addContactToAudience", "summary": "Add Contact to Audience", "description": "Add a contact to a static audience. The contact is identified by `cnvContactId`, `userId`, or `email`.", "parameters": [ { "name": "audienceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the static audience to add the contact to.", "examples": { "example": { "value": "d4e5f6a7-b8c9-0123-def0-456789abcdef" } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "The contact's email address. At least one of `cnvContactId`, `userId`, or `email` is required.", "examples": [ "jane@example.com" ] }, "cnvContactId": { "type": "string", "format": "uuid", "description": "The Conversion contact ID. At least one of `cnvContactId`, `userId`, or `email` is required.", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "userId": { "type": "string", "description": "An external user identifier for the contact. At least one of `cnvContactId`, `userId`, or `email` is required.", "examples": [ "user_12345" ] } } }, "examples": { "add-by-email": { "summary": "Add by email", "value": { "email": "jane@example.com" } }, "add-by-contact-id": { "summary": "Add by contact ID", "value": { "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "add-by-userId": { "summary": "Add by userId", "value": { "userId": "user_12345" } } } } } }, "responses": { "200": { "description": "Contact added to the audience successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "added", "cnvContactId" ], "properties": { "added": { "type": "boolean", "description": "`true` once the contact is a member of the audience. The operation is idempotent." }, "cnvContactId": { "type": "string", "format": "uuid", "description": "The resolved Conversion contact ID." } } } } }, "examples": { "added": { "summary": "Contact added", "value": { "data": { "added": true, "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } } }, "400": { "description": "The request was malformed or the audience cannot accept contacts directly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing-identifier": { "summary": "Missing identifier", "value": { "error": { "code": "missing_identifier", "message": "at least one of cnvContactId, userId, or email is required" } } }, "audience-not-static": { "summary": "Audience not static", "value": { "error": { "code": "audience_not_static", "message": "contacts can only be added to static audiences" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "404": { "description": "The audience or contact was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "audience-not-found": { "summary": "Audience not found", "value": { "error": { "code": "audience_not_found", "message": "audience not found" } } }, "contact-not-found": { "summary": "Contact not found", "value": { "error": { "code": "contact_not_found", "message": "no contact found matching the provided identifier" } } } } } } }, "409": { "description": "The provided identifiers conflict with an existing contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conflicting-identifier": { "summary": "Conflicting identifier", "value": { "error": { "code": "conflicting_identifier", "message": "contact found by email but has a different userId" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to add contact to audience" } } } } } } } } }, "delete": { "operationId": "removeContactFromAudience", "summary": "Remove Contact from Audience", "description": "Remove a contact from one static audience, identified by cnvContactId, userId, or email, in that order. Does not delete the contact, update fields, change subscription status, or remove other audience memberships. Returns success if the contact or membership is already absent. Requires audience edit permission.", "parameters": [ { "name": "audienceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the static audience to remove the contact from.", "examples": { "example": { "value": "d4e5f6a7-b8c9-0123-def0-456789abcdef" } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "The contact's email address. At least one of `cnvContactId`, `userId`, or `email` is required.", "examples": [ "jane@example.com" ] }, "cnvContactId": { "type": "string", "format": "uuid", "description": "The Conversion contact ID. At least one of `cnvContactId`, `userId`, or `email` is required.", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "userId": { "type": "string", "description": "An external user identifier for the contact. At least one of `cnvContactId`, `userId`, or `email` is required.", "examples": [ "user_12345" ] } } }, "examples": { "remove-by-email": { "summary": "Remove by email", "value": { "email": "jane@example.com" } } } } } }, "responses": { "200": { "description": "Membership is absent, including if the contact was not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "removed" ], "properties": { "removed": { "type": "boolean", "description": "True once membership is absent." }, "cnvContactId": { "type": "string", "format": "uuid", "description": "Resolved contact ID, omitted if the contact was not found." } } } } }, "examples": { "removed": { "value": { "data": { "removed": true, "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } }, "already-absent": { "value": { "data": { "removed": true } } } } } } }, "400": { "description": "Missing identifiers or a non-static audience.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing-identifier": { "summary": "Missing identifier", "value": { "error": { "code": "missing_identifier", "message": "at least one of cnvContactId, userId, or email is required" } } }, "audience-not-static": { "summary": "Audience not static", "value": { "error": { "code": "audience_not_static", "message": "membership can only be changed for static audiences" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "404": { "description": "The audience was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "audience-not-found": { "summary": "Audience not found", "value": { "error": { "code": "audience_not_found", "message": "audience not found" } } } } } } }, "409": { "description": "The provided identifiers conflict with an existing contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conflicting-identifier": { "summary": "Conflicting identifier", "value": { "error": { "code": "conflicting_identifier", "message": "contact found by email but has a different userId" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to remove contact from audience" } } } } } } }, "403": { "description": "The API key lacks audience edit permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/campaigns": { "get": { "operationId": "listCampaigns", "summary": "List Campaigns", "description": "List your custom campaigns with their type, `sfdcCampaignId`, and member count. Only custom campaigns are exposed by this API; webinars and blasts are not returned. Archived campaigns are excluded. Member statuses are not included here; fetch them as `type.statuses` from `GET /v2/campaigns/{campaignId}`.\n\nResults are paginated with an opaque cursor returned as `pagination.nextCursor`. Pass it back as the `cursor` query parameter to fetch the next page.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "The maximum number of campaigns to return per page. Values outside [1, 100] are clamped rather than rejected." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The opaque pagination cursor returned as `pagination.nextCursor` by a previous call. Omit to fetch the first page. An invalid or malformed cursor returns an `invalid_cursor` error.", "examples": { "next-page": { "value": "eyJjcmVhdGVkQXQiOiIyMDI2LTAxLTE1VDEwOjMwOjAwWiJ9" } } } ], "responses": { "200": { "description": "Campaigns retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "campaigns" ], "properties": { "campaigns": { "type": "array", "description": "The current page of campaigns.", "items": { "type": "object", "required": [ "id", "name", "type", "sfdcCampaignId", "memberCount", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The Conversion campaign id.", "examples": [ "b7c8d9e0-f1a2-3456-bcde-f01234567890" ] }, "name": { "type": "string", "description": "The campaign's display name, unique within the workspace.", "examples": [ "Q3 Field Events" ] }, "type": { "type": "object", "description": "The campaign type the campaign belongs to. Types are defined in the dashboard.", "required": [ "id", "name", "systemType" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The campaign type id.", "examples": [ "3c9d2b1a-8e4f-4a6b-9c0d-2e3f4a5b6c7d" ] }, "name": { "type": "string", "description": "The type's display name, as configured in the dashboard.", "examples": [ "Field Event" ] }, "systemType": { "type": "string", "enum": [ "CUSTOM" ], "description": "The system classification of the campaign type. Currently `CUSTOM`." } } }, "sfdcCampaignId": { "type": [ "string", "null" ], "description": "The id of the Salesforce campaign this campaign is linked to, or `null` if the campaign is not linked to Salesforce.", "examples": [ "701Ho00000AbCdEfGH" ] }, "memberCount": { "type": "integer", "description": "The total number of members in the campaign.", "examples": [ 42 ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When the campaign was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the campaign was last updated." } } } } } }, "pagination": { "type": "object", "required": [ "nextCursor" ], "properties": { "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or `null` when there are no more results. This is the single source of truth for whether more results exist." } } } } }, "examples": { "success": { "summary": "A page of campaigns", "value": { "data": { "campaigns": [ { "id": "b7c8d9e0-f1a2-3456-bcde-f01234567890", "name": "Q3 Field Events", "type": { "id": "3c9d2b1a-8e4f-4a6b-9c0d-2e3f4a5b6c7d", "name": "Field Event", "systemType": "CUSTOM" }, "sfdcCampaignId": "701Ho00000AbCdEfGH", "memberCount": 42, "createdAt": "2026-05-01T12:00:00Z", "updatedAt": "2026-06-11T09:30:00Z" }, { "id": "2d4e6f8a-1b3c-4d5e-8f9a-0b1c2d3e4f5a", "name": "Product Launch Outreach", "type": { "id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Outreach", "systemType": "CUSTOM" }, "sfdcCampaignId": null, "memberCount": 0, "createdAt": "2026-03-14T10:00:00Z", "updatedAt": "2026-03-14T10:00:00Z" } ] }, "pagination": { "nextCursor": null } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid-cursor": { "summary": "Invalid cursor", "value": { "error": { "code": "invalid_cursor", "message": "invalid pagination cursor" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to load campaigns" } } } } } } } } } }, "/v2/campaigns/{campaignId}": { "get": { "operationId": "getCampaign", "summary": "Get Campaign", "description": "Get a custom campaign by id, including its description and its campaign type's member statuses as `type.statuses`. Statuses are returned in the type's configured progression order. Archived campaigns return 404.", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Conversion campaign id, as returned by `GET /v2/campaigns`.", "examples": { "campaign": { "value": "b7c8d9e0-f1a2-3456-bcde-f01234567890" } } } ], "responses": { "200": { "description": "Campaign retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "campaign" ], "properties": { "campaign": { "type": "object", "required": [ "id", "name", "type", "sfdcCampaignId", "memberCount", "createdAt", "updatedAt", "description" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The Conversion campaign id.", "examples": [ "b7c8d9e0-f1a2-3456-bcde-f01234567890" ] }, "name": { "type": "string", "description": "The campaign's display name, unique within the workspace.", "examples": [ "Q3 Field Events" ] }, "type": { "type": "object", "description": "The campaign type the campaign belongs to. Types are defined in the dashboard.", "required": [ "id", "name", "systemType", "statuses" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The campaign type id.", "examples": [ "3c9d2b1a-8e4f-4a6b-9c0d-2e3f4a5b6c7d" ] }, "name": { "type": "string", "description": "The type's display name, as configured in the dashboard.", "examples": [ "Field Event" ] }, "systemType": { "type": "string", "enum": [ "CUSTOM" ], "description": "The system classification of the campaign type. Currently `CUSTOM`." }, "statuses": { "type": "array", "description": "The member statuses configured for the campaign type, in progression order. Use a status's `id` or `name` as `statusId` or `status` when adding members.", "items": { "type": "object", "required": [ "id", "name", "isSuccess" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The campaign status id." }, "name": { "type": "string", "description": "The status's display name.", "examples": [ "Attended" ] }, "isSuccess": { "type": "boolean", "description": "Whether the status counts as a successful outcome for the campaign." } } } } } }, "sfdcCampaignId": { "type": [ "string", "null" ], "description": "The id of the Salesforce campaign this campaign is linked to, or `null` if the campaign is not linked to Salesforce.", "examples": [ "701Ho00000AbCdEfGH" ] }, "memberCount": { "type": "integer", "description": "The total number of members in the campaign.", "examples": [ 42 ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When the campaign was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the campaign was last updated." }, "description": { "type": [ "string", "null" ], "description": "The campaign's description, or `null` if not set.", "examples": [ "Events run by the field team" ] } } } } } } }, "examples": { "success": { "summary": "A campaign with its type's statuses", "value": { "data": { "campaign": { "id": "b7c8d9e0-f1a2-3456-bcde-f01234567890", "name": "Q3 Field Events", "type": { "id": "3c9d2b1a-8e4f-4a6b-9c0d-2e3f4a5b6c7d", "name": "Field Event", "systemType": "CUSTOM", "statuses": [ { "id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b", "name": "Registered", "isSuccess": false }, { "id": "8f9a0b1c-2d3e-4f4a-9b5c-6d7e8f9a0b1c", "name": "Attended", "isSuccess": true } ] }, "sfdcCampaignId": "701Ho00000AbCdEfGH", "memberCount": 42, "createdAt": "2026-05-01T12:00:00Z", "updatedAt": "2026-06-11T09:30:00Z", "description": "Events run by the field team" } } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "campaign-not-found": { "summary": "Campaign not found", "value": { "error": { "code": "campaign_not_found", "message": "campaign not found" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to load campaign" } } } } } } } } } }, "/v2/campaigns/{campaignId}/members": { "post": { "operationId": "addCampaignMember", "summary": "Add Campaign Member", "description": "Add one member to a custom campaign by email. Same rules as `POST /v2/campaigns/{campaignId}/members/batch`: the contact is created if it does not exist, adding is an idempotent upsert, and status progression is forward-only for existing members.", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Conversion campaign id, as returned by `GET /v2/campaigns`.", "examples": { "campaign": { "value": "b7c8d9e0-f1a2-3456-bcde-f01234567890" } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "The member's email address, normalized (trimmed and lowercased) before matching. An invalid email returns `400 invalid_email` and creates no contact.", "examples": [ "jane@example.com" ] }, "statusId": { "type": "string", "format": "uuid", "description": "The campaign status id to place the member in, as returned by `GET /v2/campaigns/{campaignId}`. Takes precedence over `status`. An id that is not a status of the campaign's type returns `400 invalid_campaign_status`.", "examples": [ "8f9a0b1c-2d3e-4f4a-9b5c-6d7e8f9a0b1c" ] }, "status": { "type": "string", "description": "The campaign status name, case-insensitive. Used only when `statusId` is not set. Omit both to use the campaign type's first status.", "examples": [ "Attended" ] } } }, "examples": { "add-member": { "summary": "Add a member with a status", "value": { "email": "jane@example.com", "status": "Attended" } } } } } }, "responses": { "200": { "description": "Member added or updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "campaignMemberId", "contactId" ], "properties": { "campaignMemberId": { "type": "string", "format": "uuid", "description": "The campaign member id." }, "contactId": { "type": "string", "format": "uuid", "description": "The id of the member's contact, created if it did not exist." } } } } }, "examples": { "success": { "summary": "Member added", "value": { "data": { "campaignMemberId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d", "contactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid-email": { "summary": "Invalid email", "value": { "error": { "code": "invalid_email", "message": "invalid email format" } } }, "invalid-status": { "summary": "Invalid campaign status", "value": { "error": { "code": "invalid_campaign_status", "message": "status is not valid for this campaign" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "campaign-not-found": { "summary": "Campaign not found", "value": { "error": { "code": "campaign_not_found", "message": "campaign not found" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to add campaign member" } } } } } } } } } }, "/v2/campaigns/{campaignId}/members/batch": { "post": { "operationId": "batchAddCampaignMembers", "summary": "Batch Add Campaign Members", "description": "Add up to 200 members to a custom campaign by email, creating contacts that do not exist yet. Adding is an idempotent upsert: a contact already in the campaign has its status updated instead of being added twice.\n\nStatus progression is forward-only for existing members; requesting their current or an earlier status leaves it unchanged. Set a status by `statusId` or `status` from `GET /v2/campaigns/{campaignId}`, or omit both to use the campaign type's first status. Members are processed independently, so one can fail while the rest of the batch succeeds.", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Conversion campaign id, as returned by `GET /v2/campaigns`.", "examples": { "campaign": { "value": "b7c8d9e0-f1a2-3456-bcde-f01234567890" } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "members" ], "properties": { "members": { "type": "array", "minItems": 1, "maxItems": 200, "description": "An array of members to add to the campaign.", "items": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "The member's email address, normalized (trimmed and lowercased) before matching. An invalid email fails that member's row with `invalid_email` and creates no contact.", "examples": [ "jane@example.com" ] }, "statusId": { "type": "string", "format": "uuid", "description": "The campaign status id to place the member in, as returned by `GET /v2/campaigns/{campaignId}`. Takes precedence over `status`. An id that is not a status of the campaign's type fails that member's row.", "examples": [ "8f9a0b1c-2d3e-4f4a-9b5c-6d7e8f9a0b1c" ] }, "status": { "type": "string", "description": "The campaign status name, case-insensitive. Used only when `statusId` is not set.", "examples": [ "Attended" ] } } } } } }, "examples": { "add-members": { "summary": "Add members with different statuses", "value": { "members": [ { "email": "jane@example.com" }, { "email": "john@example.com", "status": "Attended" }, { "email": "sam@example.com", "statusId": "8f9a0b1c-2d3e-4f4a-9b5c-6d7e8f9a0b1c" } ] } } } } } }, "responses": { "200": { "description": "Batch processed. Check the counts and each result for per-member success or failure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "processed", "succeeded", "failed", "results" ], "properties": { "processed": { "type": "integer", "description": "The total number of members in the batch." }, "succeeded": { "type": "integer", "description": "The number of members added or updated." }, "failed": { "type": "integer", "description": "The number of members that failed." }, "results": { "type": "array", "description": "An array of result objects in the same order as the input `members` array.", "items": { "type": "object", "required": [ "email", "success" ], "properties": { "email": { "type": "string", "description": "The member's email address from the request." }, "success": { "type": "boolean", "description": "`true` if the member was successfully added or updated." }, "campaignMemberId": { "type": "string", "format": "uuid", "description": "The campaign member id. Present on success." }, "contactId": { "type": "string", "format": "uuid", "description": "The id of the member's contact, created if it did not exist. Present on success." }, "error": { "type": "string", "description": "A machine-readable error code. Present on failure: `invalid_email`, `invalid_campaign_status`, or `upsert_failed`." }, "message": { "type": "string", "description": "A human-readable error description. Present on failure." } } } } } } } }, "examples": { "mixed-results": { "summary": "Partial success", "value": { "data": { "processed": 2, "succeeded": 1, "failed": 1, "results": [ { "email": "jane@example.com", "success": true, "campaignMemberId": "0a1b2c3d-4e5f-4a6b-8c7d-8e9f0a1b2c3d", "contactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, { "email": "john@example.com", "success": false, "error": "invalid_campaign_status", "message": "status is not valid for this campaign" } ] } } } } } } }, "400": { "description": "The request was malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid-request": { "summary": "Invalid request body", "value": { "error": { "code": "invalid_request", "message": "request validation failed" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "campaign-not-found": { "summary": "Campaign not found", "value": { "error": { "code": "campaign_not_found", "message": "campaign not found" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to add campaign members" } } } } } } } } } }, "/v2/exports/contacts": { "post": { "operationId": "exportContacts", "summary": "Export Contacts", "description": "Bulk, incremental export of contacts, ordered by `updatedAt` ascending. Each contact's fields are flattened under `fields`, keyed by their label.\n\nResults are paginated with an opaque cursor returned as `pagination.nextCursor`. Pass it back as `cursor` to fetch the next page; a `null` cursor means there are no more results. Persist the last non-null cursor between syncs to resume. Passing the stored cursor on a later call yields contacts created or updated since.\n\n> **Request access.** This endpoint is not enabled by default, contact the Conversion team to request access. Calls from accounts without it return `403 export_not_enabled`.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cursor": { "type": "string", "description": "The opaque pagination cursor returned as `pagination.nextCursor` by a previous call. Omit (or pass an empty string) on the first call to start from the beginning. An invalid or malformed cursor returns an `invalid_cursor` error.", "examples": ["eyJjcmVhdGVkQXQiOiIyMDI2LTAxLTE1VDEwOjMwOjAwWiJ9"] }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 1000, "description": "The maximum number of contacts to return per page. Defaults to 1000. Values are clamped to the range [1, 5000] rather than rejected; values above 5000 return 5000 results." } } }, "examples": { "first-page": { "summary": "First page", "value": { "limit": 1000 } }, "next-page": { "summary": "Resume from a cursor", "value": { "cursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTAxLTE1VDEwOjMwOjAwWiJ9", "limit": 1000 } } } } } }, "responses": { "200": { "description": "A page of contacts retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": ["contacts"], "properties": { "contacts": { "type": "array", "description": "The current page of exported contacts.", "items": { "type": "object", "required": ["id", "email", "subscriptionStatus", "createdAt", "updatedAt", "fields"], "properties": { "id": { "type": "string", "format": "uuid", "description": "The Conversion contact ID. Stable primary key for warehouse upserts." }, "sfdcLeadId": { "type": ["string", "null"], "description": "The contact's Salesforce id when its Salesforce object type is Lead; otherwise `null`." }, "sfdcContactId": { "type": ["string", "null"], "description": "The contact's Salesforce id when its Salesforce object type is Contact; otherwise `null`." }, "sfdcAccountId": { "type": ["string", "null"], "description": "The Salesforce Account id of the contact's linked company, or `null` when the contact has no company or it isn't synced to Salesforce." }, "email": { "type": "string", "format": "email" }, "subscriptionStatus": { "type": "string", "description": "The contact's email subscription status. In addition to `SUBSCRIBED`, `UNSUBSCRIBED`, and `NO_STATUS`, exported values may include system-managed statuses such as `BOUNCED` or `COMPLAINED`.", "examples": ["SUBSCRIBED"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Every contact field (variable schema) value, keyed by its common name (e.g. `owner_id`)." } } } } } }, "pagination": { "type": "object", "required": ["nextCursor"], "properties": { "nextCursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page, or `null` when there are no more results. This is the single source of truth for whether more results exist." } } } } }, "examples": { "with-more-pages": { "summary": "More pages available", "value": { "data": { "contacts": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "sfdcLeadId": "00Q5f000001AbCdEAE", "sfdcContactId": null, "sfdcAccountId": "0015f00000ACMExAAB", "email": "jane@example.com", "subscriptionStatus": "SUBSCRIBED", "createdAt": "2026-01-15T10:30:00Z", "updatedAt": "2026-06-01T08:15:00Z", "fields": { "first_name": "Jane", "owner_id": "0055f000000AbCdEFG" } } ] }, "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDA4OjE1OjAwWiJ9" } } }, "last-page": { "summary": "Last page", "value": { "data": { "contacts": [ { "id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210", "sfdcLeadId": null, "sfdcContactId": null, "sfdcAccountId": null, "email": "bob@example.com", "subscriptionStatus": "UNSUBSCRIBED", "createdAt": "2026-02-20T12:00:00Z", "updatedAt": "2026-06-02T09:00:00Z", "fields": {} } ] }, "pagination": { "nextCursor": null } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid-cursor": { "summary": "Invalid cursor", "value": { "error": { "code": "invalid_cursor", "message": "invalid pagination cursor" } } }, "invalid-business": { "summary": "Invalid business", "value": { "error": { "code": "invalid_business", "message": "invalid business id" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "403": { "description": "The export API is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "export-not-enabled": { "summary": "Export not enabled", "value": { "error": { "code": "export_not_enabled", "message": "business is not authorized to use the export API" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to list contacts" } } } } } } } } } }, "/v2/exports/email-events": { "post": { "operationId": "exportEmailEvents", "summary": "Export Email Events", "deprecated": true, "description": "**Deprecated.** Use [Export Contact Events](/api-reference/export-contact-events) with `types` set to the `EMAIL_*` types you need. It returns the same events, with the email detail and `emailName` in each event's `email` object. To move an existing walk over without re-reading it, send its last cursor as `emailEventsCursor`. This endpoint is still served.\n\nBulk, incremental export of raw email engagement events of a single type, keyed by `occurredAt`. The email asset name is resolved per row on a best-effort basis (`emailName` may be `null` if it cannot be resolved).\n\nResults are paginated with an opaque cursor returned as `pagination.nextCursor`. Pass it back as `cursor` to fetch the next page; a `null` cursor means there are no more results. Persist the last non-null cursor between syncs to resume.\n\n> **Request Access.** This endpoint is not enabled by default, contact the Conversion team to request access. Calls from accounts without it return `403 export_not_enabled`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["eventType"], "properties": { "eventType": { "type": "string", "enum": [ "EMAIL_SEND", "EMAIL_DELIVERY", "EMAIL_OPEN", "EMAIL_CLICK", "EMAIL_BOUNCE", "EMAIL_SOFT_BOUNCE", "EMAIL_COMPLAINT", "EMAIL_UNSUBSCRIBE_ALL", "EMAIL_TOPIC_UNSUBSCRIBE" ], "description": "The email event type to export. Each call exports a single event type, matched 1:1 against the underlying email event type. Case-insensitive; an unsupported value returns an `invalid_field` error.", "examples": ["EMAIL_OPEN"] }, "cursor": { "type": "string", "description": "The opaque pagination cursor returned as `pagination.nextCursor` by a previous call. Omit (or pass an empty string) to fetch the first page. An invalid or malformed cursor returns an `invalid_cursor` error.", "examples": ["eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDEwOjAwOjAwWiJ9"] }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 1000, "description": "The maximum number of events to return per page. Defaults to 1000. Values are clamped to the range [1, 5000] rather than rejected; values above 5000 return 5000 results." } } }, "examples": { "first-page": { "summary": "First page of opens", "value": { "eventType": "EMAIL_OPEN", "limit": 1000 } }, "next-page": { "summary": "Resume from a cursor", "value": { "eventType": "EMAIL_OPEN", "cursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDEwOjAwOjAwWiJ9", "limit": 1000 } } } } } }, "responses": { "200": { "description": "A page of email events retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": ["events"], "properties": { "events": { "type": "array", "description": "The current page of exported email events.", "items": { "type": "object", "required": ["eventId", "contactId", "occurredAt", "eventType", "isBot"], "properties": { "eventId": { "type": "string", "format": "uuid", "description": "The Conversion engagement ID for this event. Stable primary key for warehouse upserts." }, "contactId": { "type": "string", "format": "uuid", "description": "The Conversion contact ID the event belongs to (joins `contacts.id`)." }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the event occurred." }, "eventType": { "type": "string", "description": "The underlying email event type.", "examples": ["EMAIL_OPEN"] }, "sourceType": { "type": ["string", "null"], "description": "The kind of flow that sent the email (`WORKFLOW` or `BLAST`), or `null` if unknown." }, "sourceId": { "type": ["string", "null"], "format": "uuid", "description": "The id of the workflow or blast that sent the email, or `null`." }, "emailId": { "type": ["string", "null"], "format": "uuid", "description": "The id of the email asset, or `null`." }, "emailName": { "type": ["string", "null"], "description": "The resolved name of the email asset. Best-effort: `null` if it could not be resolved." }, "sentEmailId": { "type": ["string", "null"], "format": "uuid", "description": "The per-send instance id, or `null`." }, "isBot": { "type": "boolean", "description": "`true` if the engagement was classified as bot activity. Filter in the warehouse as needed." }, "link": { "type": ["string", "null"], "description": "For `EMAIL_CLICK` events, the clicked URL; otherwise `null`." }, "topicIds": { "type": ["string", "null"], "description": "Stringified array of topic ids the recipient unsubscribed from. Only populated for `EMAIL_TOPIC_UNSUBSCRIBE` events, otherwise `null`." }, "bounceType": { "type": ["string", "null"], "enum": ["Permanent", "Transient", "Undetermined", null], "description": "Bounce classification for `EMAIL_BOUNCE` and `EMAIL_SOFT_BOUNCE` events, or `null`. Possible values: `Permanent`, `Transient`, `Undetermined`." }, "errorMessage": { "type": ["string", "null"], "description": "SMTP diagnostic code (e.g. `smtp; 550 5.1.1 user unknown`); only populated for `EMAIL_BOUNCE` and `EMAIL_SOFT_BOUNCE`, otherwise `null`." } } } } } }, "pagination": { "type": "object", "required": ["nextCursor"], "properties": { "nextCursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page, or `null` when there are no more results. This is the single source of truth for whether more results exist." } } } } }, "examples": { "with-more-pages": { "summary": "More pages available", "value": { "data": { "events": [ { "eventId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "contactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "occurredAt": "2026-06-01T10:00:00Z", "eventType": "EMAIL_OPEN", "sourceType": "BLAST", "sourceId": "d4e5f6a7-b8c9-0123-def0-456789abcdef", "emailId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "emailName": "June Newsletter", "sentEmailId": "e5f6a7b8-c9d0-1234-ef01-56789abcdef0", "isBot": false, "link": null, "topicIds": null, "bounceType": null, "errorMessage": null } ] }, "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDEwOjAwOjAwWiJ9" } } }, "last-page": { "summary": "Last page", "value": { "data": { "events": [] }, "pagination": { "nextCursor": null } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid-event-type": { "summary": "Invalid event type", "value": { "error": { "code": "invalid_field", "message": "invalid eventType; must be one of EMAIL_BOUNCE, EMAIL_SOFT_BOUNCE, EMAIL_COMPLAINT, EMAIL_DELIVERY, EMAIL_OPEN, EMAIL_CLICK, EMAIL_SEND, EMAIL_UNSUBSCRIBE_ALL, EMAIL_TOPIC_UNSUBSCRIBE" } } }, "invalid-cursor": { "summary": "Invalid cursor", "value": { "error": { "code": "invalid_cursor", "message": "invalid pagination cursor" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "403": { "description": "The export API is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "export-not-enabled": { "summary": "Export not enabled", "value": { "error": { "code": "export_not_enabled", "message": "business is not authorized to use the export API" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to list email events" } } } } } } } } } }, "/v2/exports/custom-events": { "post": { "operationId": "exportCustomEvents", "summary": "Export Custom Events", "description": "Bulk export of custom events from a half-open `occurredAt` range, ordered by `occurredAt` ascending. Each event's own payload is returned as a JSON object under `data`. The contact's current email and user ID are resolved per row on a best-effort basis (`contactEmail` and `userId` may be `null` if the contact no longer exists).\n\nSend `occurredAt` on the first call, then pass the opaque cursor returned as `pagination.nextCursor` back as `cursor` on every later call. A `null` cursor means there are no more results. Persist the last non-null cursor between syncs to resume. The range may be arbitrarily long and is walked in bounded segments internally, so an empty page with a non-null cursor means there are more results to come rather than the end of the export.\n\n> **Request access.** This endpoint is not enabled by default, contact the Conversion team to request access. Calls from accounts without it return `403 export_not_enabled`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "occurredAt": { "type": "object", "description": "The half-open `occurredAt` range to export, from `start` up to but not including `end`. Required on the first call, and omitted on later calls because the cursor carries the range. Supplying both `occurredAt` and `cursor` returns an `invalid_window` error.", "required": [ "start" ], "properties": { "start": { "type": "string", "format": "date-time", "description": "The start of the range. Events that occurred at exactly this time are included. Omitting it on a call without a `cursor` returns an `invalid_window` error.", "examples": [ "2026-08-01T00:00:00Z" ] }, "end": { "type": "string", "format": "date-time", "description": "The end of the range. Events that occurred at exactly this time are excluded, so consecutive ranges can be exported without repeating a boundary event. Omit it to export everything up to the time each page is served, which lets a stored cursor keep returning newly arrived events. Supply it to stop the export at a fixed point, for example to re-export a single historical range. Must be after `start`.", "examples": [ "2026-09-01T00:00:00Z" ] } } }, "cursor": { "type": "string", "description": "The opaque pagination cursor returned as `pagination.nextCursor` by a previous call. Omit (or pass an empty string) to fetch the first page. Send it on its own, with no `occurredAt`. An invalid or malformed cursor returns an `invalid_cursor` error.", "examples": [ "eyJ2IjoxLCJjIjoiMjAyNi0wOC0wMVQwMDowMDowMFoifQ==" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000, "description": "The maximum number of events to return per page. Defaults to 1000. Values are clamped to the range [1, 1000] rather than rejected; values above 1000 return 1000 results." } } }, "examples": { "first-page": { "summary": "First page of a range", "value": { "occurredAt": { "start": "2026-08-01T00:00:00Z" }, "limit": 1000 } }, "next-page": { "summary": "Resume from a cursor", "value": { "cursor": "eyJ2IjoxLCJjIjoiMjAyNi0wOC0wMVQwMDowMDowMFoifQ==", "limit": 1000 } }, "fixed-range": { "summary": "Re-export one fixed range", "value": { "occurredAt": { "start": "2026-08-01T00:00:00Z", "end": "2026-09-01T00:00:00Z" }, "limit": 1000 } } } } } }, "responses": { "200": { "description": "A page of custom events retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "description": "The current page of exported custom events.", "items": { "type": "object", "required": [ "eventId", "contactId", "occurredAt", "createdAt", "eventName", "source" ], "properties": { "eventId": { "type": "string", "format": "uuid", "description": "The Conversion ID for this event. Stable primary key for warehouse upserts." }, "contactId": { "type": "string", "format": "uuid", "description": "The Conversion contact ID the event belongs to (joins `contacts.id`)." }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the event occurred. This is the value supplied when the event was tracked, and it is the only timestamp this endpoint filters on." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Conversion ingested the event. Compare it with `occurredAt` to identify events that were backdated, for example by a warehouse sync or a CSV import." }, "eventName": { "type": "string", "description": "The name the event was tracked under.", "examples": [ "order_completed" ] }, "source": { "type": "string", "enum": [ "CONVERSION", "PUBLIC_API", "CONVERSION_FORM", "CSV_UPLOAD", "SALESFORCE", "SNOWFLAKE", "BIGQUERY", "META", "LINKEDIN", "ZOOM", "ZOOM_EVENTS", "SEQUEL", "GOLDCAST", "ATTENTIVE" ], "description": "The channel the event was ingested through.", "examples": [ "PUBLIC_API" ] }, "contactEmail": { "type": [ "string", "null" ], "description": "The contact's current email address. Best-effort: `null` if the contact no longer exists. This is the value at export time, not the value when the event occurred." }, "userId": { "type": [ "string", "null" ], "description": "The `userId` the contact is identified by in your own system. Best-effort: `null` if the contact no longer exists or has no `userId`." }, "clientEventId": { "type": [ "string", "null" ], "description": "The `eventId` supplied when the event was tracked, or `null` if none was sent. Use it to join back to the event in your own system." }, "data": { "type": [ "object", "null" ], "description": "The event's own payload, exactly as it was tracked, or `null` if none was sent. Keys are lowercased on ingest. Because the keys differ per event name, this is returned as a single JSON object rather than flattened into columns." } } } } } }, "pagination": { "type": "object", "required": [ "nextCursor" ], "properties": { "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or `null` when there are no more results. This is the single source of truth for whether more results exist; an empty page can still carry a cursor." } } } } }, "examples": { "with-more-pages": { "summary": "More pages available", "value": { "data": { "events": [ { "eventId": "f1e2d3c4-b5a6-7890-fedc-ba0987654321", "contactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "occurredAt": "2026-08-19T17:01:37Z", "createdAt": "2026-08-19T18:55:05.903Z", "eventName": "order_completed", "source": "PUBLIC_API", "contactEmail": "jane@example.com", "userId": "user_8813", "clientEventId": "order_12345", "data": { "currency": "usd", "items": 3, "order_total": 149.99 } } ] }, "pagination": { "nextCursor": "eyJ2IjoxLCJjIjoiMjAyNi0wOC0wMVQwMDowMDowMFoifQ==" } } }, "last-page": { "summary": "Last page", "value": { "data": { "events": [] }, "pagination": { "nextCursor": null } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing-range": { "summary": "No range and no cursor", "value": { "error": { "code": "invalid_window", "message": "occurredAt.start is required when no cursor is supplied" } } }, "conflicting-range": { "summary": "Range sent alongside a cursor", "value": { "error": { "code": "invalid_window", "message": "cursor and occurredAt are mutually exclusive; the cursor carries the range" } } }, "inverted-range": { "summary": "End before start", "value": { "error": { "code": "invalid_window", "message": "occurredAt.end must be after occurredAt.start" } } }, "invalid-cursor": { "summary": "Invalid cursor", "value": { "error": { "code": "invalid_cursor", "message": "invalid pagination cursor" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "403": { "description": "The export API is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "export-not-enabled": { "summary": "Export not enabled", "value": { "error": { "code": "export_not_enabled", "message": "business is not authorized to use the export API" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to list custom events" } } } } } } } } } }, "/v2/exports/contact-events": { "post": { "operationId": "exportContactEvents", "summary": "Export Contact Events", "description": "Bulk, incremental export of contact events: email, page visit, form submission, campaign member, workflow, audience, field change, and Salesforce lead conversion events. Custom events export from `POST /v2/exports/custom-events`.\n\nSend filters on the first call, then pass `pagination.nextCursor` back as `cursor` until it is `null`. Persist the last non-null cursor between syncs to resume.\n\n> **Request access.** This endpoint is not enabled by default, contact the Conversion team to request access. Calls from accounts without it return `403 export_not_enabled`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactIds": { "type": "array", "description": "Only these contacts' events. At most 100.", "items": { "type": "string", "format": "uuid" } }, "types": { "type": "array", "description": "Only these event types.", "items": { "type": "string", "enum": [ "EMAIL_SEND", "EMAIL_DELIVERY", "EMAIL_OPEN", "EMAIL_CLICK", "EMAIL_BOUNCE", "EMAIL_SOFT_BOUNCE", "EMAIL_COMPLAINT", "EMAIL_UNSUBSCRIBE_ALL", "EMAIL_TOPIC_UNSUBSCRIBE", "PAGE_VISIT", "FORM_SUBMISSION", "CAMPAIGN_MEMBER_ADDED", "CAMPAIGN_MEMBER_REMOVED", "CAMPAIGN_MEMBER_STATUS_CHANGED", "CAMPAIGN_MEMBER_FIELD_CHANGED", "WORKFLOW_ENTERED", "WORKFLOW_EXITED", "WORKFLOW_ERROR", "AUDIENCE_ADDED", "AUDIENCE_REMOVED", "FIELD_CHANGE", "SFDC_LEAD_CONVERTED" ] } }, "parentTypes": { "type": "array", "description": "Only these event families. With `types`, an event must match both.", "items": { "type": "string", "enum": [ "EMAIL", "PAGE_VISIT", "FORM_SUBMISSION", "CAMPAIGN_MEMBER", "WORKFLOW", "AUDIENCE", "FIELD_CHANGE", "SFDC_LEAD_CONVERTED" ] } }, "occurredAt": { "type": "object", "description": "Only events that occurred in this half-open range.", "required": [ "start" ], "properties": { "start": { "type": "string", "format": "date-time", "description": "Events that occurred at or after this time." }, "end": { "type": "string", "format": "date-time", "description": "Events that occurred before this time. Must be after `start`." } } }, "cursor": { "type": "string", "description": "The opaque cursor returned as `pagination.nextCursor` by a previous call. Omit it on the first page. Send it without filters, because the cursor carries them; sending both returns `invalid_filter`.", "examples": [ "eyJ2IjoxLCJmIjp7fSwiayI6ImFiYyJ9" ] }, "emailEventsCursor": { "type": "string", "description": "Moves a walk over from the deprecated [Export Email Events](/api-reference/export-email-events) endpoint without re-reading it. Send that endpoint's last `pagination.nextCursor` on the first page, with exactly one `EMAIL_*` type in `types` (the type that walk exported) and no other filters. The export resumes where the email events walk stopped. Other filters, or a `cursor`, return `invalid_filter`." }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 1000, "description": "The maximum number of rows per page. Defaults to 1000. Values are clamped to [1, 5000]." } } }, "examples": { "workflow-events": { "summary": "Workflow events since a date", "value": { "parentTypes": [ "WORKFLOW" ], "occurredAt": { "start": "2026-01-01T00:00:00Z" }, "limit": 1000 } }, "one-contact": { "summary": "One contact's email opens and clicks", "value": { "contactIds": [ "3f2b6c1e-8d4a-4f7e-9a1b-2c3d4e5f6a7b" ], "types": [ "EMAIL_OPEN", "EMAIL_CLICK" ] } }, "next-page": { "summary": "Resume from a cursor", "value": { "cursor": "eyJ2IjoxLCJmIjp7fSwiayI6ImFiYyJ9" } } } } } }, "responses": { "200": { "description": "A page of contact events retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "description": "The current page of contact events.", "items": { "type": "object", "required": [ "eventId", "contactId", "eventType", "parentType", "occurredAt", "createdAt" ], "properties": { "eventId": { "type": "string", "format": "uuid", "description": "The Conversion ID for this event. Stable primary key for warehouse upserts." }, "contactId": { "type": "string", "format": "uuid", "description": "The contact the event belongs to (joins `contacts.id`)." }, "eventType": { "type": "string", "enum": [ "EMAIL_SEND", "EMAIL_DELIVERY", "EMAIL_OPEN", "EMAIL_CLICK", "EMAIL_BOUNCE", "EMAIL_SOFT_BOUNCE", "EMAIL_COMPLAINT", "EMAIL_UNSUBSCRIBE_ALL", "EMAIL_TOPIC_UNSUBSCRIBE", "PAGE_VISIT", "FORM_SUBMISSION", "CAMPAIGN_MEMBER_ADDED", "CAMPAIGN_MEMBER_REMOVED", "CAMPAIGN_MEMBER_STATUS_CHANGED", "CAMPAIGN_MEMBER_FIELD_CHANGED", "WORKFLOW_ENTERED", "WORKFLOW_EXITED", "WORKFLOW_ERROR", "AUDIENCE_ADDED", "AUDIENCE_REMOVED", "FIELD_CHANGE", "SFDC_LEAD_CONVERTED" ], "description": "The specific event." }, "parentType": { "type": "string", "enum": [ "EMAIL", "PAGE_VISIT", "FORM_SUBMISSION", "CAMPAIGN_MEMBER", "WORKFLOW", "AUDIENCE", "FIELD_CHANGE", "SFDC_LEAD_CONVERTED" ], "description": "The event family. Exactly one family object below is set, matching it." }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the event occurred." }, "createdAt": { "type": "string", "format": "date-time", "description": "When Conversion recorded the event. The export is ordered by it, so events recorded late still arrive on a later page." }, "sourceType": { "type": [ "string", "null" ], "description": "The flow that caused the event, such as `WORKFLOW` or `BLAST`." }, "sourceId": { "type": [ "string", "null" ], "format": "uuid", "description": "The ID of that flow." }, "email": { "type": "object", "description": "Set on `EMAIL` events.", "properties": { "emailId": { "type": [ "string", "null" ], "format": "uuid", "description": "The email asset." }, "emailName": { "type": [ "string", "null" ], "description": "Name of the email asset, resolved best-effort. `null` if it cannot be resolved." }, "sentEmailId": { "type": [ "string", "null" ], "format": "uuid", "description": "The individual send." }, "isBot": { "type": "boolean", "description": "Whether the engagement was classified as bot activity." }, "link": { "type": [ "string", "null" ], "description": "The clicked URL, on `EMAIL_CLICK`." }, "topicIds": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "The topics, on `EMAIL_TOPIC_UNSUBSCRIBE`." }, "bounceType": { "type": [ "string", "null" ], "description": "The bounce classification, on bounces." }, "errorMessage": { "type": [ "string", "null" ], "description": "The SMTP diagnostic, on bounces." } } }, "pageVisit": { "type": "object", "description": "Set on `PAGE_VISIT` events.", "properties": { "pageUrl": { "type": [ "string", "null" ], "description": "The visited URL." }, "pageVisitType": { "type": [ "string", "null" ], "description": "The kind of page visited." }, "sentEmailId": { "type": [ "string", "null" ], "format": "uuid", "description": "The send, when the visit came from an email link." }, "sessionId": { "type": [ "string", "null" ], "format": "uuid", "description": "The visitor's session." }, "trackingId": { "type": [ "string", "null" ], "format": "uuid", "description": "The visitor's tracking ID." }, "referrer": { "type": [ "string", "null" ], "description": "The referring URL." }, "utmSource": { "type": [ "string", "null" ], "description": "`utm_source` from the page URL." }, "utmMedium": { "type": [ "string", "null" ], "description": "`utm_medium` from the page URL." }, "utmCampaign": { "type": [ "string", "null" ], "description": "`utm_campaign` from the page URL." }, "utmTerm": { "type": [ "string", "null" ], "description": "`utm_term` from the page URL." }, "utmContent": { "type": [ "string", "null" ], "description": "`utm_content` from the page URL." }, "utmExtra": { "type": [ "object", "null" ], "description": "Any other UTM parameters, keyed by name." }, "landingPageId": { "type": [ "string", "null" ], "format": "uuid", "description": "The Conversion landing page, when the page is one." }, "landingPageRouteId": { "type": [ "string", "null" ], "format": "uuid", "description": "The landing page route." }, "landingPageVersionId": { "type": [ "string", "null" ], "format": "uuid", "description": "The landing page version." }, "adId": { "type": [ "string", "null" ], "description": "The ad that brought the visitor, from ad click parameters or a lead gen form." }, "adGroupId": { "type": [ "string", "null" ], "description": "The ad group (or ad set)." }, "adCampaignId": { "type": [ "string", "null" ], "description": "The ad platform's campaign." }, "adAccountId": { "type": [ "string", "null" ], "description": "The ad account." }, "adKeyword": { "type": [ "string", "null" ], "description": "The paid search keyword." } } }, "formSubmission": { "type": "object", "description": "Set on `FORM_SUBMISSION` events.", "properties": { "formId": { "type": [ "string", "null" ], "format": "uuid", "description": "The form." }, "pageUrl": { "type": [ "string", "null" ], "description": "The page the form was submitted on." }, "fields": { "type": [ "object", "null" ], "description": "The submitted values." }, "sessionId": { "type": [ "string", "null" ], "format": "uuid", "description": "The visitor's session." }, "trackingId": { "type": [ "string", "null" ], "format": "uuid", "description": "The visitor's tracking ID." }, "referrer": { "type": [ "string", "null" ], "description": "The referring URL." }, "utmSource": { "type": [ "string", "null" ], "description": "`utm_source` from the page URL." }, "utmMedium": { "type": [ "string", "null" ], "description": "`utm_medium` from the page URL." }, "utmCampaign": { "type": [ "string", "null" ], "description": "`utm_campaign` from the page URL." }, "utmTerm": { "type": [ "string", "null" ], "description": "`utm_term` from the page URL." }, "utmContent": { "type": [ "string", "null" ], "description": "`utm_content` from the page URL." }, "utmExtra": { "type": [ "object", "null" ], "description": "Any other UTM parameters, keyed by name." }, "landingPageId": { "type": [ "string", "null" ], "format": "uuid", "description": "The Conversion landing page, when the page is one." }, "landingPageRouteId": { "type": [ "string", "null" ], "format": "uuid", "description": "The landing page route." }, "landingPageVersionId": { "type": [ "string", "null" ], "format": "uuid", "description": "The landing page version." }, "adId": { "type": [ "string", "null" ], "description": "The ad that brought the visitor, from ad click parameters or a lead gen form." }, "adGroupId": { "type": [ "string", "null" ], "description": "The ad group (or ad set)." }, "adCampaignId": { "type": [ "string", "null" ], "description": "The ad platform's campaign." }, "adAccountId": { "type": [ "string", "null" ], "description": "The ad account." }, "adKeyword": { "type": [ "string", "null" ], "description": "The paid search keyword." } } }, "campaignMember": { "type": "object", "description": "Set on `CAMPAIGN_MEMBER` events.", "properties": { "campaignId": { "type": [ "string", "null" ], "format": "uuid", "description": "The campaign (joins `POST /v2/exports/campaigns`)." }, "campaignMemberId": { "type": [ "string", "null" ], "format": "uuid", "description": "The campaign membership." }, "campaignTypeId": { "type": [ "string", "null" ], "format": "uuid", "description": "The campaign's type." }, "campaignCategory": { "type": [ "string", "null" ], "description": "The campaign's category." }, "statusId": { "type": [ "string", "null" ], "format": "uuid", "description": "The member status after the event (joins the campaign type's `statuses`)." }, "oldStatusId": { "type": [ "string", "null" ], "format": "uuid", "description": "The member status before a status change." }, "isSuccess": { "type": [ "boolean", "null" ], "description": "Whether the new status counts as success." }, "oldIsSuccess": { "type": [ "boolean", "null" ], "description": "Whether the old status counted as success." }, "fieldKey": { "type": [ "string", "null" ], "description": "The field's key, as in `GET /v2/fields`." }, "oldValue": { "type": [ "string", "null" ], "description": "The previous value, on `CAMPAIGN_MEMBER_FIELD_CHANGED`." }, "newValue": { "type": [ "string", "null" ], "description": "The new value, on `CAMPAIGN_MEMBER_FIELD_CHANGED`." } } }, "workflow": { "type": "object", "description": "Set on `WORKFLOW` events.", "properties": { "workflowId": { "type": [ "string", "null" ], "format": "uuid", "description": "The workflow." }, "workflowRunId": { "type": [ "string", "null" ], "format": "uuid", "description": "Ties one run's entered, exited, and error events together." }, "workflowNodeId": { "type": [ "string", "null" ], "format": "uuid", "description": "The trigger node on entry, the exit node on exit, and the failed node on error." } } }, "audience": { "type": "object", "description": "Set on `AUDIENCE` events.", "properties": { "audienceId": { "type": [ "string", "null" ], "format": "uuid", "description": "The audience." } } }, "fieldChange": { "type": "object", "description": "Set on `FIELD_CHANGE` events.", "properties": { "fieldKey": { "type": [ "string", "null" ], "description": "The field's key, as in `GET /v2/fields`." }, "oldValue": { "type": [ "string", "null" ], "description": "The previous value." }, "newValue": { "type": [ "string", "null" ], "description": "The new value." } } }, "leadConversion": { "type": "object", "description": "Set on `SFDC_LEAD_CONVERTED` events.", "properties": { "oldSalesforceLeadId": { "type": [ "string", "null" ], "description": "The Salesforce Lead that was converted." }, "newSalesforceContactId": { "type": [ "string", "null" ], "description": "The Salesforce Contact it became." } } } } } } } }, "pagination": { "type": "object", "required": [ "nextCursor" ], "properties": { "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or `null` when there are no more results. A page can be short or empty while the cursor is non-null." } } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid-cursor": { "summary": "Malformed cursor", "value": { "error": { "code": "invalid_cursor", "message": "invalid pagination cursor" } } }, "cursor-with-filters": { "summary": "Filters sent with a cursor", "value": { "error": { "code": "invalid_filter", "message": "filters go on the first page only; the cursor carries them" } } }, "invalid-event-type": { "summary": "Unknown event type", "value": { "error": { "code": "invalid_event_type", "message": "invalid event type \"ENTER_AUTOMATION\"" } } }, "inverted-range": { "summary": "End before start", "value": { "error": { "code": "invalid_window", "message": "occurredAt.end must be after occurredAt.start" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "403": { "description": "The export API is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "export-not-enabled": { "summary": "Export not enabled", "value": { "error": { "code": "export_not_enabled", "message": "business is not authorized to use the export API" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to list contact events" } } } } } } } } } }, "/v2/exports/campaigns": { "post": { "operationId": "exportCampaigns", "summary": "Export Campaigns", "description": "Export of every campaign: custom and blast campaigns, webinars, and field events. Each call returns one page; follow `pagination.nextCursor` until it is `null` to read the full set. Ad campaigns are not exported.\n\n> **Request access.** This endpoint is not enabled by default, contact the Conversion team to request access. Calls from accounts without it return `403 export_not_enabled`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "description": "Only campaigns of these categories.", "items": { "type": "string", "enum": [ "CUSTOM", "BLAST", "WEBINAR", "FIELD_EVENT" ] } }, "campaignTypeIds": { "type": "array", "description": "Only campaigns of these campaign types. At most 100.", "items": { "type": "string", "format": "uuid" } }, "includeArchived": { "type": "boolean", "description": "Include archived rows. Defaults to `true`." }, "cursor": { "type": "string", "description": "The opaque cursor returned as `pagination.nextCursor` by a previous call. Omit it on the first page. Send it without filters, because the cursor carries them; sending both returns `invalid_filter`.", "examples": [ "eyJ2IjoxLCJmIjp7fSwiayI6ImFiYyJ9" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "The maximum number of rows per page. Defaults to 50. Values are clamped to [1, 100]." } } }, "examples": { "all": { "summary": "Every campaign", "value": {} }, "webinars": { "summary": "Active webinars only", "value": { "categories": [ "WEBINAR" ], "includeArchived": false } } } } } }, "responses": { "200": { "description": "A page of campaigns retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "campaigns" ], "properties": { "campaigns": { "type": "array", "description": "The current page of campaigns.", "items": { "type": "object", "required": [ "id", "name", "category", "campaignTypeId", "archived", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The Conversion campaign ID." }, "name": { "type": "string", "description": "The campaign's name." }, "description": { "type": [ "string", "null" ], "description": "The campaign's description." }, "category": { "type": "string", "enum": [ "CUSTOM", "BLAST", "WEBINAR", "FIELD_EVENT" ], "description": "The campaign's category." }, "campaignTypeId": { "type": "string", "format": "uuid", "description": "The campaign's type." }, "archived": { "type": "boolean", "description": "Whether the campaign is archived." }, "salesforceCampaignId": { "type": [ "string", "null" ], "description": "The linked Salesforce campaign." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the campaign was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the campaign was last updated." } } } } } }, "pagination": { "type": "object", "required": [ "nextCursor" ], "properties": { "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or `null` when there are no more results. A page can be short or empty while the cursor is non-null." } } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid-cursor": { "summary": "Malformed cursor", "value": { "error": { "code": "invalid_cursor", "message": "invalid pagination cursor" } } }, "cursor-with-filters": { "summary": "Filters sent with a cursor", "value": { "error": { "code": "invalid_filter", "message": "filters go on the first page only; the cursor carries them" } } }, "invalid-category": { "summary": "Unsupported category", "value": { "error": { "code": "invalid_filter", "message": "invalid categories value \"AD_CAMPAIGN\"" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "403": { "description": "The export API is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "export-not-enabled": { "summary": "Export not enabled", "value": { "error": { "code": "export_not_enabled", "message": "business is not authorized to use the export API" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to list campaigns" } } } } } } } } } }, "/v2/exports/campaign-types": { "post": { "operationId": "exportCampaignTypes", "summary": "Export Campaign Types", "description": "Export of every campaign type with its member statuses. Follow `pagination.nextCursor` until it is `null` to read the full set.\n\n> **Request access.** This endpoint is not enabled by default, contact the Conversion team to request access. Calls from accounts without it return `403 export_not_enabled`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "description": "Only types of these categories.", "items": { "type": "string", "enum": [ "CUSTOM", "BLAST", "WEBINAR", "FIELD_EVENT", "AD_CAMPAIGN" ] } }, "includeArchived": { "type": "boolean", "description": "Include archived rows. Defaults to `true`." }, "cursor": { "type": "string", "description": "The opaque cursor returned as `pagination.nextCursor` by a previous call. Omit it on the first page. Send it without filters, because the cursor carries them; sending both returns `invalid_filter`.", "examples": [ "eyJ2IjoxLCJmIjp7fSwiayI6ImFiYyJ9" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "The maximum number of rows per page. Defaults to 50. Values are clamped to [1, 100]." } } }, "examples": { "all": { "summary": "Every campaign type", "value": {} } } } } }, "responses": { "200": { "description": "A page of campaign types retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "campaignTypes" ], "properties": { "campaignTypes": { "type": "array", "description": "The current page of campaign types.", "items": { "type": "object", "required": [ "id", "name", "category", "archived", "statuses" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The campaign type ID." }, "name": { "type": "string", "description": "The type's name." }, "description": { "type": [ "string", "null" ], "description": "The type's description." }, "category": { "type": "string", "description": "The type's category." }, "archived": { "type": "boolean", "description": "Whether the type is archived." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the type was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the type was last updated." }, "statuses": { "type": "array", "description": "The member statuses campaigns of this type use, in order.", "items": { "type": "object", "required": [ "id", "name", "position", "isSuccess", "hidden" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The status ID. Campaign member events reference it as `statusId`." }, "name": { "type": "string", "description": "The status's name." }, "position": { "type": "integer", "description": "The status's 0-based place in the type's order." }, "isSuccess": { "type": "boolean", "description": "Whether the status counts as success." }, "hidden": { "type": "boolean", "description": "Whether the status is hidden from status choices." }, "parentStatusId": { "type": [ "string", "null" ], "format": "uuid", "description": "The status this one rolls up to." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the status was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the status was last updated." } } } } } } } } }, "pagination": { "type": "object", "required": [ "nextCursor" ], "properties": { "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or `null` when there are no more results. A page can be short or empty while the cursor is non-null." } } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid-cursor": { "summary": "Malformed cursor", "value": { "error": { "code": "invalid_cursor", "message": "invalid pagination cursor" } } }, "cursor-with-filters": { "summary": "Filters sent with a cursor", "value": { "error": { "code": "invalid_filter", "message": "filters go on the first page only; the cursor carries them" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "403": { "description": "The export API is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "export-not-enabled": { "summary": "Export not enabled", "value": { "error": { "code": "export_not_enabled", "message": "business is not authorized to use the export API" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to list campaign types" } } } } } } } } } }, "/v2/exports/workflows": { "post": { "operationId": "exportWorkflows", "summary": "Export Workflows", "description": "Export of every workflow. Deleted workflows are not returned. Follow `pagination.nextCursor` until it is `null` to read the full set.\n\n> **Request access.** This endpoint is not enabled by default, contact the Conversion team to request access. Calls from accounts without it return `403 export_not_enabled`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "statuses": { "type": "array", "description": "Only workflows in these statuses.", "items": { "type": "string", "enum": [ "ACTIVE", "ACTIVATING", "PAUSED" ] } }, "cursor": { "type": "string", "description": "The opaque cursor returned as `pagination.nextCursor` by a previous call. Omit it on the first page. Send it without filters, because the cursor carries them; sending both returns `invalid_filter`.", "examples": [ "eyJ2IjoxLCJmIjp7fSwiayI6ImFiYyJ9" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "The maximum number of rows per page. Defaults to 50. Values are clamped to [1, 100]." } } }, "examples": { "active": { "summary": "Active workflows", "value": { "statuses": [ "ACTIVE" ] } } } } } }, "responses": { "200": { "description": "A page of workflows retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "workflows" ], "properties": { "workflows": { "type": "array", "description": "The current page of workflows.", "items": { "type": "object", "required": [ "id", "name", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The workflow ID. Workflow events reference it as `workflowId`." }, "name": { "type": "string", "description": "The workflow's name." }, "status": { "type": "string", "enum": [ "ACTIVE", "ACTIVATING", "PAUSED" ], "description": "The workflow's status." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the workflow was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the workflow was last updated." }, "activatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the workflow was last activated." } } } } } }, "pagination": { "type": "object", "required": [ "nextCursor" ], "properties": { "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or `null` when there are no more results. A page can be short or empty while the cursor is non-null." } } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid-cursor": { "summary": "Malformed cursor", "value": { "error": { "code": "invalid_cursor", "message": "invalid pagination cursor" } } }, "cursor-with-filters": { "summary": "Filters sent with a cursor", "value": { "error": { "code": "invalid_filter", "message": "filters go on the first page only; the cursor carries them" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "403": { "description": "The export API is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "export-not-enabled": { "summary": "Export not enabled", "value": { "error": { "code": "export_not_enabled", "message": "business is not authorized to use the export API" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to list workflows" } } } } } } } } } }, "/v2/exports/audiences": { "post": { "operationId": "exportAudiences", "summary": "Export Audiences", "description": "Export of every audience. Follow `pagination.nextCursor` until it is `null` to read the full set.\n\n> **Request access.** This endpoint is not enabled by default, contact the Conversion team to request access. Calls from accounts without it return `403 export_not_enabled`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "types": { "type": "array", "description": "Only audiences of these types.", "items": { "type": "string", "enum": [ "STATIC", "DYNAMIC" ] } }, "cursor": { "type": "string", "description": "The opaque cursor returned as `pagination.nextCursor` by a previous call. Omit it on the first page. Send it without filters, because the cursor carries them; sending both returns `invalid_filter`.", "examples": [ "eyJ2IjoxLCJmIjp7fSwiayI6ImFiYyJ9" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "The maximum number of rows per page. Defaults to 50. Values are clamped to [1, 100]." } } }, "examples": { "all": { "summary": "Every audience", "value": {} } } } } }, "responses": { "200": { "description": "A page of audiences retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "audiences" ], "properties": { "audiences": { "type": "array", "description": "The current page of audiences.", "items": { "type": "object", "required": [ "id", "name", "type", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The audience ID." }, "name": { "type": "string", "description": "The audience's name." }, "type": { "type": "string", "enum": [ "STATIC", "DYNAMIC" ], "description": "Whether membership is managed by hand or by a filter." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the audience was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the audience was last updated." } } } } } }, "pagination": { "type": "object", "required": [ "nextCursor" ], "properties": { "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or `null` when there are no more results. A page can be short or empty while the cursor is non-null." } } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid-cursor": { "summary": "Malformed cursor", "value": { "error": { "code": "invalid_cursor", "message": "invalid pagination cursor" } } }, "cursor-with-filters": { "summary": "Filters sent with a cursor", "value": { "error": { "code": "invalid_filter", "message": "filters go on the first page only; the cursor carries them" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "403": { "description": "The export API is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "export-not-enabled": { "summary": "Export not enabled", "value": { "error": { "code": "export_not_enabled", "message": "business is not authorized to use the export API" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to list audiences" } } } } } } } } } }, "/v2/exports/audience-members": { "post": { "operationId": "exportAudienceMembers", "summary": "Export Audience Members", "description": "Export of which contacts are in which audiences right now. Removed members are not returned, so treat each full walk as a snapshot. Follow `pagination.nextCursor` until it is `null`.\n\n> **Request access.** This endpoint is not enabled by default, contact the Conversion team to request access. Calls from accounts without it return `403 export_not_enabled`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "audienceIds": { "type": "array", "description": "Only these audiences' members. At most 100.", "items": { "type": "string", "format": "uuid" } }, "cursor": { "type": "string", "description": "The opaque cursor returned as `pagination.nextCursor` by a previous call. Omit it on the first page. Send it without filters, because the cursor carries them; sending both returns `invalid_filter`.", "examples": [ "eyJ2IjoxLCJmIjp7fSwiayI6ImFiYyJ9" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 1000, "description": "The maximum number of rows per page. Defaults to 1000. Values are clamped to [1, 5000]." } } }, "examples": { "all": { "summary": "Every membership", "value": { "limit": 1000 } }, "one-audience": { "summary": "One audience", "value": { "audienceIds": [ "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" ] } } } } } }, "responses": { "200": { "description": "A page of audience memberships retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "members" ], "properties": { "members": { "type": "array", "description": "The current page of audience memberships.", "items": { "type": "object", "required": [ "audienceId", "contactId", "createdAt", "updatedAt" ], "properties": { "audienceId": { "type": "string", "format": "uuid", "description": "The audience." }, "contactId": { "type": "string", "format": "uuid", "description": "The contact (joins `contacts.id`)." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the contact joined the audience." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the membership was last updated." }, "partitionId": { "type": "string", "format": "uuid", "description": "The contact's partition, for members of partitioned audiences. Omitted otherwise." } } } } } }, "pagination": { "type": "object", "required": [ "nextCursor" ], "properties": { "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or `null` when there are no more results. A page can be short or empty while the cursor is non-null." } } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid-cursor": { "summary": "Malformed cursor", "value": { "error": { "code": "invalid_cursor", "message": "invalid pagination cursor" } } }, "cursor-with-filters": { "summary": "Filters sent with a cursor", "value": { "error": { "code": "invalid_filter", "message": "filters go on the first page only; the cursor carries them" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "403": { "description": "The export API is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "export-not-enabled": { "summary": "Export not enabled", "value": { "error": { "code": "export_not_enabled", "message": "business is not authorized to use the export API" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to list audience members" } } } } } } } } } }, "/v2/exports/touchpoints": { "post": { "operationId": "exportTouchpoints", "summary": "Export Touchpoints", "description": "Bulk, incremental export of Mosaic touchpoints, computed under your attribution settings and ordered by when they occurred. Requires Mosaic in addition to export access.\n\nSend `occurredAt` on the first call, then pass `pagination.nextCursor` back as `cursor` until it is `null` or stops changing. Without `occurredAt.end`, the export stops a day before now so sessions and email clicks settle first. Persist the last cursor between syncs to resume.\n\n> **Request access.** This endpoint is not enabled by default, contact the Conversion team to request access. Calls from accounts without it return `403 export_not_enabled`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "occurredAt": { "type": "object", "description": "The half-open range to export. Required on the first call and omitted with `cursor`.", "required": [ "start" ], "properties": { "start": { "type": "string", "format": "date-time", "description": "Touchpoints that occurred at or after this time." }, "end": { "type": "string", "format": "date-time", "description": "Touchpoints that occurred before this time. Must be after `start`. Omit it to keep a stored cursor advancing as new touchpoints settle." } } }, "cursor": { "type": "string", "description": "The opaque cursor returned as `pagination.nextCursor` by a previous call. Omit it on the first page. Send it without filters, because the cursor carries them; sending both returns `invalid_filter`.", "examples": [ "eyJ2IjoxLCJmIjp7fSwiayI6ImFiYyJ9" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 1000, "description": "The maximum number of rows per page. Defaults to 1000. Values are clamped to [1, 5000]." } } }, "examples": { "first-page": { "summary": "Start a sync", "value": { "occurredAt": { "start": "2026-01-01T00:00:00Z" }, "limit": 1000 } }, "next-page": { "summary": "Resume from a cursor", "value": { "cursor": "eyJ2IjoxLCJmIjp7fSwiayI6ImFiYyJ9" } } } } } }, "responses": { "200": { "description": "A page of touchpoints retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "touchpoints" ], "properties": { "touchpoints": { "type": "array", "description": "The current page of touchpoints.", "items": { "type": "object", "required": [ "touchpointId", "contactId", "touchType", "occurredAt" ], "properties": { "touchpointId": { "type": "string", "description": "The touchpoint's ID. Stable across exports, so use it as the primary key.", "examples": [ "ws:3f2b6c1e-8d4a-4f7e-9a1b-2c3d4e5f6a7b:9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" ] }, "contactId": { "type": "string", "format": "uuid", "description": "The contact (joins `contacts.id`)." }, "touchType": { "type": "string", "enum": [ "WEB_SESSION", "EMAIL_CLICK", "CAMPAIGN_SUCCESS", "LEAD_GEN_FORM_SUBMISSION" ], "description": "The kind of touch." }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the touch happened." }, "sessionId": { "type": [ "string", "null" ], "format": "uuid", "description": "The web session, on web touches and email touches that landed one." }, "formId": { "type": [ "string", "null" ], "format": "uuid", "description": "The form submitted in the session or on the ad platform." }, "landingPageUrl": { "type": [ "string", "null" ], "description": "The first page of the session." }, "referrer": { "type": [ "string", "null" ], "description": "The referring URL." }, "keyword": { "type": [ "string", "null" ], "description": "The paid search keyword." }, "utmSource": { "type": [ "string", "null" ], "description": "`utm_source`. Empty on `CAMPAIGN_SUCCESS`." }, "utmMedium": { "type": [ "string", "null" ], "description": "`utm_medium`. Empty on `CAMPAIGN_SUCCESS`." }, "utmCampaign": { "type": [ "string", "null" ], "description": "`utm_campaign`. Empty on `CAMPAIGN_SUCCESS`." }, "utmTerm": { "type": [ "string", "null" ], "description": "`utm_term`. Empty on `CAMPAIGN_SUCCESS`." }, "utmContent": { "type": [ "string", "null" ], "description": "`utm_content`. Empty on `CAMPAIGN_SUCCESS`." }, "adId": { "type": [ "string", "null" ], "description": "The ad platform's ad ID." }, "adGroupId": { "type": [ "string", "null" ], "description": "The ad platform's ad group (or ad set) ID." }, "adCampaignId": { "type": [ "string", "null" ], "description": "The ad platform's campaign ID." }, "adAccountId": { "type": [ "string", "null" ], "description": "The ad platform's account ID." }, "adProvider": { "type": [ "string", "null" ], "enum": [ "GOOGLE", "META", "LINKEDIN", null ], "description": "The ad platform." }, "campaignId": { "type": [ "string", "null" ], "description": "The campaign on `CAMPAIGN_SUCCESS`, the Conversion ad campaign on web and lead gen touches, and the blast on email touches." }, "channelId": { "type": [ "string", "null" ], "format": "uuid", "description": "The Mosaic channel the touch was assigned to." }, "subchannelId": { "type": [ "string", "null" ], "format": "uuid", "description": "The Mosaic subchannel, when the channel has one that matched." } } } } } }, "pagination": { "type": "object", "required": [ "nextCursor" ], "properties": { "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or `null` when there are no more results. A page can be short or empty while the cursor is non-null." } } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid-cursor": { "summary": "Malformed cursor", "value": { "error": { "code": "invalid_cursor", "message": "invalid pagination cursor" } } }, "cursor-with-filters": { "summary": "Filters sent with a cursor", "value": { "error": { "code": "invalid_filter", "message": "filters go on the first page only; the cursor carries them" } } }, "missing-range": { "summary": "No range and no cursor", "value": { "error": { "code": "invalid_window", "message": "occurredAt.start is required when no cursor is supplied" } } }, "inverted-range": { "summary": "End before start", "value": { "error": { "code": "invalid_window", "message": "occurredAt.end must be after occurredAt.start" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "403": { "description": "The export API, or Mosaic, is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "export-not-enabled": { "summary": "Export not enabled", "value": { "error": { "code": "export_not_enabled", "message": "business is not authorized to use the export API" } } }, "mosaic-not-enabled": { "summary": "Mosaic not enabled", "value": { "error": { "code": "export_not_enabled", "message": "business is not authorized to export this data" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to list touchpoints" } } } } } } } } } }, "/v2/full-delete": { "post": { "operationId": "fullDelete", "summary": "Full Delete Contact", "description": "Permanently delete a contact and suppress its identifiers for GDPR and CCPA erasure requests.\n\nIdentify the contact with `email`, `cnvContactId`, or `userId`. At least one is required.\n\nA full delete removes the contact's personal data and engagement data as described in [Data deletion](/product-docs/gdpr/data-deletion), then suppresses the provided identifiers so the contact is not re-created.\n\nDeletion is permanent and cannot be reversed.\n\n> **Request access.** This endpoint is not enabled by default, contact the Conversion team to request access. Calls from accounts without it return `403 export_not_enabled`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "The contact's email address. At least one of `email`, `cnvContactId`, or `userId` is required.", "examples": [ "jane@example.com" ] }, "cnvContactId": { "type": "string", "format": "uuid", "description": "The Conversion contact ID. At least one of `email`, `cnvContactId`, or `userId` is required.", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "userId": { "type": "string", "description": "The external user identifier for the contact, as passed to the Events endpoints. At least one of `email`, `cnvContactId`, or `userId` is required.", "examples": [ "user_12345" ] } } }, "examples": { "by-email": { "summary": "Delete by email", "value": { "email": "jane@example.com" } }, "by-contact-id": { "summary": "Delete by contact ID", "value": { "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "by-user-id": { "summary": "Delete by user ID", "value": { "userId": "user_12345" } } } } } }, "responses": { "204": { "description": "The contact was deleted and its identifiers suppressed. The response has no body." }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing-identifier": { "summary": "Missing identifier", "value": { "error": { "code": "missing_identifier", "message": "one of 'email', 'cnvContactId', or 'userId' is required" } } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "Missing or invalid API key", "value": { "error": { "code": "unauthorized", "message": "API key is required" } } } } } } }, "403": { "description": "The full delete API is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "export-not-enabled": { "summary": "Full delete not enabled", "value": { "error": { "code": "export_not_enabled", "message": "business is not authorized to use the full delete API" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "summary": "Internal error", "value": { "error": { "code": "internal_error", "message": "failed to delete contact" } } } } } } } } } } } }