Conversion Forms API
The Forms API from Conversion — 2 operation(s) for forms.
The Forms API from Conversion — 2 operation(s) for forms.
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-forms-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 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.'