Get a contact

GET

/contacts/{contactId}

curl --request GET \
  --url https://api.usesonora.com/v1/contacts/example \
  --header 'Authorization: Bearer <token>'

One contact, departed or archived or not.

Requires the contacts:read scope.

Authorizations

• apiKey
• oauth
  contacts:read

Parameters

Path Parameters

contactId

required

string

The contact’s Sonora id.

Responses

200

The contact.

Media typeapplication/json

A person at one of your customers.

object

id

required

string

customerId

required

The customer the person works at. Null when Sonora hasn’t matched them to one.

string | null

firstName

required

string | null

lastName

required

string | null

name

required

First and last name together; null when Sonora has neither.

string | null

email

required

string | null

phone

required

string | null

title

required

Job title.

string | null

linkedinUrl

required

string | null

isChampion

required

Marked as a champion at their account.

boolean

departedAt

required

Any of:

string

string format: date-time

null

null

archivedAt

required

Any of:

string

string format: date-time

null

null

doNotContact

required

Someone on your team marked the person do-not-contact, so Sonora never emails them. The mark is on the address, so changing it doesn’t move updatedAt.

boolean

externalIds

required

Array<object>

The record’s id in another system.

object

source

required

The system the id is from: salesforce, hubspot, zendesk, intercom, …

string

id

required

string

engagementsCount

required

Calls, emails, meetings and tickets Sonora has seen the person in.

integer

lastEngagementAt

required

Any of:

string

string format: date-time

null

null

createdAt

required

string format: date-time

updatedAt

required

Moves on any change to the record, including Sonora’s own bookkeeping (engagement counts).

string format: date-time

links

required

object

self

required

This resource’s canonical URL on the API host.

string

Example^generated

{
  "id": "example",
  "customerId": "example",
  "firstName": "example",
  "lastName": "example",
  "name": "example",
  "email": "example",
  "phone": "example",
  "title": "example",
  "linkedinUrl": "example",
  "isChampion": true,
  "departedAt": "2026-04-15T12:00:00Z",
  "archivedAt": "2026-04-15T12:00:00Z",
  "doNotContact": true,
  "externalIds": [
    {
      "source": "example",
      "id": "example"
    }
  ],
  "engagementsCount": 1,
  "lastEngagementAt": "2026-04-15T12:00:00Z",
  "createdAt": "2026-04-15T12:00:00Z",
  "updatedAt": "2026-04-15T12:00:00Z",
  "links": {
    "self": "example"
  }
}

401

unauthorized: The Authorization header is missing, or the key is invalid, revoked or expired.

Media typeapplication/json

The one error shape every endpoint answers with.

object

error

required

object

code

required

Stable snake_case code to branch on; see the error table.

string

message

required

For humans; may change.

string

details

object

key

additional properties

requestId

required

Quote it when asking for help.

string | null

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

403

insufficient_scope: The key or token lacks the scope this endpoint needs, and details.required names it; or an OAuth access token called an endpoint only an API key can.

Media typeapplication/json

The one error shape every endpoint answers with.

object

error

required

object

code

required

Stable snake_case code to branch on; see the error table.

string

message

required

For humans; may change.

string

details

object

key

additional properties

requestId

required

Quote it when asking for help.

string | null

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

404

contact_not_found: No contact with that id.

Media typeapplication/json

The one error shape every endpoint answers with.

object

error

required

object

code

required

Stable snake_case code to branch on; see the error table.

string

message

required

For humans; may change.

string

details

object

key

additional properties

requestId

required

Quote it when asking for help.

string | null

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

429

rate_limited: Too many requests for this key; retry after Retry-After seconds.

Media typeapplication/json

The one error shape every endpoint answers with.

object

error

required

object

code

required

Stable snake_case code to branch on; see the error table.

string

message

required

For humans; may change.

string

details

object

key

additional properties

requestId

required

Quote it when asking for help.

string | null

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

500

internal_error: Something went wrong on Sonora’s side. Retry, and quote requestId if it persists.

Media typeapplication/json

The one error shape every endpoint answers with.

object

error

required

object

code

required

Stable snake_case code to branch on; see the error table.

string

message

required

For humans; may change.

string

details

object

key

additional properties

requestId

required

Quote it when asking for help.

string | null

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}