Conversion Campaigns API

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