Skip to content

Create a record

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

Requires the “Structured data - Write records” permission. ?createMissingRefs=1 creates a draft placeholder for a reference to an externalId that doesn’t exist yet.

collection
required
string

Collection key

Example

matches
createMissingRefs
string
Allowed values: 1
Media typeapplication/json
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"
}

Updated, or unchanged

Media typeapplication/json
StructuredRecordWriteResult

A written record and what happened to it

object
data
StructuredRecord

A record of a structured data collection

object
id

Record ID

integer
externalId

The connector’s own id for the record, unique in the collection

string
nullable
collection

The collection’s key

string
status

Status. Frontends (API keys not linked to a CMS user) only see published records.

string
Allowed values: draft published archived
title

The value of the collection’s title field

string
data

The field values, by field key. A reference holds the id of what it points to; expand it with include=.

object
included

With include=: what the named reference fields point to, by field key (an object, a list for several values, or null when it is missing or not published)

object
createdAt

Created

string format: date-time
nullable
updatedAt

Last changed

string format: date-time
nullable
publishedAt

First published

string format: date-time
nullable
result

Created, updated, or unchanged (the same data was sent again: nothing was written)

string
Allowed values: created updated unchanged

Example

{
"data": {
"id": 27,
"externalId": "opta:m1",
"collection": "matches",
"status": "draft",
"title": "Arsenal v Chelsea",
"data": {
"label": "Arsenal v Chelsea",
"home": 21,
"away": 22,
"kickoff": "2026-11-20T20:00:00+00:00"
}
},
"result": "created"
}

Created

Media typeapplication/json
StructuredRecordWriteResult

A written record and what happened to it

object
data
StructuredRecord

A record of a structured data collection

object
id

Record ID

integer
externalId

The connector’s own id for the record, unique in the collection

string
nullable
collection

The collection’s key

string
status

Status. Frontends (API keys not linked to a CMS user) only see published records.

string
Allowed values: draft published archived
title

The value of the collection’s title field

string
data

The field values, by field key. A reference holds the id of what it points to; expand it with include=.

object
included

With include=: what the named reference fields point to, by field key (an object, a list for several values, or null when it is missing or not published)

object
createdAt

Created

string format: date-time
nullable
updatedAt

Last changed

string format: date-time
nullable
publishedAt

First published

string format: date-time
nullable
result

Created, updated, or unchanged (the same data was sent again: nothing was written)

string
Allowed values: created updated unchanged

Example

{
"data": {
"id": 27,
"externalId": "opta:m1",
"collection": "matches",
"status": "draft",
"title": "Arsenal v Chelsea",
"data": {
"label": "Arsenal v Chelsea",
"home": 21,
"away": 22,
"kickoff": "2026-11-20T20:00:00+00:00"
}
},
"result": "created"
}

Not valid; nothing was written

Media typeapplication/json
StructuredValidationError

The record was not written: what is wrong, by field key

object
error
string
errors
object
key
additional properties
string

Example

{
"error": "The record is not valid.",
"errors": {
"kickoff": "Must be a date and time in ISO 8601, e.g. 2026-11-15T20:45:00+01:00.",
"home": "No teams record with externalId: opta:t99."
}
}

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

No such collection or record

Clashes with existing data (an externalId already used)