Skip to content
SonoraSonora API

Mark a contact do not contact

PUT
/contacts/{contactId}/do-not-contact
curl --request PUT \
  --url https://api.usesonora.com/v1/contacts/example/do-not-contact \
  --header 'Authorization: Bearer <token>'

Mark the contact do not contact, as the person page’s menu in Sonora does: no workflow or draft emails them again until someone lifts the mark. The mark is on their email address, so it holds however a workflow or draft comes to name them. Their emails and meetings still come in. Marking someone already marked changes nothing, and keeps who marked them and why.

Requires the contacts:write scope. API keys only.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
contactId
required
string

The contact’s Sonora id.

Responses

Section titled “Responses”

200

Section titled “200”

The contact, marked.

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 format: date-time
archivedAt
required
Any of:
string format: date-time
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 format: date-time
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
Examplegenerated
{
  "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

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

403

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

404

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

422

Section titled “422”

contact_has_no_email: The contact has no email address, and a do-not-contact mark lives on the address.

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

429

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

500

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

Try it

Try it runs the reference's read endpoints, and this one changes data, so it needs an API key with the contacts:write scope. Create a key in Sonora under Settings → API and call it from your own code.