Contacts API

About

Look up and search contacts, create and update them, add notes and tags, assign teammates, find duplicate groups, manage saved filters, and skip-trace (enrich) contacts for phone numbers and emails. All operations go through the developer API gateway — one endpoint, called by operationId. If you haven’t set up a key yet, start with the Developer API Overview.

Operations

Reading contacts (`READ` scope)

operationId	What it does
`getContact`	Fetch one contact by id — identity, channels, addresses, properties, tags/lists, custom-field values, teammates, notes, and linked deals. Custom fields include the org’s definitions even when this contact’s `values` are null.
`findContacts`	Fuzzy-search contacts by name, phone, email, or address. Results are relevance-ranked candidates, not guaranteed exact matches; verify the returned name before using its `contactId` in a write.
`findContactsByNote`	Fuzzy-search note bodies from the last year and return one best snippet per matching contact. Searches at most 500 candidate notes per archive state and returns at most 50 contacts, so `totalCount` is not an exhaustive org-wide count.
`findDuplicateContactGroups`	Find groups with the same name (ignoring case/spacing) sharing a phone or email, including chained matches. Reads only active contacts visible to the key owner. Page groups with `limit` (default 50, max 100) and `offset`; `truncated` means `totalCount` is a floor. Name variants and property-only matches are not covered, so an empty result is not proof there are no duplicates. Review each group before `mergeContacts`.
`listContactActivities`	Page one contact’s calls, texts, emails, notes, and system events. Email entries include full plain-text `textExtract` when available; calls include disposition and disposition note. Filter by activity type and direction.
`countContacts`	The number of active contacts visible to your key, in one call — the same total the Contacts page shows.
`listContactFilters`	List saved contact filters visible to the key owner: shared organization filters plus their own private ones. Each row includes the owner’s `userId`; check it before editing a teammate’s filter.
`filterContacts`	Run a saved `filterId` or an unsaved `filterTree`, with `limit`/`offset` pagination and optional `sort: { field, direction }`. Returns contacts plus `total` and `hasMore`; an unsaved tree does not create a filter.
`searchContactTags`	Find existing contact tags and lists by name. Use the returned ids in contact writes.

Use getFilter to read a saved criteria tree before editing it, and saveFilter(type: CONTACT) to create one. Filter authoring and vocabulary discovery are documented in the Properties API. filterContacts and filtered countContacts calls check the resolved criteria against your organization’s plan. A field the plan excludes causes an operation error with code PLAN_ENTITLEMENT_REQUIRED, rather than an empty result. This applies to saved filters as well as inline trees; a saved filter does not preserve access to a feature your plan no longer includes. For filterContacts.sort, direction is ASC or DESC and field is SELLER_INTENT_SCORE, LAST_COMMUNICATION, LAST_ACTIVITY, DIAL_ATTEMPTS (organization-wide outbound dials), MY_LAST_CALL, MY_LAST_TEXT, LAST_UPDATED, CREATED_AT, TASK_HIGHLIGHT, or AUCTION_DATE (earliest upcoming auction or sale day, with contacts having none last). Unknown fields are silently ignored and use the default order; a successful response does not prove a guessed sort field worked.

Writing contacts (`WRITE` scope)

