> ## Documentation Index > Fetch the complete documentation index at: https://developers.conveyour.com/llms.txt > Use this file to discover all available pages before exploring further. # Bulk create records > Creates or updates multiple records at once (bulk upsert). The request body is a **raw JSON array** of flat record objects — not wrapped in an object. Maximum 100 records per call. Records are upserted by `external_id`. `external_id` is **required** on every record in the batch. A record without it is rejected with `{ "external_id": "MISSING", "status": "error", "errors": ["Missing required external_id"] }` — the rest of the batch still processes. Bulk create/upsert records (raw array body, max 100) **Permission:** Requires `manage_custom_objects` **or** `manage_custom_records`. Denials read `Manage Custom Records`. Sending anything other than a top-level JSON array returns `Records input is not a JSON array` — with HTTP `200`, so check `status`. Exceeding 100 records returns HTTP `429` with `Currently supporting a maximum of 100 records per add request`. ## OpenAPI ````yaml /api-reference/specs/custom-object-records.json post /api/custom/records/add openapi: 3.1.0 info: title: ConveYour API — Custom Object Records description: Create, retrieve, update, and delete records for your Custom Object types. version: 1.0.0 servers: - url: https://{subdomain}.conveyour.com description: Your organization's ConveYour instance variables: subdomain: default: acme description: >- Your organization's slug — the subdomain you sign in on. Replace `acme` with yours: if you sign in at `bigco.conveyour.com`, enter `bigco`. security: - conveyourToken: [] tags: - name: Custom Object Records description: Create, retrieve, update, and delete records for your Custom Object types. paths: /api/custom/records/add: post: tags: - Custom Object Records summary: Bulk create records description: >- Creates or updates multiple records at once (bulk upsert). The request body is a **raw JSON array** of flat record objects — not wrapped in an object. Maximum 100 records per call. Records are upserted by `external_id`. `external_id` is **required** on every record in the batch. A record without it is rejected with `{ "external_id": "MISSING", "status": "error", "errors": ["Missing required external_id"] }` — the rest of the batch still processes. Bulk create/upsert records (raw array body, max 100) **Permission:** Requires `manage_custom_objects` **or** `manage_custom_records`. Denials read `Manage Custom Records`. Sending anything other than a top-level JSON array returns `Records input is not a JSON array` — with HTTP `200`, so check `status`. Exceeding 100 records returns HTTP `429` with `Currently supporting a maximum of 100 records per add request`. operationId: bulkCreateUpsertRecordsRawArrayBodyMax100 parameters: - name: obj_id in: query description: >- The ID of the Custom Object type to scope these records to. Can also be passed in each record object as `obj_id`. schema: type: string - $ref: '#/components/parameters/teams' requestBody: required: true content: application/json: schema: type: array description: >- A JSON ARRAY of records to upsert. A bare object is rejected with `Records input is not a JSON array`. Maximum 100 per request; more returns HTTP 429. maxItems: 100 items: type: object required: - external_id properties: external_id: type: string description: >- REQUIRED. Match key for the upsert; a record missing it is returned with status "error" and external_id "MISSING". obj_id: type: string description: >- Custom object ID. Falls back to the scoped `obj_id` when omitted. additionalProperties: description: Any field defined on the custom object's schema. responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: type: array items: $ref: '#/components/schemas/UpsertResult' description: >- One entry per submitted record. The request is capped at 100 records — more returns HTTP 429. example: status: ok message: 2 Records processed data: - external_id: vin-123 status: created - external_id: vin-456 status: updated '403': $ref: '#/components/responses/Forbidden' '429': description: >- Too many records in one request. `POST /api/custom/records/add` accepts at most **100 records**; more returns `Currently supporting a maximum of 100 records per add request`. content: application/json: schema: type: object properties: status: type: string enum: - failed description: Always `failed`. message: type: string description: Human-readable explanation. components: parameters: teams: name: teams[] in: query description: >- Team scope for the request, as one or more team ObjectIds. The brackets are required: PHP keeps only the last value for a repeated plain key, so `teams=A&teams=B` silently resolves to B alone. On requests with a JSON body you may send `teams` (no brackets) in the body instead. **Values that are not valid ObjectIds are silently ignored** — a mistyped team ID behaves as if no team was sent. See the [teams section of the API conventions guide](/guides/api-conventions#team-scoping). style: form explode: true schema: type: array items: type: string example: - 64a1b2c3d4e5f6a7b8c9d0ff schemas: Envelope: type: object description: The common response envelope shared by all ConveYour endpoints. properties: status: type: string enum: - ok - failed description: '`ok` on success, `failed` on error.' message: type: string description: Human-readable description of the result. data: description: >- The response payload — an object or an array depending on the endpoint. UpsertResult: type: object description: >- Per-record outcome of a bulk upsert. Returns one entry for every record submitted, in the same order — an entry can fail while the request as a whole still succeeds, so check status on each. properties: external_id: type: string description: >- The record's external_id, or the literal 'MISSING' when the input omitted it. status: type: string enum: - created - updated - error description: '''created'' or ''updated'' on success; ''error'' on failure.' errors: type: array items: type: string description: Validation messages. Present only when status is 'error'. required: - external_id - status responses: Forbidden: description: >- The token is missing or invalid, or the service account behind it lacks the permission this endpoint requires. content: application/json: example: status: failed message: Lacking necessary permission add_contacts data: permission: add_contacts securitySchemes: conveyourToken: type: apiKey in: header name: x-conveyour-token description: >- Your API key token. Contacts endpoints require a **Server-only — Full API** key — see [Authentication](/quickstart). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.