Conversion

Conversion Audiences API

The Audiences API from Conversion — 1 operation(s) for audiences.

Documentation GitHub OpenAPI

Operations 2

POST /v2/audiences/{audienceId}/contacts Add Contact to Audience #

DELETE /v2/audiences/{audienceId}/contacts Remove Contact from Audience #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

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.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/conversion:conversion-audiences-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API 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.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

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.'