GoliathDevelopersGet an API key
Get started / Quickstart

Your first call, in four minutes.

Create a key, send one request, get a contact back, then write one safely.

1

Create a key

In the app · Settings → API keys

Pick the scopes your code needs: READ to look things up, and WRITE too, for step 4's create. The full secret appears once, so put it in your secrets manager. It's a server-to-server key: never ship it in a browser or a phone app.

New API keywhat you'll see in Settings
gsk_••••••••••••••••••••••••
Shown once. Every call runs as you, with your permissions and your contact visibility.

Open Settings → API keys ↗

2

Make your first call

One endpoint · an operationId and its variables

There is one HTTP endpoint. You never send a GraphQL query: you name an operation from the catalog and pass its variables.

curl https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer $GOLIATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": "findContacts",
    "variables": {
      "searchTerm": "Jane Doe",
      "limit": 5
    }
  }'
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.findContacts({
  searchTerm: 'Jane Doe',
  limit: 5
})
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',
  },
  body: JSON.stringify({
    operationId: 'findContacts',
    variables: {
      searchTerm: 'Jane Doe',
      limit: 5
    }
  }),
})
const { data, errors } = await res.json()
3

Read what comes back

200 with data, or an HTTP status with a stable code

A handled request always returns 200 { data, errors? }. Auth and transport problems return an HTTP status with the code in errors[0].extensions.code, to switch on: every code.

200 · example values
HTTP/1.1 200 OK

{
  "data": {
    "contactQuery": {
      "getContactIdentityResults": {
        "results": [
          { "contactId": "ctc_8f2…", "personName": "Jane Doe",
            "propertyAddress": "1148 Linden Ave, Nashville, TN",
            "phoneNumber": "+13235550100", "isArchived": false }
        ],
        "totalCount": 1,
        "hasMore": false
      }
    }
  }
}
4

Write, safely

Always send an Idempotency-Key

Send an Idempotency-Key on every write. If the request times out, retrying with the same key replays the stored result instead of creating a second contact.

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": "createContact",
    "variables": {
      "input": {
        "sellerFirstName": "Jane",
        "sellerLastName": "Doe",
        "type": "UNDETERMINED",
        "addPhoneNumbers": [
          {
            "phoneNumber": "+13235550100",
            "verificationStatus": "UNVERIFIED"
          }
        ],
        "addEmails": [
          {
            "email": "jane@example.com",
            "verificationStatus": "UNVERIFIED"
          }
        ]
      }
    }
  }'
import { GoliathClient } from '@goliath-data/sdk'

const goliath = new GoliathClient({
  apiKey: process.env.GOLIATH_API_KEY!,
  baseUrl: 'https://server.goliathdata.com',
})

// Enum values as strings: the SDK's enum types aren't exported yet, so assert to the method's variables type.
const variables = {
  input: {
    sellerFirstName: 'Jane',
    sellerLastName: 'Doe',
    type: 'UNDETERMINED',
    addPhoneNumbers: [
      {
        phoneNumber: '+13235550100',
        verificationStatus: 'UNVERIFIED'
      }
    ],
    addEmails: [
      {
        email: 'jane@example.com',
        verificationStatus: 'UNVERIFIED'
      }
    ]
  }
} as Parameters<typeof goliath.contacts.createContact>[0]

const result = await goliath.contacts.createContact(variables, { 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: 'createContact',
    variables: {
      input: {
        sellerFirstName: 'Jane',
        sellerLastName: 'Doe',
        type: 'UNDETERMINED',
        addPhoneNumbers: [
          {
            phoneNumber: '+13235550100',
            verificationStatus: 'UNVERIFIED'
          }
        ],
        addEmails: [
          {
            email: 'jane@example.com',
            verificationStatus: 'UNVERIFIED'
          }
        ]
      }
    }
  }),
})
const { data, errors } = await res.json()