Skip to main content

Update metadata individually or in batches

Metadata updates accept either one key and value pair or a metadata array. Existing calls continue to work. A batch lets you update several fields in one API call.

MutationResource identifier
updateContactMetadatacontactId
updateBookingMetadatabookingId
updateInvoiceMetadatainvoiceId
updateLocationMetadatalocationId (location group ID)
updateProductMetadataproductId
updateUserMetadatauserId
updatePathwayMetadatapathwayId

Single pair​

mutation UpdateContactMetadata($id: ID!, $key: String!, $value: String!) {
updateContactMetadata(contactId: $id, key: $key, value: $value) {
data {
id
}
error
}
}

The other mutations use the same arguments with their resource identifier. For backward compatibility, updateProductMetadata.key retains the GraphQL ID scalar: use $key: ID! for product single-pair calls. The other single-pair keys use String. Batch entry keys use String for all available mutations.

Batch​

mutation UpdateContactMetadataBatch(
$id: ID!
$metadata: [MetadataEntryInput!]!
) {
updateContactMetadata(contactId: $id, metadata: $metadata) {
data {
id
}
error
}
}

Example variables:

{
"id": "RESOURCE_ID",
"metadata": [
{ "key": "external_reference", "value": "REF-123" },
{ "key": "source", "value": "Connect" }
]
}

Use the corresponding mutation and resource identifier from the table to update another resource. Pathways accept this existing batch form as well as the single-pair form.

Validation and limits​

  • Supply exactly one form: both key and value, or a non-empty metadata array. Supplying neither form or mixing forms is rejected, including supplying only a key or value alongside a batch.
  • Omit unused arguments. Explicit null arguments and null array entries are rejected.
  • Each entry must contain a non-empty key and value after sanitisation. Existing character validation and sanitisation rules apply, including a maximum key length of 40 characters and value length of 500 characters.
  • Duplicate keys within a batch are rejected after key sanitisation. For example, reference and reference are duplicates.
  • Each stored resource can contain at most 50 metadata keys. This is the existing limit and applies to the resulting stored metadata, rather than to each API call. Overwriting existing keys does not use additional capacity.

Updates add new keys or overwrite supplied existing keys and preserve all unspecified keys. Every batch succeeds or fails as a whole: an invalid entry or an exceeded limit leaves the metadata unchanged.

For example, if a contact has 49 keys, a batch overwriting one key and adding one new key succeeds. Adding two new keys fails without applying either entry. At 50 keys, updates to existing keys continue to work.