--- title: "Export Contact Events" method: POST path: "/v2/exports/contact-events" --- # Export Contact Events `POST /v2/exports/contact-events` ## Request - Base URL: `https://pub-api.conversion.ai/api` - URL: `https://pub-api.conversion.ai/api/v2/exports/contact-events` - Auth: one of: - API key in header `X-API-Key` - API key in query parameter `api_key` 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`. Send 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. > **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`. ## Request body - object - `contactIds` string[]: Only these contacts' events. At most 100. - `types` string[]: Only these event types. - `parentTypes` string[]: Only these event families. With `types`, an event must match both. - `occurredAt` object: Only events that occurred in this half-open range. - `start` string, date-time, required: Events that occurred at or after this time. - `end` string, date-time: Events that occurred before this time. Must be after `start`. - `cursor` string: 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`. - `emailEventsCursor` string: 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` integer: The maximum number of rows per page. Defaults to 1000. Values are clamped to [1, 5000]. ## Response `200` A page of contact events retrieved successfully. - object - `data` object - `events` object[], required: The current page of contact events. - `eventId` string, uuid, required: The Conversion ID for this event. Stable primary key for warehouse upserts. - `contactId` string, uuid, required: The contact the event belongs to (joins `contacts.id`). - `eventType` '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', required: The specific event. - `parentType` 'EMAIL' | 'PAGE_VISIT' | 'FORM_SUBMISSION' | 'CAMPAIGN_MEMBER' | 'WORKFLOW' | 'AUDIENCE' | 'FIELD_CHANGE' | 'SFDC_LEAD_CONVERTED', required: The event family. Exactly one family object below is set, matching it. - `occurredAt` string, date-time, required: When the event occurred. - `createdAt` string, date-time, required: When Conversion recorded the event. The export is ordered by it, so events recorded late still arrive on a later page. - `sourceType` string, nullable: The flow that caused the event, such as `WORKFLOW` or `BLAST`. - `sourceId` string, uuid, nullable: The ID of that flow. - `email` object: Set on `EMAIL` events. - `emailId` string, uuid, nullable: The email asset. - `emailName` string, nullable: Name of the email asset, resolved best-effort. `null` if it cannot be resolved. - `sentEmailId` string, uuid, nullable: The individual send. - `isBot` boolean: Whether the engagement was classified as bot activity. - `link` string, nullable: The clicked URL, on `EMAIL_CLICK`. - `topicIds` string[], nullable: The topics, on `EMAIL_TOPIC_UNSUBSCRIBE`. - `bounceType` string, nullable: The bounce classification, on bounces. - `errorMessage` string, nullable: The SMTP diagnostic, on bounces. - `pageVisit` object: Set on `PAGE_VISIT` events. - `pageUrl` string, nullable: The visited URL. - `pageVisitType` string, nullable: The kind of page visited. - `sentEmailId` string, uuid, nullable: The send, when the visit came from an email link. - `sessionId` string, uuid, nullable: The visitor's session. - `trackingId` string, uuid, nullable: The visitor's tracking ID. - `referrer` string, nullable: The referring URL. - `utmSource` string, nullable: `utm_source` from the page URL. - `utmMedium` string, nullable: `utm_medium` from the page URL. - `utmCampaign` string, nullable: `utm_campaign` from the page URL. - `utmTerm` string, nullable: `utm_term` from the page URL. - `utmContent` string, nullable: `utm_content` from the page URL. - `utmExtra` object, nullable: Any other UTM parameters, keyed by name. - `landingPageId` string, uuid, nullable: The Conversion landing page, when the page is one. - `landingPageRouteId` string, uuid, nullable: The landing page route. - `landingPageVersionId` string, uuid, nullable: The landing page version. - `adId` string, nullable: The ad that brought the visitor, from ad click parameters or a lead gen form. - `adGroupId` string, nullable: The ad group (or ad set). - `adCampaignId` string, nullable: The ad platform's campaign. - `adAccountId` string, nullable: The ad account. - `adKeyword` string, nullable: The paid search keyword. - `formSubmission` object: Set on `FORM_SUBMISSION` events. - `formId` string, uuid, nullable: The form. - `pageUrl` string, nullable: The page the form was submitted on. - `fields` object, nullable: The submitted values. - `sessionId` string, uuid, nullable: The visitor's session. - `trackingId` string, uuid, nullable: The visitor's tracking ID. - `referrer` string, nullable: The referring URL. - `utmSource` string, nullable: `utm_source` from the page URL. - `utmMedium` string, nullable: `utm_medium` from the page URL. - `utmCampaign` string, nullable: `utm_campaign` from the page URL. - `utmTerm` string, nullable: `utm_term` from the page URL. - `utmContent` string, nullable: `utm_content` from the page URL. - `utmExtra` object, nullable: Any other UTM parameters, keyed by name. - `landingPageId` string, uuid, nullable: The Conversion landing page, when the page is one. - `landingPageRouteId` string, uuid, nullable: The landing page route. - `landingPageVersionId` string, uuid, nullable: The landing page version. - `adId` string, nullable: The ad that brought the visitor, from ad click parameters or a lead gen form. - `adGroupId` string, nullable: The ad group (or ad set). - `adCampaignId` string, nullable: The ad platform's campaign. - `adAccountId` string, nullable: The ad account. - `adKeyword` string, nullable: The paid search keyword. - `campaignMember` object: Set on `CAMPAIGN_MEMBER` events. - `campaignId` string, uuid, nullable: The campaign (joins `POST /v2/exports/campaigns`). - `campaignMemberId` string, uuid, nullable: The campaign membership. - `campaignTypeId` string, uuid, nullable: The campaign's type. - `campaignCategory` string, nullable: The campaign's category. - `statusId` string, uuid, nullable: The member status after the event (joins the campaign type's `statuses`). - `oldStatusId` string, uuid, nullable: The member status before a status change. - `isSuccess` boolean, nullable: Whether the new status counts as success. - `oldIsSuccess` boolean, nullable: Whether the old status counted as success. - `fieldKey` string, nullable: The field's key, as in `GET /v2/fields`. - `oldValue` string, nullable: The previous value, on `CAMPAIGN_MEMBER_FIELD_CHANGED`. - `newValue` string, nullable: The new value, on `CAMPAIGN_MEMBER_FIELD_CHANGED`. - `workflow` object: Set on `WORKFLOW` events. - `workflowId` string, uuid, nullable: The workflow. - `workflowRunId` string, uuid, nullable: Ties one run's entered, exited, and error events together. - `workflowNodeId` string, uuid, nullable: The trigger node on entry, the exit node on exit, and the failed node on error. - `audience` object: Set on `AUDIENCE` events. - `audienceId` string, uuid, nullable: The audience. - `fieldChange` object: Set on `FIELD_CHANGE` events. - `fieldKey` string, nullable: The field's key, as in `GET /v2/fields`. - `oldValue` string, nullable: The previous value. - `newValue` string, nullable: The new value. - `leadConversion` object: Set on `SFDC_LEAD_CONVERTED` events. - `oldSalesforceLeadId` string, nullable: The Salesforce Lead that was converted. - `newSalesforceContactId` string, nullable: The Salesforce Contact it became. - `pagination` object - `nextCursor` string, nullable, required: 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. ## Other responses - `400`: The request was malformed or contained invalid data. - `401`: Authentication failed. - `403`: The export API is not enabled for this account. - `500`: An unexpected server error occurred. --- [API](https://skmtc.dev/conversion/apis/conversion-api.md) - [All operations](https://skmtc.dev/conversion/apis/conversion-api/llms.txt) - [OpenAPI document](https://skmtc.dev/conversion/apis/conversion-api/revisions/8422f815402a?raw)