Skip to content

Create or replace many records by externalId

POST
/cms/data/{collection}/records/bulk
curl --request POST \
--url 'https://api.example.com/cms/data/matches/records/bulk?createMissingRefs=1' \
--header 'API-Key: <API-Key>' \
--header 'Content-Type: application/json' \
--data '{ "records": [ { "externalId": "opta:m1", "status": "draft", "data": { "label": "Arsenal v Chelsea", "home": { "externalId": "opta:t3" }, "kickoff": "2026-11-20T20:00:00Z" } } ] }'

Up to 500 records, each with an externalId. Each succeeds or fails on its own (207 when some failed); a record can point to one earlier in the batch. Requires the “Structured data - Write records” permission.

collection
required
string

Collection key

Example

matches
createMissingRefs
string
Allowed values: 1
Media typeapplication/json
object
records
Array<object>
StructuredRecordInput

A record as it is written. In data, a reference to a record can be its id or {“externalId”: “…”}.

object
externalId

The connector’s own id (taken from the path on PUT …/external/{externalId})

string
nullable

Example

opta:m1
status

Status (the collection’s default status when left out on create)

string
nullable
Allowed values: draft published archived
data

The field values, by field key. On PATCH, merged onto the stored values; null removes a value.

object

Example

{
"label": "Arsenal v Chelsea",
"home": {
"externalId": "opta:t3"
},
"kickoff": "2026-11-20T20:00:00Z"
}

All written

Media typeapplication/json
StructuredBulkResult

What a bulk upsert did, item by item. Each item succeeds or fails on its own.

object
ok

Whether every item was written

boolean
created
integer
updated
integer
unchanged
integer
failed
integer
results
Array<object>
object
index

Position in records

integer
externalId
string
nullable
id

Record ID, when written

integer
result
string
Allowed values: created updated unchanged failed
error

When failed

string
errors

When failed: what is wrong, by field key

object

Example

{
"results": [
{
"result": "created"
}
]
}

Some failed

Media typeapplication/json
StructuredBulkResult

What a bulk upsert did, item by item. Each item succeeds or fails on its own.

object
ok

Whether every item was written

boolean
created
integer
updated
integer
unchanged
integer
failed
integer
results
Array<object>
object
index

Position in records

integer
externalId
string
nullable
id

Record ID, when written

integer
result
string
Allowed values: created updated unchanged failed
error

When failed

string
errors

When failed: what is wrong, by field key

object

Example

{
"results": [
{
"result": "created"
}
]
}

Not {“records”: […]}, or more than 500

Needs an API key linked to a CMS user with the Structured data permission

No such collection or record