> ## Documentation Index > Fetch the complete documentation index at: https://docs.conversion.ai/llms.txt > Use this file to discover all available pages before exploring further. # Batch Upsert Custom Object Records > Create or update up to 200 records of one custom object. Create the custom object in Conversion and define its fields first. Each record requires a stable clientDedupKey from your source system. Requires edit-records access to the custom object. HTTP 200 includes one result per input, in order, with processed, succeeded, and failed counts. Repeated keys in a batch are processed sequentially by the same ingestion path used for warehouse syncs. Correct missing keys and invalid fields before retrying. Invalid requests, access denials, or service failures return a non-200 response. Relationship values use the target record's clientDedupKey, with an email fallback for contacts. Missing targets remain pending, so record success does not mean every relationship has resolved. This endpoint does not create companies, opportunities, or other relationship targets. ## OpenAPI ````yaml /openapi.json post /v2/custom-objects/{customObjectId}/records/batch openapi: 3.1.0 info: title: Conversion 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: [] paths: /v2/custom-objects/{customObjectId}/records/batch: post: summary: Batch Upsert Custom Object Records description: >- Create or update up to 200 records of one custom object. Create the custom object in Conversion and define its fields first. Each record requires a stable clientDedupKey from your source system. Requires edit-records access to the custom object. HTTP 200 includes one result per input, in order, with processed, succeeded, and failed counts. Repeated keys in a batch are processed sequentially by the same ingestion path used for warehouse syncs. Correct missing keys and invalid fields before retrying. Invalid requests, access denials, or service failures return a non-200 response. Relationship values use the target record's clientDedupKey, with an email fallback for contacts. Missing targets remain pending, so record success does not mean every relationship has resolved. This endpoint does not create companies, opportunities, or other relationship targets. operationId: batchUpsertCustomObjectRecords 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: clientDedupKey: type: string minLength: 1 description: >- Stable upstream record key, unique within this custom object. Creates a missing record or updates the existing match. 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. Relationship values use the target record's clientDedupKey; contact targets also support email as a fallback. Reverse relationship and system-owned fields are read-only. JSON numbers retain their supplied precision; identifiers must be strings. required: - clientDedupKey required: - records example: records: - clientDedupKey: 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. clientDedupKey: type: string 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 clientDedupKey: 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' 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__`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.