Conversion Custom Objects API
The Custom Objects API from Conversion — 1 operation(s) for custom objects.
The Custom Objects API from Conversion — 1 operation(s) for custom objects.
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-custom-objects-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 Custom Objects 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: Custom Objects
paths:
/v2/custom-objects/{customObjectId}/records/batch:
post:
operationId: batchUpsertCustomObjectRecords
summary: Batch Upsert Custom Object Records
description: Create or update up to 200 records of one custom object in a single request, with a result for each record. Records are matched by `objectId`.
parameters:
- name: customObjectId
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the existing custom object created in Conversion.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
records:
type: array
minItems: 1
maxItems: 200
items:
type: object
properties:
objectId:
type: string
minLength: 1
description: Your system's ID for the record, unique within this custom object. Creates the record if no match exists, otherwise updates it. Repeated values in one batch are applied in order. Leading or trailing whitespace is rejected.
fields:
type: object
additionalProperties:
type:
- string
- number
- boolean
- 'null'
description: Existing field keys mapped to values. Omitted fields stay unchanged; null or an empty string clears a field. A relationship value names the related record by its `objectId`, or a contact by its `userId` or email. A link to a record that doesn't exist yet stays pending and completes if that record is created within a few days; related records are never created. Reverse relationship and system-owned fields are read-only. JSON numbers retain their supplied precision; identifiers must be strings.
required:
- objectId
required:
- records
example:
records:
- objectId: org-123
fields:
dashboard_region: us
responses:
'200':
description: Per-record write results.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
processed:
type: integer
succeeded:
type: integer
failed:
type: integer
results:
type: array
items:
type: object
properties:
success:
type: boolean
id:
type: string
format: uuid
description: Conversion ID of the saved record. Returned on success; not an input identifier for this endpoint.
objectId:
type: string
description: The `objectId` sent for this record.
operation:
type: string
enum:
- CREATE
- UPDATE
error:
type: string
description: 'Per-record error code: invalid_identifier, invalid_field, upsert_skipped, or upsert_failed.'
message:
type: string
skipped:
type: boolean
description: True when CRM intentionally did not write the record.
fieldErrors:
type: array
description: Field keys and reasons reported by CRM when a record fails field validation.
items:
type: object
required:
- key
- reason
properties:
key:
type: string
reason:
type: string
description: CRM rejection reason, such as DROPPED_TYPE_MISMATCH.
required:
- success
required:
- processed
- succeeded
- failed
- results
example:
data:
processed: 1
succeeded: 1
failed: 0
results:
- success: true
id: 1cfa4f66-5db2-4ce5-b4b0-b9c801f3ad7c
objectId: org-123
operation: CREATE
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: The API key lacks permission, or custom objects are not enabled.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Resource not found in this workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Unexpected service failure.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Custom Objects
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.'