Conversion Custom Objects API

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