Conversion Audiences API
The Audiences API from Conversion — 1 operation(s) for audiences.
The Audiences API from Conversion — 1 operation(s) for audiences.
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-audiences-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 Audiences 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: Audiences
paths:
/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
tags:
- Audiences
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'
tags:
- Audiences
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.'