> ## Documentation Index > Fetch the complete documentation index at: https://docs.useboom.ai/llms.txt > Use this file to discover all available pages before exploring further. # Batch upsert objects > Upsert up to 1000 custom objects in one request. Idempotent and safely retryable. By DEFAULT each item REPLACES that object's entire `attributes` blob, so an item carrying only the fields you want to change DELETES every other attribute on that object. To add or change a subset across many objects, pass `mode: 'merge'` — it overlays the keys you send and leaves the rest untouched, with no need to read each object first. Pass `createMissing: false` to update only objects that already exist; anything unmatched comes back in `skipped` rather than being created. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/cdp/custom-objects/batch openapi: 3.1.0 info: title: Boom API version: 1.0.0 description: >- Boom's public REST API — one uniform surface over every platform capability. CDP: upsert people and custom objects, define object and relationship types, link and unlink relationships, and record behavioral events — one record per request or up to 1000 per request via the `/batch` endpoints. Segments: read (list, read, membership) and full authoring — discover the filterable catalog, validate a filter, create and update segments, preview match counts, and trigger evaluation. Initiatives: create and configure outreach initiatives, link WhatsApp templates, drive the lifecycle (launch, cancel, archive), and read collected-data summaries. Participants: enroll people into an active initiative, track their status, read conversation transcripts, and stop outreach. Journeys: read-only access to always-on message flows and their metrics. WhatsApp templates: list your WhatsApp numbers and list, read, and create message templates. The same capabilities are exposed as MCP tools with identical schemas. servers: - url: https://www.useboom.ai description: Production - url: https://dev.useboom.ai description: Development (sandbox — use a development organization API key) security: - bearerAuth: [] paths: /api/v1/cdp/custom-objects/batch: post: tags: - CDP Custom Objects summary: Batch upsert objects description: >- Upsert up to 1000 custom objects in one request. Idempotent and safely retryable. By DEFAULT each item REPLACES that object's entire `attributes` blob, so an item carrying only the fields you want to change DELETES every other attribute on that object. To add or change a subset across many objects, pass `mode: 'merge'` — it overlays the keys you send and leaves the rest untouched, with no need to read each object first. Pass `createMissing: false` to update only objects that already exist; anything unmatched comes back in `skipped` rather than being created. operationId: cdp_custom_objects_batch_upsert requestBody: required: true content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: items: minItems: 1 maxItems: 1000 type: array items: type: object properties: type: type: string minLength: 1 maxLength: 255 description: >- The custom object type name. Must already exist (create it with the types endpoint) — unknown types are rejected. externalId: type: string minLength: 1 maxLength: 255 description: >- Your stable identifier for this object within its type (idempotency key). displayName: description: Human-readable label for the object. type: string minLength: 1 maxLength: 255 attributes: description: >- Free-form custom traits. Full-replace by default — omitted keys are deleted. Pass mode:'merge' to overlay only what you send. type: object propertyNames: type: string maxLength: 255 additionalProperties: {} required: - type - externalId description: Custom objects to upsert. mode: default: replace description: >- How `attributes` is applied. 'replace' (default) swaps the whole blob — any stored attribute you leave out is DELETED. 'merge' overlays the keys you send onto the stored ones and leaves the rest untouched, which is what you want when adding or changing a subset. type: string enum: - replace - merge createMissing: default: true description: >- When false, objects that do not already exist are skipped and reported in `skipped` instead of being created. Use it when working from a list that may not match, so a bad id enriches nothing rather than inventing an object. type: boolean required: - items responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: summary: type: object properties: total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 created: type: integer minimum: -9007199254740991 maximum: 9007199254740991 updated: type: integer minimum: -9007199254740991 maximum: 9007199254740991 failed: type: integer minimum: -9007199254740991 maximum: 9007199254740991 skipped: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - total - created - updated - failed - skipped additionalProperties: false errors: type: array items: type: object properties: index: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Zero-based index of the failed item. externalId: type: string error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message additionalProperties: false required: - index - error additionalProperties: false skipped: type: array items: type: string description: >- externalIds not written because `createMissing` was false and no such object exists. required: - summary - errors - skipped additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: >- Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error components: securitySchemes: bearerAuth: type: http scheme: bearer description: 'Organization API key, sent as `Authorization: Bearer boom_org_...`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.