Conversion Campaigns API
The Campaigns API from Conversion — 4 operation(s) for campaigns.
The Campaigns API from Conversion — 4 operation(s) for campaigns.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/conversion:conversion-campaigns-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Conversion Campaigns 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: []
tags:
- name: Campaigns
paths:
/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}`.
Results 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
tags:
- 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
tags:
- Campaigns
/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
tags:
- Campaigns
/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.
Status 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
tags:
- Campaigns
components:
schemas:
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'
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_<key_id>_<secret>`.'
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.'