Create or replace a record by externalId
const url = 'https://api.example.com/cms/data/matches/records/external/opta%3Am1?createMissingRefs=1';const options = { method: 'PUT', 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 PUT \ --url 'https://api.example.com/cms/data/matches/records/external/opta%3Am1?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" } }'The call connectors use: creates the record, or replaces its data. Sending the same data again changes nothing (result: unchanged). Requires the “Structured data - Write records” permission.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Collection key
Example
matchesThe record’s externalId (URL-encoded)
Example
opta:m1Query 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