operationId	What it does
`createContact`	Create a contact using `input.sellerFirstName` and `input.sellerLastName`. Optional `addPhoneNumbers`, `addEmails`, and address/custom-field inputs add details. `type` is optional and retained for compatibility; it does not set a deal type on the contact.
`updateContact`	Update one contact by `contactId` — identity, archive state, channels, addresses, properties, relatives, custom-field values, files, tags/lists, teammates, and teams. Add/remove fields are deltas, not replacements; the response echoes custom-field values for read-back.
`addContactNote`	Add a text note to a contact’s timeline. The response is the owning contact, not the note; report its echoed name and re-read the contact if you need the new note id.
`editContactNote`	Rewrite an existing note’s body by `noteId`. The note keeps its id and timeline position. Pass the full replacement body — this replaces the text, it doesn’t append. `noteId`s come from `getContact` (`notes[]`) or a `NOTE` entry in `listContactActivities`; `addContactNote` doesn’t return one, so re-read the contact to find the note you just wrote.
`deleteContactNote`	Permanently delete a note by `noteId`. No undo — when only the wording is wrong, use `editContactNote` instead. One note per call. Returns the owning contact with its remaining notes.
`mergeContacts`	Merge duplicates into one surviving record. `contactIds` is the full set (2 or more); `primaryContactId` is the survivor and must be one of them — it keeps its own custom fields and agent while absorbing the others’ notes, tags, and activities, and the losers are archived. `name` is the survivor’s resulting display name; optional `pointPersonUserId` decides which agent survives when the merged contacts disagree. Applied synchronously.
`addContactTags`	Apply existing tags (by tag id, from `searchContactTags`/`createContactTag`) to contacts. Async — returns a `bulkTaskId` to poll with `getBulkTask`.
`removeContactTags`	Remove free-form tags from contacts without deleting the tag definition. Async; tag-removal workflows may run. Use ids from `searchContactTags.tags` — list/custom-field ids do nothing.
`addContactsToList`	Add contacts to one or more lists. Async; returns a `bulkTaskId`. List membership changes can trigger contact workflows.
`removeContactsFromList`	Remove contacts from lists without deleting the lists. Async and safe when a contact is already absent.
`assignContact`	Assign a teammate to contacts (default role `POINT_PERSON`; `PARTICIPANT` also allowed). Get `userId` from `listTeammates`. Async — returns a `bulkTaskId`.
`unassignContact`	Remove one or more teammates from contacts. Async; it does not hand work to a replacement, except that one remaining participant is promoted when they are the only assignee left. Re-read ownership afterward.
`archiveContacts`	Archive (soft-delete) contacts by id. Runs as an async bulk job — returns a `bulkTaskId` to poll with `getBulkTask`. Recoverable.
`unarchiveContacts`	Restore archived contacts by explicit id. Async. Restoring a duplicate archived by `mergeContacts` does not restore data moved to the survivor.
`renameContactTag`	Rename a free-form tag in place while preserving memberships, filters, and workflow references.
`renameContactList`	Rename a list in place while preserving memberships, filters, and workflow references.
`createContactTag`	Create an organization-wide free-form tag. Returns the tag catalog; read the new id back by name.
`createContactList`	Create an organization-wide contact list. Returns the list catalog; read the new id back by name.
`setContactsCustomField`	Set or clear one `DROPDOWN` custom field across many contacts. Values are option labels, not ids. Async; poll `getBulkTask` because validation failures surface on the worker.
`deleteContactTags`	Delete free-form tags by id (from `createContactTag`); also removes them from any contacts.
`deleteContactLists`	Delete contact lists by id (from `createContactList`); also drops membership.
`deleteContactFilter`	Permanently delete a saved CONTACT filter by `filterId`; no archive or undo. Property/deal filter ids are refused. Check the owner’s `userId` in `listContactFilters` first: an org admin can delete a teammate’s shared filter, while a teammate’s private filter is refused. Prefer `updateFilter` when the criteria only need correcting.

Bulk contact writes can start workflowsAdding or removing tags/lists and setting a custom field publish the same contact-change events as the app. A matching CONTACT workflow can therefore start and send. Check the org’s workflows before changing a large selection, and poll every returned bulkTaskId before reporting success.

Who may edit or delete a noteA non-admin key may only edit or delete notes the key owner authored; anyone else’s are refused. A note whose author.kind is AI counts as someone else’s, so a non-admin key is refused on one — check the author before offering to correct a note. A team-admin key can edit or delete any note.

Custom fields (`READ` + `WRITE` scopes)

Custom fields are organization-wide definitions. These operations manage the definitions themselves; you write per-contact values through the addCustomFieldValues input on createContact and updateCustomFieldValues on updateContact, using the customFieldId from here.

