Skip to Content
ContactDrive HelpHelp

ContactDrive Core REST API (v2)

Integrate with ContactDrive using the REST API

This document is for third-party developers integrating with ContactDrive using an API key.

Base URL

https://api.contactdrive.app/api/v2

Authentication

Send your API key as a Bearer token header:

  1. Bearer token header (required going forward)
  2. apiKey query parameter (deprecated — still accepted, but emits aDeprecation response header and will be removed in a future release)

Header auth example

curl --request GET \
  --url 'https://api.contactdrive.app/api/v2/whoami' \
  --header 'Authorization: Bearer <API_KEY>'

Query auth example

curl --request GET \
  --url 'https://api.contactdrive.app/api/v2/whoami?apiKey=<API_KEY>'

Workspace scope

  • API keys are workspace-scoped
  • The workspace is resolved from the API key
  • You do not pass a workspace ID in these REST calls
  • All results are constrained to the workspace tied to the key

Endpoints most relevant to contact integrations

GET /whoami

Use this first to validate your API key and discover the resolved user/workspace context.

Success response (200)

{
  "userId": "abc123",
  "firstName": "Jane",
  "lastName": "Doe",
  "emailAddress": "jane@example.com",
  "workspaceId": "my-workspace",
  "workspaceName": "My Workspace"
}

Unauthorized response (401)

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "A valid API key is required."
  }
}

Error envelope

All error responses use a consistent shape. field is present on validation

failures and identifies the offending input path:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body must include a \"contact\" object.",
    "field": "contact"
  }
}

Error codes include UNAUTHORIZED (401), VALIDATION_ERROR (422),

NOT_FOUND (404), IDEMPOTENCY_CONFLICT (409), and INTERNAL_ERROR (500).

Idempotency

Send an Idempotency-Key header on POST /PUT /PATCH requests. A repeated

request with the same key (same workspace + route, within 24h) returns the

original response without re-executing.

Dry run

Add ?dryRun=true to a POST /PUT request to validate and authorize it and

receive the would-be record ({ "data": { "dryRun": true, "wouldWrite": … } } )

without writing anything.


GET /workspace

Returns workspace metadata including custom contact field definitions and activity types.

Success response (200)

{
  "workspaceId": "my-workspace",
  "workspaceName": "My Workspace",
  "status": "active",
  "customFields": [
    {
      "value": "customFields.donor_level",
      "label": "Contacts - Donor level"
    }
  ],
  "activityTypes": [
    {
      "value": "call",
      "label": "Phone Call",
      "helpText": ""
    }
  ]
}

GET /contacts

Returns a paginated list of contacts for the API key's workspace.

Query parameters

  • limit (optional, default 10 )
  • offset (optional, default 0 )

Example

curl --request GET \
  --url 'https://api.contactdrive.app/api/v2/contacts?limit=10&offset=0' \
  --header 'Authorization: Bearer <API_KEY>'

Response shape

Returns an array of flattened contact objects. Common keys include:

  • cdId
  • firstName
  • middleName
  • lastName
  • fullname
  • email
  • primaryPhone
  • phoneMobile
  • phoneWork
  • phoneHome
  • organization
  • jobTitle
  • tags
  • notes
  • createdAt
  • Custom fields by slug (for example: donor_level )

POST /contacts

Creates a contact in the API key's workspace. Body: { "contact": { … } } .

Supports ?upsertByExternalId=true (update an existing contact matched on a

shared externalIds entry) and ?dryRun=true .

Returns 201 with { "data": { "contactId", "workspaceId", "created": true } } .

PUT /contacts/:contactId

Updates the supplied fields on a contact. System-managed fields

(workspaceId , createdBy , _id ) are ignored. Supports ?dryRun=true .

POST /contacts/query

Finds contacts that match a filter. The body takes filter, the same versioned filter the contacts grid, saved views and dashboards use, plus optional options and countOnly.

  • filter: { "filterVersion": 1, "collection": "contacts", "match": "AND" | "OR", "conditions": [...] }. All four keys are required. Each condition is { "kind", "field", "operator", "value" }, where kind is text, number, date, set or boolean and fixes which operators are legal. Use { "kind": "group", "match": "OR", "conditions": [...] } to mix AND and OR. Omit filter entirely to match every contact.
  • options: limit (default 100, at most 500), skip, and sort.
  • countOnly: true returns only the count, in paging.total.

Call GET /query/vocabulary for the fields this workspace offers, custom fields included, and the operators each kind accepts.

Example

curl --request POST \
  --url 'https://api.contactdrive.app/api/v2/contacts/query' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": {
      "filterVersion": 1,
      "collection": "contacts",
      "match": "AND",
      "conditions": [
        { "kind": "text", "field": "addresses.state", "operator": "equals", "value": "OH" },
        { "kind": "set", "field": "tags", "operator": "in", "values": ["Volunteer"] }
      ]
    },
    "options": { "limit": 50 }
  }'

A filter the API can't run is answered 422 with a message naming what to change, and nothing is queried.

Changed in 2.39.0: the older flat filters list is no longer accepted. A request that sends filters is answered 422 naming filter. Rewrite each { field, op, value } entry as a condition in filter.conditions. If you use the ContactDrive MCP server through a local install, update it to version 1.9.0 or later.

GET /contacts/search

Text (q ) and external-ID search with pagination.

Integration guidance

  • Use GET /whoami to validate keys
  • Use GET /workspace to discover custom field metadata
  • Use GET /contacts / GET /contacts/search / POST /contacts/query for reads
  • Use POST /contacts and PUT /contacts/:id for writes (send anIdempotency-Key header; preview with ?dryRun=true )

Machine-readable contract

A full OpenAPI 3.1 description is served, unauthenticated, at:

GET /api/v2/openapi.json

Versioning & deprecation policy

  • The API is versioned in the path (/api/v2 ). Breaking changes ship under anew path segment (/api/v3 ); /api/v2 will not change incompatibly once asuccessor exists.
  • Additive changes (new endpoints, new optional fields, new response fields)are not breaking and may land in /api/v2 at any time. Clients mustignore unknown response fields.
  • Deprecated inputs respond with an RFC 8594 Deprecation: true header (anda human-readable Warning ). Currently deprecated: the apiKey queryparameter — send the key as an Authorization: Bearer header instead.
  • A deprecated feature stays functional for at least one successor versionbefore removal.

Other mounted REST paths (not documented here)

  • /activity
  • /apps
  • /services
  • /webhooks

These exist in the server routing layer, but this document is focused on third-party contact integration paths.

On this page