Developer API Overview

About

The Goliath developer API lets your own code — servers, scripts, AI agents, or third-party tools — read and write the same data you work with in the app: contacts, properties, deals and pipelines, workflow automations, forms, and team settings. There is one HTTP endpoint. You never send GraphQL or build queries — instead you call a named operation from a fixed catalog (an operationId) with its variables, and Goliath executes a pre-authored, pre-reviewed request on your behalf. Every call runs as the key’s owning user, so your real organization permissions and visibility apply — the API can never see or touch anything you couldn’t see in the app yourself.

Live in productionThe developer API is live: create and scope a key in the app under Settings → API Keys and call the production endpoint below — no enrollment or approval step. The server also publishes its own always-current reference: GET /api/v1/help (no auth required) renders full documentation for every operation, generated from the running API.

Looking for something simpler?If all you need is programmatic skip tracing, the standalone Skip Trace API is a single-purpose REST endpoint with its own key. To receive data from Goliath instead of calling in, see the Contact Webhook Payload reference.

Generating an API key

Open API Keys. From the app, go to Settings → API Keys (also reachable from the API Keys card on the Integrations page).
Create a key. Keys are personal — each key belongs to your user and acts as you. Create one key per host or device so you can revoke them independently.
Pick scopes. Each key carries one or more scopes (see below). ADMIN can only be granted to a key whose owner is a team admin.
Store the secret. The key looks like gsk_.... Pass it as a Bearer token on every request and keep it in your secrets manager — never ship it in a browser, mobile app, or any client-side code.

Scopes

Scope	Grants
`READ`	Read operations — fetch and list data.
`WRITE`	Mutating operations — create and update records.
`ADMIN`	Team management, analytics, and billing/credit-spending operations. Implies `READ` + `WRITE`. Only grantable to a team admin’s key, and re-checked on every call — if the owner loses admin, the key’s `ADMIN` operations stop working immediately.

Scopes decide what kind of operation a key may run. Which specific records it may touch is a separate check — see Authorization for how organization ownership and the two kinds of 403 work.

Making a request

POST https://server.goliathdata.com/api/v1/call
Authorization: Bearer gsk_...
Content-Type: application/json

{ "operationId": "getContact", "variables": { "contactId": "..." } }

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": "smith" } }'

(POST /api/v1/graphql is the same endpoint under its original name and stays supported — despite that path, it does not accept GraphQL queries either.) A handled request always returns 200 with a GraphQL-style body:

{ "data": { ... }, "errors": [ ... ] }

Transport and authorization problems use HTTP status codes instead:

Status	Code	Meaning
401	`unauthorized`	Missing bearer header, or invalid/revoked key
400	`raw_query_forbidden`	Body contained a `query` — raw GraphQL is never accepted
400	`bad_request`	Body missing a string `operationId`, or malformed `variables`
400	`unknown_operation`	`operationId` is not in the catalog
400	`unknown_variable`	`variables` contained a name the operation doesn’t declare. The message lists the accepted variables — undeclared names are rejected rather than silently ignored, so a typo’d filter can’t quietly return unfiltered results
403	`insufficient_scope`	Key lacks the scope the operation requires
403	`forbidden`	Operation references a resource outside your organization
429	`rate_limited`	Too many calls to a rate-limited operation — retry after the `Retry-After` header
500	`internal_error`	Unexpected failure on our side

Result limits & truncation

Every list/search operation has a result cap — a maximum number of rows it returns per call. If you send a limit larger than the cap, it is silently clamped to the cap: you get the cap’s worth of rows, no error. Most list operations are fully pageable — they take an offset (or a cursor) and return a totalCount and/or hasMore, so you can walk the whole result set a page at a time. Prefer these when you need everything:

# page through all matches
{ "operationId": "findContacts", "variables": { "searchTerm": "smith", "limit": 50, "offset": 0 } }
{ "operationId": "findContacts", "variables": { "searchTerm": "smith", "limit": 50, "offset": 50 } }

Two operations still cap without paginationThese have no offset/cursor, so rows beyond the cap can’t be retrieved:

listAppointments (cap 50) — returns a total, so if it exceeds the rows you got back, narrow the date range rather than expecting more pages.
listFormActivityLocations (cap 500) — returns no total; treat a full page (exactly the cap) as “possibly more, narrow it.”

Wider pagination on these two is on the roadmap.

Discovering operations

The full operation catalog is machine-readable — ideal for AI agents and for keeping your integration in sync:

GET https://server.goliathdata.com/api/v1/operations
Authorization: Bearer gsk_...
→ 200 { "operations": [{ "operationId", "operationType", "requiredScope", "summary", "authorized" }] }

GET https://server.goliathdata.com/api/v1/operations/:operationId
→ 200 { variables, responseShape, example, notes, ... }

The list returns one-line summaries of every operation.
The detail view returns the full variable schema, the exact response shape, and a copy-pasteable example for one operation.
authorized reflects your key’s scopes, so a caller sees exactly what it is allowed to run.

Operation reference by area

The catalog is documented alongside each feature’s user guides:

Properties API — look up and search properties, run saved filters, manage tags and lists
Contacts API — read, create, update, and enrich contacts
Deals API — read, create, update, and archive deals
Pipelines API — manage pipeline structure and read pipeline analytics
Workflows API — manage workflow automations and runs
Content Templates API — manage message templates and folders
Forms API — manage lead-capture forms and read form analytics
Communications API — read inbox threads, recordings and transcripts, manage suppressions, and render templates
Notifications API — read your notification feed and mark items read
Appointments API — schedule appointments and manage your availability
Tasks API — create, reschedule, and complete CRM to-do tasks
Skip Trace API — run skip traces from your own systems
Bulk Tasks API — poll the status of long-running bulk jobs
Team API — teammates, invites, and team analytics
Account API — your profile and integration setup links
Billing API — plan, credit balances, and credit prices

Not yet available

A few capabilities on the developer-API roadmap aren’t exposed yet — use the app for these until they ship:

File uploads — importing contacts, properties, or skip-trace lists from a CSV.
Signal coverage — querying data-coverage by county/ZIP/state.

The discovery endpoint is always the source of truth for what your key can call right now — if an operation isn’t listed there, it isn’t available yet.

Getting Started

TypeScript SDK

Core Resources

Automations

Communication & Tasks

Account & Billing

About

Generating an API key

Scopes

Making a request

Result limits & truncation

Discovering operations

Operation reference by area

Not yet available

​About

​Generating an API key

​Scopes

​Making a request

​Result limits & truncation

​Discovering operations

​Operation reference by area

​Not yet available

About

Generating an API key

Scopes

Making a request

Result limits & truncation

Discovering operations

Operation reference by area

Not yet available