Reference
Contacts
Read and write contacts, custom fields, and GDPR erasure
Erasure is irreversible and needs its own scope. See Contacts.
contactApi
Query
ScopeCONTACTS_READ
One contact by id (API key: contacts:read). Null if absent.
Arguments
idID!RequiredReturns
idID!displayNameStringavatarUrlStringphoneStringemailStringchannels[String!]!erasedBoolean!externalIdStringquery {
contactApi(id: "…") { id displayName avatarUrl phone email }
}contactApiByExternalId
Query
ScopeCONTACTS_READ
One contact by your own externalId (API key: contacts:read). Null if absent.
Arguments
externalIdString!RequiredReturns
idID!displayNameStringavatarUrlStringphoneStringemailStringchannels[String!]!erasedBoolean!externalIdStringquery {
contactApiByExternalId(externalId: "…") { id displayName avatarUrl phone email }
}contactsApi
Query
ScopeCONTACTS_READ
List/search contacts (API key: contacts:read).
Arguments
filterContactApiFilterInputDefaults to
\{\}.paginationContactApiPaginationInputDefaults to
\{\}.sortDirSortDirectionContactApiFilterInput
searchStringexternalIdStringphoneStringchannelContactChannelcreatedAfterDateTimecreatedBeforeDateTimeContactApiPaginationInput
firstIntafterIDReturns
query {
contactsApi(filter: { … }, pagination: { … }, sortDir: ASC) { items nextCursor totalCount }
}createContactApi
Mutation
ScopeCONTACTS_MANAGE
Create a contact (API key: contacts:manage).
Arguments
ContactApiWriteInput
externalIdStringdisplayNameStringfirstNameStringlastNameStringphoneStringlanguageStringfields[ContactApiFieldInput!]channelContactApiChannelInputReturns
idID!displayNameStringavatarUrlStringphoneStringemailStringchannels[String!]!erasedBoolean!externalIdStringmutation {
createContactApi(input: { … }) { id displayName avatarUrl phone email }
}createPeopleFieldDefinition
Mutation
ScopeCONTACTS_MANAGE
Arguments
CreateFieldDefinitionDto
keyString!RequirednameString!RequiredtypeString!RequiredvisibilityStringgroupFieldGroupDisplay section in the chat profile view (defaults to USER_DATA).
isRequiredBooleandisplayOrderFloatpinnedToChatViewBooleanShow this field in the compact chat panel (vs behind "See all"). Independent of group and visibility. Defaults to false.
descriptionStringoptions[String!]defaultValueJSONisSystemFieldBooleanisReadOnlyBooleanWhether this field is read-only. Read-only fields cannot be edited by users. This is typically set by the system for auto-calculated fields.
Returns
_idString!organisationIdString!keyString!nameString!typeFieldType!descriptionStringvisibilityFieldVisibility!groupFieldGroupisRequiredBoolean!isSystemFieldBoolean!isReadOnlyBoolean!Whether this field is read-only and cannot be edited by users. Read-only fields are auto-calculated or set by the system.
options[String!]defaultValueJSONdisplayOrderFloat!pinnedToChatViewBooleancreatedAtDateTime!updatedAtDateTime!mutation {
createPeopleFieldDefinition(input: { … }) { _id organisationId key name type }
}deletePeopleFieldDefinition
Mutation
ScopeCONTACTS_MANAGE
Arguments
idString!RequiredReturns
Boolean!mutation {
deletePeopleFieldDefinition(id: "…")
}deletePeopleFieldValue
Mutation
ScopeCONTACTS_MANAGE
Arguments
peopleIdString!RequiredfieldIdString!RequiredReturns
Boolean!mutation {
deletePeopleFieldValue(peopleId: "…", fieldId: "…")
}eraseContact
Mutationirreversible
ScopeCONTACTS_ERASE
Irreversibly erase a Contact's PII (GDPR right to erasure). Org-scoped. Member (role) OR an API key with the CONTACTS_ERASE scope.
Arguments
EraseInput
contactIdID!RequiredThe Contact to erase (or preview erasing).
organisationIdID!RequiredThe organisation the contact must belong to.
reasonStringOptional free-text reason/ticket reference for the erasure. Operator-supplied free text, passed through as-is.
Returns
contactIdID!The Contact that was erased.
erasedAtDateTime!When the erasure completed.
affectedCounts[EraseCount!]!Per-collection counts of documents affected by the erasure.
erasureLogIdID!The
ErasureLog._id this erasure was recorded under.mutation {
eraseContact(input: { … }) { contactId erasedAt affectedCounts erasureLogId }
}getPeopleFieldDefinitions
Query
ScopeCONTACTS_READ
Arguments
filterPeopleFieldsFilterDtoPeopleFieldsFilterDto
peopleIdStringkeys[String!]typeStringvisibilityStringgroups[FieldGroup!]Return only fields in these display groups - lets the chat view load the primary sections up front and the rest behind "Details".
onlyPinnedBooleanReturn only fields pinned to the compact chat panel - the fast query the chat view uses before the operator opens full "Details".
includeSystemFieldsBooleanincludeCustomFieldsBooleanapplyPrivacyMaskingBooleanReturns
_idString!organisationIdString!keyString!nameString!typeFieldType!descriptionStringvisibilityFieldVisibility!groupFieldGroupisRequiredBoolean!isSystemFieldBoolean!isReadOnlyBoolean!Whether this field is read-only and cannot be edited by users. Read-only fields are auto-calculated or set by the system.
options[String!]defaultValueJSONdisplayOrderFloat!pinnedToChatViewBooleancreatedAtDateTime!updatedAtDateTime!query {
getPeopleFieldDefinitions(filter: { … }) { _id organisationId key name type }
}getPeopleFieldValue
Query
ScopeCONTACTS_READ
Arguments
idString!RequiredReturns
_idString!peopleIdString!organisationIdString!valueJSONcreatedAtDateTime!updatedAtDateTime!fieldKeyStringquery {
getPeopleFieldValue(id: "…") { _id peopleId organisationId field value }
}getPeopleFieldValues
Query
ScopeCONTACTS_READ
Arguments
peopleIdString!RequiredfilterPeopleFieldsFilterDtoPeopleFieldsFilterDto
peopleIdStringkeys[String!]typeStringvisibilityStringgroups[FieldGroup!]Return only fields in these display groups - lets the chat view load the primary sections up front and the rest behind "Details".
onlyPinnedBooleanReturn only fields pinned to the compact chat panel - the fast query the chat view uses before the operator opens full "Details".
includeSystemFieldsBooleanincludeCustomFieldsBooleanapplyPrivacyMaskingBooleanReturns
_idString!peopleIdString!organisationIdString!valueJSONcreatedAtDateTime!updatedAtDateTime!fieldKeyStringquery {
getPeopleFieldValues(peopleId: "…", filter: { … }) { _id peopleId organisationId field value }
}isWhatsAppIdEditable
Query
ScopeCONTACTS_READ
Check if WhatsApp ID field is editable for a contact
Arguments
peopleIdString!RequiredReturns
Boolean!query {
isWhatsAppIdEditable(peopleId: "…")
}previewErase
Query
ScopeCONTACTS_ERASE
Read-only preview of what an eraseContact call would affect for a Contact, without mutating anything. Org-scoped. Member (role) OR an API key with the CONTACTS_ERASE scope.
Arguments
EraseInput
contactIdID!RequiredThe Contact to erase (or preview erasing).
organisationIdID!RequiredThe organisation the contact must belong to.
reasonStringOptional free-text reason/ticket reference for the erasure. Operator-supplied free text, passed through as-is.
Returns
contactIdID!The Contact this preview was computed for.
willErase[EraseCount!]!Per-collection counts of documents an eraseContact call would affect.
warnings[String!]!Human-readable, PII-free warning lines (e.g. 'contact already erased', 'N messages will be anonymized').
query {
previewErase(input: { … }) { contactId willErase warnings }
}setPeopleFieldValue
Mutation
ScopeCONTACTS_MANAGE
Arguments
SetFieldValueDto
peopleIdString!RequiredfieldIdString!RequiredvalueJSONReturns
_idString!peopleIdString!organisationIdString!valueJSONcreatedAtDateTime!updatedAtDateTime!fieldKeyStringmutation {
setPeopleFieldValue(input: { … }) { _id peopleId organisationId field value }
}updateContactApi
Mutation
ScopeCONTACTS_MANAGE
Update a contact's fields (API key: contacts:manage). NotFound if absent or in another org.
Arguments
idID!RequiredContactApiWriteInput
externalIdStringdisplayNameStringfirstNameStringlastNameStringphoneStringlanguageStringfields[ContactApiFieldInput!]channelContactApiChannelInputReturns
idID!displayNameStringavatarUrlStringphoneStringemailStringchannels[String!]!erasedBoolean!externalIdStringmutation {
updateContactApi(id: "…", input: { … }) { id displayName avatarUrl phone email }
}updatePeopleFieldDefinition
Mutation
ScopeCONTACTS_MANAGE
Arguments
idString!RequiredUpdateFieldDefinitionDto
keyStringnameStringtypeStringvisibilityStringisRequiredBooleandisplayOrderFloatgroupFieldGroupMove this field to another display section. Allowed on system fields (it is presentation, not data).
pinnedToChatViewBooleanPin/unpin this field in the compact chat panel. Allowed on system fields (presentation, not data).
descriptionStringoptions[String!]defaultValueJSONReturns
_idString!organisationIdString!keyString!nameString!typeFieldType!descriptionStringvisibilityFieldVisibility!groupFieldGroupisRequiredBoolean!isSystemFieldBoolean!isReadOnlyBoolean!Whether this field is read-only and cannot be edited by users. Read-only fields are auto-calculated or set by the system.
options[String!]defaultValueJSONdisplayOrderFloat!pinnedToChatViewBooleancreatedAtDateTime!updatedAtDateTime!mutation {
updatePeopleFieldDefinition(id: "…", input: { … }) { _id organisationId key name type }
}upsertContactApi
Mutation
ScopeCONTACTS_MANAGE
Create or update a contact idempotently by your own externalId (API key: contacts:manage).
Arguments
ContactApiWriteInput
externalIdStringdisplayNameStringfirstNameStringlastNameStringphoneStringlanguageStringfields[ContactApiFieldInput!]channelContactApiChannelInputReturns
idID!displayNameStringavatarUrlStringphoneStringemailStringchannels[String!]!erasedBoolean!externalIdStringmutation {
upsertContactApi(input: { … }) { id displayName avatarUrl phone email }
}