operationId	Scope	What it does
`listContactCustomFields`	`READ`	List the org’s contact custom-field definitions — id, name, type (`TEXT` \| `NUMBER` \| `DOLLAR` \| `DATE` \| `LINK` \| `DROPDOWN`), dropdown options, `allowMultiple`, `defaultValue`.
`createContactCustomField`	`WRITE`	Create a definition: `name` + `type`; `options` required for `DROPDOWN`, `allowMultiple`/`defaultValue` optional. Applied synchronously. Returns the org catalog — read the new id back by matching the name.
`updateContactCustomField`	`WRITE`	Edit a definition in place by id — the right way to fix a wrong name, description, options, or default rather than creating a second field. Everything except the id is optional and omitted fields are untouched. The type cannot be changed. `options` applies to `DROPDOWN` only and replaces the whole list, so send every option you want to keep, each existing one as `{ id, label }`.
`reorderContactCustomFields`	`WRITE`	Set the display order. Presentation only — no definition, option, or recorded value is touched. Pass every custom-field id the org has, in the order you want: call `listContactCustomFields` immediately before and send the complete reordered list. A partial list, an unknown id, or a repeated id is rejected.
`deleteContactCustomField`	`WRITE`	Permanently delete a definition. Destructive and irreversible — every value recorded on every contact for this field is deleted with it and is not moved anywhere. Prefer `updateContactCustomField` when the field is merely wrong. Requires a `dependencyResolution.impactVersion` from `getDeletionImpact` (`targetKind: CONTACT_CUSTOM_FIELD`).

Check the blast radius before deleting a fieldCall getDeletionImpact with targetKind: CONTACT_CUSTOM_FIELD and the field id first. It reports how many contacts hold a value and which filters and workflows reference the field, and returns the impactVersion you must hand back as dependencyResolution.impactVersion — pass an empty replacements array when it reports no replacement requirements.

Enrichment (`ADMIN` scope)

operationId	What it does
`enrichContact`	Skip-trace a contact to discover phone numbers and emails. Consumes one skip-trace credit (real money).
`createContactFromProperty`	Create a CRM contact from a property. Triggers skip-trace enrichment — consumes one skip-trace credit.

Credit-spending operationsEnrichment operations spend your organization’s skip-trace credits, so they require the ADMIN scope and the key owner must currently be a team admin. Check balances first with getBillingSummary — see the Billing API.

Organization guardContact operations declare which ids are pre-checked. These include the contact itself on by-id writes, and tag/list or teammate ids on bulk operations that declare those guards. An inaccessible guarded id returns 403 forbidden. Secondary ids nested in updateContact are validated by the operation as it executes and can return an operation error such as NOT_FOUND. See Authorization for the model.

Example

Find a contact, then add a note to it:

curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "findContacts", "variables": { "searchTerm": "maria alvarez" } }'

curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "addContactNote", "variables": { "contactId": "CONTACT_ID", "body": "Voicemail left 7/9 — call back Friday." } }'

Full variable schemas, response shapes, and worked examples for every operation are available from the discovery endpoint.

Contacts also flow out of Goliath — workflow webhook steps POST a contact payload to your URLs. See the Contact Webhook Payload reference.

Getting Started

TypeScript SDK

Core Resources

Automations

Communication & Tasks

Account & Billing

About

Operations

Reading contacts (`READ` scope)

Writing contacts (`WRITE` scope)

Custom fields (`READ` + `WRITE` scopes)

Enrichment (`ADMIN` scope)

Example

​About

​Operations

​Reading contacts (READ scope)

​Writing contacts (WRITE scope)

​Custom fields (READ + WRITE scopes)

​Enrichment (ADMIN scope)

​Example

About

Operations

Reading contacts (`READ` scope)

Writing contacts (`WRITE` scope)

Custom fields (`READ` + `WRITE` scopes)

Enrichment (`ADMIN` scope)

Example