Conversion Forms API

openapi: 3.2.0
info:
  title: Conversion Forms 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: Forms
paths:
  /v2/forms:
    get:
      operationId: listForms
      summary: List Forms
      description: 'List tracked, published Conversion-native forms with basic metadata. External forms (custom HTML) and ad lead-gen forms (LinkedIn, Meta) are excluded, as are untracked, archived, and never-published forms.


        Results are paginated with an opaque cursor returned as `pagination.nextCursor`. Pass it back as the `cursor` query parameter to fetch the next page. A `null` cursor means there are no more results.'
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        description: The maximum number of forms to return per page. Defaults to 50. Values are clamped to the range [1, 100] rather than rejected; values above 100 return 100 results.
      - 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: Forms retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required:
                    - forms
                    properties:
                      forms:
                        type: array
                        description: The current page of forms.
                        items:
                          type: object
                          required:
                          - id
                          - name
                          - createdAt
                          - updatedAt
                          - submissionCount
                          - lastSubmittedAt
                          properties:
                            id:
                              type: string
                              format: uuid
                              description: The Conversion form id. Use it as the `formId` path parameter of `GET /v2/forms/{formId}`.
                              examples:
                              - 9f3c1a2e-6b7d-4e2a-9c1f-1a2b3c4d5e6f
                            name:
                              type: string
                              description: The form's display name.
                              examples:
                              - Demo Request
                            createdAt:
                              type: string
                              format: date-time
                              description: When the form was created.
                            updatedAt:
                              type: string
                              format: date-time
                              description: When the form was last updated.
                            submissionCount:
                              type: integer
                              description: The total number of submissions received by the form.
                              examples:
                              - 412
                            lastSubmittedAt:
                              type:
                              - string
                              - 'null'
                              format: date-time
                              description: When the form last received a submission, or `null` if it has never been submitted.
                  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 forms
                  value:
                    data:
                      forms:
                      - id: 9f3c1a2e-6b7d-4e2a-9c1f-1a2b3c4d5e6f
                        name: Demo Request
                        createdAt: '2026-05-01T12:00:00Z'
                        updatedAt: '2026-06-11T09:30:00Z'
                        submissionCount: 412
                        lastSubmittedAt: '2026-07-10T08:15:00Z'
                      - id: 2d4e6f8a-1b3c-4d5e-8f9a-0b1c2d3e4f5a
                        name: Newsletter Signup
                        createdAt: '2026-03-14T10:00:00Z'
                        updatedAt: '2026-03-14T10:00:00Z'
                        submissionCount: 0
                        lastSubmittedAt: null
                    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 forms
      tags:
      - Forms
  /v2/forms/{formId}:
    get:
      operationId: getForm
      summary: Get Form
      description: 'Get a tracked, published Conversion-native form by id, including the fields of its published definition. Each field''s `fieldId` is the key used to reference the field in the forms JavaScript API and in submission data. `DROPDOWN` and `MULTI_CHECKBOX` fields also list their selectable `options`, so you can map a submitted value back to the option label a visitor saw. A `MULTI_CHECKBOX` submits the values of every ticked option as a single semicolon-separated string, such as `analytics;automation`.


        Only tracked, published Conversion-native forms resolve; unknown ids, forms belonging to another workspace, external and ad forms, and untracked, archived, or never-published forms all return a `form_not_found` error.'
      parameters:
      - name: formId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The Conversion form id, as returned by `GET /v2/forms`.
        examples:
          form:
            value: 9f3c1a2e-6b7d-4e2a-9c1f-1a2b3c4d5e6f
      responses:
        '200':
          description: Form retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required:
                    - form
                    properties:
                      form:
                        type: object
                        required:
                        - id
                        - name
                        - createdAt
                        - updatedAt
                        - submissionCount
                        - lastSubmittedAt
                        - fields
                        properties:
                          id:
                            type: string
                            format: uuid
                            description: The Conversion form id. Use it as the `formId` path parameter of `GET /v2/forms/{formId}`.
                            examples:
                            - 9f3c1a2e-6b7d-4e2a-9c1f-1a2b3c4d5e6f
                          name:
                            type: string
                            description: The form's display name.
                            examples:
                            - Demo Request
                          createdAt:
                            type: string
                            format: date-time
                            description: When the form was created.
                          updatedAt:
                            type: string
                            format: date-time
                            description: When the form was last updated.
                          submissionCount:
                            type: integer
                            description: The total number of submissions received by the form.
                            examples:
                            - 412
                          lastSubmittedAt:
                            type:
                            - string
                            - 'null'
                            format: date-time
                            description: When the form last received a submission, or `null` if it has never been submitted.
                          fields:
                            type: array
                            description: The fields of the published form definition, including hidden fields.
                            items:
                              type: object
                              required:
                              - fieldId
                              - name
                              - type
                              - required
                              - hidden
                              properties:
                                fieldId:
                                  type: string
                                  description: The field's id in the form definition. Use this id to reference the field in the forms JavaScript API; submission data is keyed by it.
                                  examples:
                                  - aa8b2c1d-4e5f-4a6b-8c9d-0e1f2a3b4c5d
                                name:
                                  type: string
                                  description: The field's name as configured in the form editor, unique within the form. It also labels the field's values in submission data.
                                  examples:
                                  - email
                                type:
                                  type: string
                                  enum:
                                  - SHORT_ANSWER
                                  - LONG_ANSWER
                                  - DROPDOWN
                                  - NUMBER
                                  - EMAIL
                                  - PHONE_NUMBER
                                  - LINK
                                  - SINGLE_CHECKBOX
                                  - MULTI_CHECKBOX
                                  - HIDDEN
                                  description: The field input type. `DROPDOWN` and `MULTI_CHECKBOX` fields submit option values listed under `options`, a `MULTI_CHECKBOX` joining its ticked values with `;`. `HIDDEN` fields are populated from the page rather than typed by the visitor.
                                required:
                                  type: boolean
                                  description: Whether the field must be filled to submit. Always `false` for hidden fields.
                                hidden:
                                  type: boolean
                                  description: Whether the field is a hidden field.
                                options:
                                  type: array
                                  description: 'The selectable options of a `DROPDOWN` or `MULTI_CHECKBOX` field, in the order they are configured in the form editor. Omitted for every other field type.


                                    A submission carries option values, never labels: a `DROPDOWN` field submits one option value, and a `MULTI_CHECKBOX` field submits the selected option values as a single semicolon-separated string, such as `analytics;automation`. A submitted value that does not match one of these options is rejected.'
                                  items:
                                    type: object
                                    required:
                                    - label
                                    - value
                                    properties:
                                      label:
                                        type: string
                                        description: The option's text as shown on the form. Labels are optional in the form editor; when empty, the form displays `value` instead.
                                        examples:
                                        - 1-10 employees
                                      value:
                                        type: string
                                        description: The value a submission carries for the field when this option is selected. Unique within the field.
                                        examples:
                                        - 1-10
              examples:
                success:
                  summary: A form with visible and hidden fields
                  value:
                    data:
                      form:
                        id: 9f3c1a2e-6b7d-4e2a-9c1f-1a2b3c4d5e6f
                        name: Demo Request
                        createdAt: '2026-05-01T12:00:00Z'
                        updatedAt: '2026-06-11T09:30:00Z'
                        submissionCount: 412
                        lastSubmittedAt: '2026-07-10T08:15:00Z'
                        fields:
                        - fieldId: aa8b2c1d-4e5f-4a6b-8c9d-0e1f2a3b4c5d
                          name: email
                          type: EMAIL
                          required: true
                          hidden: false
                        - fieldId: bb9c3d2e-5f6a-4b7c-9d0e-1f2a3b4c5d6e
                          name: company_size
                          type: DROPDOWN
                          required: false
                          hidden: false
                          options:
                          - label: 1-10 employees
                            value: 1-10
                          - label: 11-50 employees
                            value: 11-50
                          - label: 51+ employees
                            value: 51+
                        - fieldId: cc0d4e3f-6a7b-4c8d-0e1f-2a3b4c5d6e7f
                          name: message
                          type: LONG_ANSWER
                          required: false
                          hidden: false
                        - fieldId: dd1e5f4a-7b8c-4d9e-1f2a-3b4c5d6e7f8a
                          name: utm_source
                          type: HIDDEN
                          required: false
                          hidden: true
        '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:
                form-not-found:
                  summary: Form not found
                  value:
                    error:
                      code: form_not_found
                      message: form 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 form
      tags:
      - Forms
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.'