Create a record
const url = 'https://api.example.com/cms/data/matches/records?createMissingRefs=1';const options = { method: 'POST', headers: {'API-Key': '<API-Key>', 'Content-Type': 'application/json'}, body: '{"externalId":"opta:m1","status":"draft","data":{"label":"Arsenal v Chelsea","home":{"externalId":"opta:t3"},"kickoff":"2026-11-20T20:00:00Z"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Collection key
Example
matchesQuery Parameters
Section titled “Query Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”A record as it is written. In data, a reference to a record can be its id or {“externalId”: “…”}.
object
The connector’s own id (taken from the path on PUT …/external/{externalId})
Example
opta:m1Status (the collection’s default status when left out on create)
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"}Responses
Section titled “Responses”Updated, or unchanged
A written record and what happened to it
object
A record of a structured data collection
object
Record ID
The connector’s own id for the record, unique in the collection
The collection’s key
Status. Frontends (API keys not linked to a CMS user) only see published records.
The value of the collection’s title field
The field values, by field key. A reference holds the id of what it points to; expand it with include=.
object
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
Created
Last changed
First published
Created, updated, or unchanged (the same data was sent again: nothing was written)
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
A written record and what happened to it
object
A record of a structured data collection
object
Record ID
The connector’s own id for the record, unique in the collection
The collection’s key
Status. Frontends (API keys not linked to a CMS user) only see published records.
The value of the collection’s title field
The field values, by field key. A reference holds the id of what it points to; expand it with include=.
object
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
Created
Last changed
First published
Created, updated, or unchanged (the same data was sent again: nothing was written)
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
The record was not written: what is wrong, by field key
object
object
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)