SonarSend API Endpoints Custom fields

Custom fields

The typed schema that contact values live in.

3 endpoints Base URL · https://api.sonarsend.com Auth · X-API-Key

The CustomFieldDefinition object 10 fields

created_atdate-time · nullable

currency_codestring · nullable

ISO 4217 code for a currency field; null otherwise.

default_valueany

Optional default. Free-form — shape depends on field_type.

enum_valuesstring[] · nullable

For enum (and open string) fields: the allowed / suggested values. Null otherwise.

field_keystring

The key contacts store values under. Derived from name when not supplied at creation; immutable thereafter.

field_typeenum

The value type. Cannot be changed after creation — the stored values were written against it.

One of: string, number, boolean, date, datetime, time, enum, tags, email, url, timezone, country, currency, contact

iduuid

Definition ID. Used in the update, delete and usage paths.

namestring

Human label.

tenant_iduuid

value_constraintenum

strict accepts only listed enum_values; open grows the list as new values arrive. Only meaningful for enum and string; always strict for other types.

One of: strict, open

The ContactStage object 9 fields

categoryenum

Coarse grouping. Drives which score (prospect vs customer) a contact in this stage is scored on.

One of: prospect, customer, churned, disqualified, partner

colorstring · nullable

Hex swatch for the UI, e.g. #3366FF. Null when unset.

created_atdate-time · nullable

descriptionstring · nullable

iduuid

namestring

slugstring

Stable key derived from name.

sort_orderinteger

Display order within the pipeline.

tenant_iduuid

List custom field definitions

GET /t/{slug}/api/settings/custom-fields

The account's custom field schema — the typed fields a contact's custom_fields values are written against. Managing these definitions is scoped on custom-fields:*, deliberately separate from contacts:write: writing a contact's values and changing the schema those values live in are different powers. Requires custom-fields:read.

Returns

A page of CustomFieldDefinition objects, under data.

CustomFieldDefinition 10 fields

Responses

200

The account's custom field definitions.

400

The request failed validation, or a referenced record was rejected.

404

The tenant slug, or the record the path names, does not exist.

Request

curl -X GET "https://api.sonarsend.com/t/acme/api/settings/custom-fields" \
  -H "X-API-Key: $SONARSEND_API_KEY"

const res = await fetch('https://api.sonarsend.com/t/acme/api/settings/custom-fields', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.SONARSEND_API_KEY },
});

const data = await res.json();

Response 200

{
  "data": [
    {
      "id": "9c21895d-57f0-4a15-a1df-4dc6835d4f80",
      "tenant_id": "9c21895d-57f0-4a15-a1df-4dc6835d4f80",
      "name": "Acme onboarding",
      "field_key": "welcome-series",
      "field_type": "string",
      "enum_values": [
        "string"
      ]
    }
  ],
  "next_cursor": "eyJpZCI6IjljMjE4OTVkIn0",
  "has_more": true
}

Check what uses a custom field

GET /t/{slug}/api/settings/custom-fields/{id}/usage

Counts what references a field, per source — the thing to call before a delete, since a non-zero cross-module reference is what makes deletion fail with FIELD_IN_USE. Requires custom-fields:read.

Returns { usage }, an object keyed by source (contacts, segments, saved_filters, automations) with a count for each; a source with no references may be omitted. contacts counts how many contacts hold a value and does not block deletion — only the other sources do.

Path parameters

id string Required

Returns

usageobject

Reference counts keyed by source (contacts, segments, saved_filters, automations).

Responses

200

Per-source usage counts.

400

The request failed validation, or a referenced record was rejected.

404

The tenant slug, or the record the path names, does not exist.

Request

curl -X GET "https://api.sonarsend.com/t/acme/api/settings/custom-fields/9c21895d-57f0-4a15-a1df-4dc6835d4f80/usage" \
  -H "X-API-Key: $SONARSEND_API_KEY"

const res = await fetch('https://api.sonarsend.com/t/acme/api/settings/custom-fields/9c21895d-57f0-4a15-a1df-4dc6835d4f80/usage', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.SONARSEND_API_KEY },
});

const data = await res.json();

Response 200

{
  "usage": {}
}

List contact stages

GET /t/{slug}/api/settings/stages

The account's pipeline stages, in display order — the values a contact's stage_id can point at. Read with contacts:read (a stage is contact metadata, not part of the custom-field schema; only reading is exposed to the API, stage management is admin-UI only). Each stage carries a category that decides whether a contact in it is scored on its prospect or customer score.

Returns

A page of ContactStage objects, under data.

ContactStage 9 fields

Responses

200

The account's pipeline stages, in display order.

400

The request failed validation, or a referenced record was rejected.

404

The tenant slug, or the record the path names, does not exist.

Request

curl -X GET "https://api.sonarsend.com/t/acme/api/settings/stages" \
  -H "X-API-Key: $SONARSEND_API_KEY"

const res = await fetch('https://api.sonarsend.com/t/acme/api/settings/stages', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.SONARSEND_API_KEY },
});

const data = await res.json();

Response 200

{
  "data": [
    {
      "id": "9c21895d-57f0-4a15-a1df-4dc6835d4f80",
      "tenant_id": "9c21895d-57f0-4a15-a1df-4dc6835d4f80",
      "name": "Acme onboarding",
      "slug": "acme",
      "category": "prospect",
      "color": "string"
    }
  ],
  "next_cursor": "eyJpZCI6IjljMjE4OTVkIn0",
  "has_more": true
}