updateContact
Update a contact by contactId: the general-purpose per-contact write.
POST/api/v1/callWRITEidempotent · 24 hruns as the key's owner
Update a contact by contactId: the general-purpose per-contact write. All of it, contactId too, is one input variable the docs cannot expand, so this list is the contract. Identity: name, isArchived (false RESTORES one archived contact; unarchiveContacts for many), importantNote (the record's important-note field, not a timeline note: addContactNote writes those, changeNotePinned pins one). Channels: addPhoneNumbers (verificationStatus: UNVERIFIED unless the person was reached on it) / updatePhoneNumbers / removePhoneNumbers (updatePhoneNumbers sets only verificationStatus, phoneType, note, ranking: a new number is remove-then-add; a US number is stored as 10 digits and formatted for display, so reformatting needs no write), addEmails / updateEmails / removeEmails, addMailingAddresses / updateMailingAddresses / removeMailingAddresses (their home or mailing address: "lives at X, not Y" replaces it here, never as a property; an edit is remove-then-add; removeMailingAddresses takes the MAPPING-row id from mailingAddresses[].id, not an address id). Subject properties: addProperties / updateProperties / removeProperties, how "add 123 Oak St to this contact" is done; addProperties takes a propertyId from findProperties/getProperty plus a verificationStatus. Relatives: subContacts (upsert; omit the id to create) and removeSubContacts. Custom fields: updateCustomFieldValues, each { contactId, customFieldId, exactly ONE of textValue / numberValue / dateValue / dropdownSelectedValues per the field type (getContact shows the per-type read-back); dropdownSelectedValues takes the option LABELS (an option id is read as its label), and a value the field has no option for is refused with the field options listed }; the response echoes customFields so you can confirm the value landed. Files: deleteFileIds (detaches by UploadedFile id). Tags, lists, teammates, teams: addTagIds/removeTagIds, addToListIds/removeFromListIds, addCollaborators/removeCollaborators, addUserGroupIds/removeUserGroupIds. Synchronous; returns the contact. Omitted fields are untouched; each add*/remove* pair is a delta, not a replacement. For MANY contacts use the bulk ops (addContactTags/removeContactTags, addContactsToList/removeContactsFromList, assignContact/unassignContact, archiveContacts/unarchiveContacts), which are async and return a bulkTaskId.
curl https://server.goliathdata.com/api/v1/call \
-H "Authorization: Bearer $GOLIATH_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"operationId": "updateContact",
"variables": {
"input": {
"contactId": "<String>"
}
}
}'import { GoliathClient } from '@goliath-data/sdk'
const goliath = new GoliathClient({
apiKey: process.env.GOLIATH_API_KEY!,
baseUrl: 'https://server.goliathdata.com',
})
const result = await goliath.contacts.updateContact(
{
input: {
contactId: '<String>'
}
},
{ idempotencyKey: crypto.randomUUID() },
)const res = await fetch('https://server.goliathdata.com/api/v1/call', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.GOLIATH_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
operationId: 'updateContact',
variables: {
input: {
contactId: '<String>'
}
}
}),
})
const { data, errors } = await res.json()Variables
The example sends only what the schema requires. Some operations also need one of several optional variables (one filter or another, say); the description above says which.
inputUpdateContactInput!required
contactIdString!required
addProperties[CreateContactPropertyInput!]
updateProperties[UpdateContactPropertyInput!]
removeProperties[String!]
addMailingAddresses[CreateContactMailingAddressInput!]
updateMailingAddresses[UpdateContactMailingAddressInput!]
Update an existing mailing row's verification / ordering by its mapping-row id (ContactMailingAddress.id). The address text is immutable: edit = remove + re-add.
removeMailingAddresses[String!]
isArchivedBoolean
nameString
addCollaborators[ContactCollaboratorInput!]
removeCollaborators[String!]
updateCustomFieldValues[UpdateContactCustomFieldInput!]
deleteFileIds[String!]
importantNoteString
addPhoneNumbers[CreateContactPhoneNumberInput!]
updatePhoneNumbers[UpdateContactPhoneNumberInput!]
removePhoneNumbers[String!]
subContacts[SubContactMutationInput!]
removeSubContacts[String!]
addEmails[CreateContactEmailInput!]
updateEmails[UpdateContactEmailInput!]
removeEmails[String!]
addToListIds[ID!]
removeFromListIds[ID!]
addTagIds[ID!]
removeTagIds[ID!]
addUserGroupIds[ID!]
removeUserGroupIds[ID!]
Every field, all the way down
variables
[
{
"name": "input",
"type": "UpdateContactInput!",
"required": true,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "contactId",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "addProperties",
"type": "[CreateContactPropertyInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "propertyId",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "propertyString",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "address",
"type": "AddressInput",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "id",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "line1",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "line2",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "city",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "state",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "zip",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
}
]
},
{
"name": "verificationStatus",
"type": "VerificationStatus!",
"required": true,
"description": null,
"defaultValue": null,
"enumValues": [
"VERIFIED",
"UNVERIFIED",
"WRONG"
]
},
{
"name": "status",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "ranking",
"type": "Int",
"required": false,
"description": null,
"defaultValue": null
}
]
},
{
"name": "updateProperties",
"type": "[UpdateContactPropertyInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "id",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "verificationStatus",
"type": "VerificationStatus",
"required": false,
"description": null,
"defaultValue": null,
"enumValues": [
"VERIFIED",
"UNVERIFIED",
"WRONG"
]
},
{
"name": "status",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "ranking",
"type": "Int",
"required": false,
"description": null,
"defaultValue": null
}
]
},
{
"name": "removeProperties",
"type": "[String!]",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "addMailingAddresses",
"type": "[CreateContactMailingAddressInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "addressString",
"type": "String!",
"required": true,
"description": "Raw single-line address; resolved via MailingAddressResolutionService (property → address → raw).",
"defaultValue": null
},
{
"name": "propertyElasticsearchId",
"type": "ID",
"required": false,
"description": "Instant-duplicate case: the property (Property.id / esId) the user copied this mailing address from: e.g. \"use my subject property as the mailing address\". When set, the mailing row links straight to that property (no ES search).",
"defaultValue": null
},
{
"name": "verificationStatus",
"type": "VerificationStatus",
"required": false,
"description": null,
"defaultValue": null,
"enumValues": [
"VERIFIED",
"UNVERIFIED",
"WRONG"
]
},
{
"name": "ranking",
"type": "Int",
"required": false,
"description": "Display order; lower is higher (0 = primary).",
"defaultValue": null
}
]
},
{
"name": "updateMailingAddresses",
"type": "[UpdateContactMailingAddressInput!]",
"required": false,
"description": "Update an existing mailing row's verification / ordering by its mapping-row id (ContactMailingAddress.id). The address text is immutable: edit = remove + re-add.",
"defaultValue": null,
"fields": [
{
"name": "id",
"type": "ID!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "verificationStatus",
"type": "VerificationStatus",
"required": false,
"description": null,
"defaultValue": null,
"enumValues": [
"VERIFIED",
"UNVERIFIED",
"WRONG"
]
},
{
"name": "ranking",
"type": "Int",
"required": false,
"description": null,
"defaultValue": null
}
]
},
{
"name": "removeMailingAddresses",
"type": "[String!]",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "isArchived",
"type": "Boolean",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "name",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "addCollaborators",
"type": "[ContactCollaboratorInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "userId",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "role",
"type": "ContactToUserMappingStatus!",
"required": true,
"description": null,
"defaultValue": null,
"enumValues": [
"REVOKED",
"POINT_PERSON",
"PARTICIPANT"
]
},
{
"name": "createTask",
"type": "CreateTaskInput",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "title",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "taskType",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "timezone",
"type": "Timezone!",
"required": true,
"description": "AZ: Arizona: MST all year, no DST.",
"defaultValue": null,
"enumValues": [
"IDLW",
"SST",
"HST",
"AKST",
"PST",
"MST",
"AZ",
"CST",
"EST",
"AST",
"BRT",
"FNT",
"AZOT",
"UTC",
"CET",
"EET",
"MSK",
"GST",
"PKT",
"BST",
"ICT",
"JST",
"AEST",
"NCT",
"NZST"
]
},
{
"name": "description",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "endDate",
"type": "DateTime!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "participants",
"type": "[String!]",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "contactId",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "pipelineItemIds",
"type": "[ID!]",
"required": false,
"description": "Deals to explicitly attach to the task (creates DealTask join rows). May be empty or omitted.",
"defaultValue": null
},
{
"name": "dealIds",
"type": "[ID!]",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "autoCompleteOnNoteAdded",
"type": "Boolean",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "autoCompleteOnReassignment",
"type": "Boolean",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "createCalendarEvent",
"type": "Boolean",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "alongsideOpenTasks",
"type": "Boolean",
"required": false,
"description": null,
"defaultValue": null
}
]
}
]
},
{
"name": "removeCollaborators",
"type": "[String!]",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "updateCustomFieldValues",
"type": "[UpdateContactCustomFieldInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "contactId",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "customFieldId",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "textValue",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "calendarDate",
"type": "String",
"required": false,
"description": "Preferred DATE value as a strict calendar day (YYYY-MM-DD). Do not combine with dateValue.",
"defaultValue": null
},
{
"name": "dateValue",
"type": "DateTime",
"required": false,
"description": "Legacy DATE compatibility input. Prefer calendarDate for new clients; do not combine both forms.",
"defaultValue": null
},
{
"name": "numberValue",
"type": "Float",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "dropdownSelectedValues",
"type": "[String!]",
"required": false,
"description": null,
"defaultValue": null
}
]
},
{
"name": "deleteFileIds",
"type": "[String!]",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "importantNote",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "addPhoneNumbers",
"type": "[CreateContactPhoneNumberInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "phoneNumber",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "verificationStatus",
"type": "VerificationStatus!",
"required": true,
"description": null,
"defaultValue": null,
"enumValues": [
"VERIFIED",
"UNVERIFIED",
"WRONG"
]
},
{
"name": "phoneType",
"type": "PhoneType",
"required": false,
"description": null,
"defaultValue": null,
"enumValues": [
"MOBILE",
"RESIDENTIAL",
"LANDLINE",
"UNKNOWN"
]
},
{
"name": "note",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "ranking",
"type": "Int",
"required": false,
"description": null,
"defaultValue": null
}
]
},
{
"name": "updatePhoneNumbers",
"type": "[UpdateContactPhoneNumberInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "id",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "verificationStatus",
"type": "VerificationStatus",
"required": false,
"description": null,
"defaultValue": null,
"enumValues": [
"VERIFIED",
"UNVERIFIED",
"WRONG"
]
},
{
"name": "phoneType",
"type": "PhoneType",
"required": false,
"description": null,
"defaultValue": null,
"enumValues": [
"MOBILE",
"RESIDENTIAL",
"LANDLINE",
"UNKNOWN"
]
},
{
"name": "note",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "ranking",
"type": "Int",
"required": false,
"description": null,
"defaultValue": null
}
]
},
{
"name": "removePhoneNumbers",
"type": "[String!]",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "subContacts",
"type": "[SubContactMutationInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "id",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "contactId",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "name",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "relation",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "note",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "phoneNumbers",
"type": "[CreateContactPhoneNumberInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "phoneNumber",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "verificationStatus",
"type": "VerificationStatus!",
"required": true,
"description": null,
"defaultValue": null,
"enumValues": [
"VERIFIED",
"UNVERIFIED",
"WRONG"
]
},
{
"name": "phoneType",
"type": "PhoneType",
"required": false,
"description": null,
"defaultValue": null,
"enumValues": [
"MOBILE",
"RESIDENTIAL",
"LANDLINE",
"UNKNOWN"
]
},
{
"name": "note",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "ranking",
"type": "Int",
"required": false,
"description": null,
"defaultValue": null
}
]
},
{
"name": "emails",
"type": "[CreateContactEmailInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "email",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "verificationStatus",
"type": "VerificationStatus!",
"required": true,
"description": null,
"defaultValue": null,
"enumValues": [
"VERIFIED",
"UNVERIFIED",
"WRONG"
]
},
{
"name": "note",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "ranking",
"type": "Int",
"required": false,
"description": null,
"defaultValue": null
}
]
}
]
},
{
"name": "removeSubContacts",
"type": "[String!]",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "addEmails",
"type": "[CreateContactEmailInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "email",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "verificationStatus",
"type": "VerificationStatus!",
"required": true,
"description": null,
"defaultValue": null,
"enumValues": [
"VERIFIED",
"UNVERIFIED",
"WRONG"
]
},
{
"name": "note",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "ranking",
"type": "Int",
"required": false,
"description": null,
"defaultValue": null
}
]
},
{
"name": "updateEmails",
"type": "[UpdateContactEmailInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "id",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "verificationStatus",
"type": "VerificationStatus",
"required": false,
"description": null,
"defaultValue": null,
"enumValues": [
"VERIFIED",
"UNVERIFIED",
"WRONG"
]
},
{
"name": "note",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "ranking",
"type": "Int",
"required": false,
"description": null,
"defaultValue": null
}
]
},
{
"name": "removeEmails",
"type": "[String!]",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "addToListIds",
"type": "[ID!]",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "removeFromListIds",
"type": "[ID!]",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "addTagIds",
"type": "[ID!]",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "removeTagIds",
"type": "[ID!]",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "addUserGroupIds",
"type": "[ID!]",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "removeUserGroupIds",
"type": "[ID!]",
"required": false,
"description": null,
"defaultValue": null
}
]
}
]Response
What comes back under data: a list shows as one entry, and a value as its type.
response shape
{
"data": {
"contactMutation": {
"updateContact": {
"id": "<ID>",
"name": "…",
"isArchived": true,
"emails": [
{
"id": "<ID>",
"email": "…",
"verificationStatus": "VERIFIED"
}
],
"phoneNumbers": [
{
"id": "<ID>",
"phoneNumber": "…",
"phoneType": "MOBILE",
"verificationStatus": "VERIFIED"
}
],
"tags": [
{
"id": "<ID>",
"name": "…"
}
],
"lists": [
{
"id": "<ID>",
"name": "…"
}
],
"participants": [
{
"status": "REVOKED",
"user": {
"id": "<ID>",
"firstName": "…",
"lastName": "…",
"email": "…"
}
}
],
"userGroups": [
{
"id": "<ID>",
"name": "…"
}
],
"customFields": [
{
"id": "<ID>",
"name": "…",
"type": "DROPDOWN",
"allowMultiple": true,
"values": {
"textValue": "…",
"dateValue": "2026-01-01T00:00:00.000Z",
"numberValue": 0,
"dropdownSelectedValues": [
"…"
]
}
}
]
}
}
}
}Errors
400
unknown_variableA variable the operation does not declare. A typo is refused rather than silently dropped.
401
unauthorizedNo bearer header, or the key is invalid or revoked.
403
insufficient_scopeThe key lacks the scope the operation requires.
403
forbiddenA referenced record does not exist, was deleted, or is outside your organization. The gateway cannot tell those apart.
409
idempotency_conflictA request with this Idempotency-Key is still in flight.
Idempotency
Send an Idempotency-Key of 1 to 255 characters. A finished request retried with the same key replays its stored response, marked Idempotency-Replayed: true; one still in flight returns 409 idempotency_conflict. Keys expire after 24 hours. Write without fear →