---
title: "Batch Upsert Custom Object Records"
method: POST
path: "/v2/custom-objects/{customObjectId}/records/batch"
---

# Batch Upsert Custom Object Records

`POST /v2/custom-objects/{customObjectId}/records/batch`

## Request

- Base URL: `https://pub-api.conversion.ai/api`
- URL: `https://pub-api.conversion.ai/api/v2/custom-objects/{customObjectId}/records/batch`
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in query parameter `api_key`

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

## Path parameters

- `customObjectId` string, uuid, required

## Request body

- object
  - `records` object[], required
    - `objectId` string, required: 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` object: 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.

## Response `200`

Per-record write results.

- object
  - `data` object
    - `processed` integer, required
    - `succeeded` integer, required
    - `failed` integer, required
    - `results` object[], required
      - `success` boolean, required
      - `id` string, uuid: Conversion ID of the saved record. Returned on success; not an input identifier for this endpoint.
      - `objectId` string: The `objectId` sent for this record.
      - `operation` 'CREATE' | 'UPDATE'
      - `error` string: Per-record error code: invalid_identifier, invalid_field, upsert_skipped, or upsert_failed.
      - `message` string
      - `skipped` boolean: True when CRM intentionally did not write the record.
      - `fieldErrors` object[]: Field keys and reasons reported by CRM when a record fails field validation.
        - `key` string, required
        - `reason` string, required: CRM rejection reason, such as DROPPED_TYPE_MISMATCH.

## Other responses

- `400`: Invalid request.
- `401`: Missing or invalid API key.
- `403`: The API key lacks permission, or custom objects are not enabled.
- `404`: Resource not found in this workspace.
- `500`: Unexpected service failure.

---

[API](https://skmtc.dev/conversion/apis/conversion-api.md) - [All operations](https://skmtc.dev/conversion/apis/conversion-api/llms.txt) - [OpenAPI document](https://skmtc.dev/conversion/apis/conversion-api/revisions/8422f815402a?raw)