GoliathDevelopersGet an API key
Guides / Contact Imports API

Contact Imports API

Import contacts from a spreadsheet — map columns, preview, revise and confirm — through the Goliath developer API

About

Bring a spreadsheet of contacts into Goliath the same way the app’s Import page does: start an import from a file, let the import mapper match its columns to Goliath’s fields, preview the contacts it will produce, correct the mapping in plain words if needed, then confirm. Nothing is written to your CRM until the confirm step.

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.

The import flow

  1. startContactImport creates the import from a file and runs the mapper.
  2. If the mapping is still in progress, authorContactImportMapping finishes it.
  3. previewContactImport and getContactImportRowFindings show what will come in.
  4. reviseContactImportMapping changes the mapping, as often as needed.
  5. confirmContactImport imports every row in the background; poll getContactImport until it finishes.

Every step after the first takes the import’s fileProcessingTaskId.

Operations

Building the mapping (WRITE scope)

operationId Scope What it does
startContactImport WRITE Start an import from a chat file by its shelf id (artifactId). Creates the contact upload and runs the import mapper, which can take a few minutes. Returns fileProcessingTaskId, the row count and the columns. .csv, .xlsx and .xls only. Nothing is imported yet.
authorContactImportMapping WRITE Bring the mapping to ready when startContactImport returned it still in progress. Returns at once when it is already ready.
reviseContactImportMapping WRITE Change the mapping in plain words (message, e.g. “column D is the mailing address”) and re-run the mapper. Nothing is imported.

Checking before you import (READ scope)

operationId Scope What it does
previewContactImport READ The first 1 to 10 rows (limit, default 8) as the contacts they will become — name, phones, emails, addresses, tags, lists, deals and custom fields — plus the file’s row count.
getContactImportRowFindings READ Rows (among the first 100) whose phone is not a full US number, so they would come in without it.

Importing (WRITE scope)

operationId Scope What it does
confirmContactImport WRITE Import every row — the app’s Import button. attestationAccepted is required: it records the person’s affirmation that they have a lawful basis to contact these people. Optional tagName, optOutTagName, and reviveArchivedMatches. Starts a background task.
getContactImport READ An import’s status, row count, contacts produced, ETA and tag, with created / matched / restored / skipped / failed counts. Poll it after confirming.

For finished imports — the per-bucket rows and the original CSV line behind each outcome — see the upload reports on the Files API.

Example

Preview an import, then confirm it:

curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "previewContactImport", "variables": { "fileProcessingTaskId": "IMPORT_ID" } }'
curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: confirm-import-IMPORT_ID" \
  -d '{ "operationId": "confirmContactImport", "variables": { "fileProcessingTaskId": "IMPORT_ID", "tagName": "October list", "attestationAccepted": true } }'

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