API reference

POST/v1/accountsCreate Company

Required scopes: contacts:write

Parameters

Field	Type and constraints
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

CompanyData

Field	Type and constraints
`COMPANY_ID`Optional	`string` \| `null`
`COMPANY_NAME`Optional	`string` \| `null`
`COMPANY_DOMAIN`Optional	`string` \| `null`
`COMPANY_CITY`Optional	`string` \| `null`
`COMPANY_STATE`Optional	`string` \| `null`
`COMPANY_COUNTRY`Optional	`string` \| `null`
`COMPANY_LOGO_URL`Optional	`string` \| `null`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

POST/v1/accounts/from-searchSave Company

Required scopes: contacts:write

Parameters

Field	Type and constraints
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

SaveCompanySource

Field	Type and constraints
`COMPANY_ID`Required	`string` Min length: `1` · Max length: `256` · Pattern: `"^[^\\x00-\\x1f\\x7f]+$"`
`target`Optional	`SourceTarget` \| `null`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

LookupResult_CompanyView_

POST/v1/accounts/lookupLookup Companies

Required scopes: contacts:read

Request body Required

application/json

RecordLookup

Field	Type and constraints
`ids`Required	array of `string` Min items: `1` · Max items: `100`
`id_type`Optional	`"source" \| "record"` Default: `"record"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/accounts/{identity}Company

Required scopes: contacts:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Min length: `1` · Max length: `256` · Pattern: `"^[^\\x00-\\x1f\\x7f]+$"`
`id_type`Optionalquery	`"source" \| "record"` Default: `"record"`

Responses

200 Successful Response

application/json

CompanyView

422 Validation Error

application/json

PATCH/v1/accounts/{identity}Edit Company

Required scopes: contacts:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

CompanyEdit

Field	Type and constraints
`expected_revision`Required	`integer`
`state`Optional	`"active" \| "archived"` \| `null`
`COMPANY_ID`Optional	`string` \| `null`
`COMPANY_NAME`Optional	`string` \| `null`
`COMPANY_DOMAIN`Optional	`string` \| `null`
`COMPANY_CITY`Optional	`string` \| `null`
`COMPANY_STATE`Optional	`string` \| `null`
`COMPANY_COUNTRY`Optional	`string` \| `null`
`COMPANY_LOGO_URL`Optional	`string` \| `null`
`remove_overrides`Optional	array of `"COMPANY_NAME" \| "COMPANY_DOMAIN" \| "COMPANY_CITY" \| "COMPANY_STATE" \| "COMPANY_COUNTRY" \| "COMPANY_LOGO_URL"` Remove selected provided overrides and use the selected owned snapshot values. Requires a catalogue-backed licensed record; omission preserves overrides, null still masks a value. No purchase or source refresh. Min items: `1` · Max items: `64`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

POST/v1/accounts/{identity}/preview-refreshesRefresh Company

Required scopes: contacts:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

PreviewRefresh

Field	Type and constraints
`expected_revision`Required	`integer`
`expected_check_revision`Required	`integer`
`version_id`Required	`string` Pattern: `"^[a-f0-9]{32}$"`
`reset_overrides`Optional	array of "FIRST_NAME" \| "LAST_NAME" \| "MIDDLE_NAME" \| "JOB_TITLE" \| "DEPARTMENT" \| "SENIORITY_LEVEL" \| "HEADLINE" \| "SUMMARY" \| "SKILLS" \| "WORK_EXPERIENCE" \| "EDUCATION_HISTORY" \| "POSTS" \| "CURRENT_BUSINESS_EMAIL" \| "CURRENT_BUSINESS_EMAIL_VALIDATION_STATUS" \| "CURRENT_BUSINESS_EMAIL_VALIDATION_DATE" \| "EMAILS" \| "PHONES" \| "MOBILE_PHONE" \| "MOBILE_PHONE_VALIDATION_STATUS" \| "LINKEDIN_URL" \| "PERSONAL_CITY" \| "PERSONAL_STATE" \| "PERSONAL_COUNTRY" \| "PERSONAL_ADDRESS" \| "PERSONAL_ZIP" \| "LAST_UPDATED" \| "COMPANY_NAME" \| "COMPANY_DOMAIN" \| "COMPANY_DESCRIPTION" \| "COMPANY_INDUSTRY" \| "COMPANY_REVENUE_RANGE" \| "COMPANY_NUM_EMPLOYEE_RANGE" \| "COMPANY_OWNERSHIP" \| "COMPANY_LATEST_FUNDING_STAGE" \| "COMPANY_LATEST_FUNDING_ROUND_DATE" \| "COMPANY_TOTAL_FUNDING" \| "COMPANY_STOCK_EXCHANGE" \| "COMPANY_TICKER_SYMBOL" \| "COMPANY_STOCK_SYMBOL" \| "COMPANY_MARKET_CAPITALIZATION" \| "COMPANY_TOTAL_REVENUE" \| "COMPANY_NUMBER_OF_FOLLOWERS" \| "COMPANY_CITY" \| "COMPANY_STATE" \| "COMPANY_COUNTRY" \| "COMPANY_COUNTRY_NUMERIC" \| "COMPANY_ADDRESS" \| "COMPANY_ZIP_CODE" \| "COMPANY_FOUNDED_YEAR" \| "COMPANY_LINKEDIN_URL" \| "COMPANY_FACEBOOK_URL" \| "COMPANY_TWITTER_URL" \| "COMPANY_ANGELLIST_URL" \| "COMPANY_TECHNOLOGIES" \| "COMPANY_RETAIL_LOCATION_COUNT" \| "COMPANY_ID" \| "COMPANY_LOGO_URL" \| "UUID" \| "PHOTO_URL" Max items: `64`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/accounts/{identity}/source-checksCompany History

Required scopes: contacts:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`after`Optionalquery	`integer` Default: `0` · Minimum: `0` · Maximum: `9007199254740991`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

SourceCheckHistory

422 Validation Error

application/json

POST/v1/accounts/{identity}/source-checksCheck Company

Required scopes: contacts:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

SourceCheck

Field	Type and constraints
`expected_revision`Required	`integer`
`expected_check_revision`Required	`integer`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

Analytics3 operations

GET/analytics/deliveryDelivery Analytics

Required scopes: usage:read

Parameters

Field	Type and constraints
`start`Optionalquery	`number` \| `null`
`end`Optionalquery	`number` \| `null`
`campaign_id`Optionalquery	`string` \| `null`

Responses

200 Successful Response

application/json

DeliverySummary

422 Validation Error

application/json

GET/analytics/delivery-daysDaily Delivery Analytics

Required scopes: usage:read

Parameters

Field	Type and constraints
`start`Requiredquery	`number`
`end`Requiredquery	`number`
`timezone`Optionalquery	`string` Default: `""` · Max length: `128`
`campaign_id`Optionalquery	`string` \| `null`

Responses

200 Successful Response

application/json

DailyDeliveryDays

409 Invalid cohort window/timezone or unavailable campaign; inspect detail.code

application/json

422 Validation Error

application/json

GET/analytics/verificationVerification Analytics

Required scopes: usage:read

Parameters

Field	Type and constraints
`start`Optionalquery	`number` \| `null`
`end`Optionalquery	`number` \| `null`

Responses

200 Successful Response

application/json

VerificationCohorts

422 Validation Error

application/json

Billing30 operations

POST/billing/card-setupsSetup

Required scopes: spending:write

Request body Required

application/json

CardRequest

Field	Type and constraints
`id`Required	`string` Min length: `1` · Max length: `128` · Pattern: `"^[^_].*$"`
`revision`Required	`integer` Minimum: `0.0`

Responses

200 Successful Response

application/json

CardSetupResult

422 Validation Error

application/json

POST/billing/card-setups/{identity}/completeComplete

Required scopes: spending:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

CardChangeResult

422 Validation Error

application/json

GET/billing/cardsCards

Required scopes: usage:read

Parameters

Field	Type and constraints
`after`Optionalquery	`string` Default: `""` · Max length: `128`

Responses

200 Successful Response

application/json

SavedCards

422 Validation Error

application/json

CardChangeResult | CardRemovalRejected

POST/billing/cards/{method}/removeRemove

Required scopes: spending:write

Parameters

Field	Type and constraints
`method`Requiredpath	`string`

Request body Required

application/json

CardRequest

Field	Type and constraints
`id`Required	`string` Min length: `1` · Max length: `128` · Pattern: `"^[^_].*$"`
`revision`Required	`integer` Minimum: `0.0`

Responses

200 Successful Response

application/json

Original removal rejected before any effect; select another primary separately

{
  "id": "example-remove-required",
  "method": "pm_exampleRequired",
  "revision": 7,
  "completed": false,
  "outcome": "rejected_no_effect",
  "reason": "subscription_replace_default_card_first",
  "replayed": false
}

Same original remains rejected; replay does not attempt detachment

{
  "id": "example-remove-required",
  "method": "pm_exampleRequired",
  "revision": 7,
  "completed": false,
  "outcome": "rejected_no_effect",
  "reason": "subscription_replace_default_card_first",
  "replayed": true
}

422 Validation Error

application/json

GET/billing/historyCustomer History

Required scopes: usage:read

Parameters

Field	Type and constraints
`start`Requiredquery	`number`
`end`Requiredquery	`number`
`before`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`
`kind`Optionalquery	`string` \| `null`
`campaign`Optionalquery	`string` \| `null`

Responses

200 Successful Response

application/json

BillingHistoryPage

422 Validation Error

application/json

PATCH/billing/preferencesPreferences

Required scopes: spending:write

Request body Required

application/json

DefaultCard

Field	Type and constraints
`id`Required	`string` Min length: `1` · Max length: `128` · Pattern: `"^[^_].*$"`
`revision`Required	`integer` Minimum: `0.0`
`method`Required	`string` Max length: `128` · Pattern: `"^pm_[A-Za-z0-9]+$"`

Responses

200 Successful Response

application/json

CardChangeResult

422 Validation Error

application/json

GET/billing/subscriptionStatus

Required scopes: usage:read

Parameters

Field	Type and constraints
`changes_after`Optionalquery	`string` Default: `""` · Max length: `128`
`invoices_after`Optionalquery	`string` Default: `""` · Max length: `128`

Responses

200 Successful Response

application/json

SubscriptionSnapshot

422 Validation Error

application/json

POST/billing/subscription/changesReview

Required scopes: spending:write

Request body Required

application/json

Review

Field	Type and constraints
`id`Required	`string` Min length: `1` · Max length: `128` · Pattern: `"^[^_].*$"`
`revision`Required	`integer` Minimum: `0.0`
`daily_sends`Required	`integer` Minimum: `0.0` · Maximum: `900.0`
`provisioning_policy`Optional	`"inboxkit-provisioning-v1"` \| `null`

Responses

200 Successful Response

application/json

SubscriptionChange

422 Validation Error

application/json

SubscriptionChangeStatus

GET/billing/subscription/changes/{identity}Change

Required scopes: usage:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

POST/billing/subscription/changes/{identity}/cancelCancel

Required scopes: spending:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

SubscriptionSnapshot

422 Validation Error

application/json

SubscriptionConfirmation

POST/billing/subscription/changes/{identity}/confirmConfirm

Required scopes: spending:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Request body Required

application/json

Confirmation

Field	Type and constraints
`revision`Required	`integer` Minimum: `0.0`
`maximum_cents`Required	`integer` Minimum: `0.0`
`policy`Required	`string` Max length: `64`
`provisioning_policy`Optional	`"inboxkit-provisioning-v1"` \| `null`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

POST/billing/subscription/changes/{identity}/recoverRecover

Required scopes: spending:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Request body Required

application/json

Recovery

Field	Type and constraints
`maximum_cents`Required	`integer` Minimum: `0.0`

Responses

200 Successful Response

application/json

SubscriptionRecovery

422 Validation Error

application/json

GET/billing/top-upsTop Ups

Required scopes: usage:read

Historical sending-wallet funding, not subscription capacity or metered data funds. New authority is disabled after subscription cutover; retain original read/cancel recovery. Use /billing/subscription for capacity and /v1/billing/data-fundings for metered data.

Parameters

Field	Type and constraints
`after`Optionalquery	`string` Default: `""` · Max length: `128`

Responses

200 Successful Response

application/json

LegacyFundingHistory

422 Validation Error

application/json

GET/billing/top-ups/{identity}Top Up Status

Required scopes: usage:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

LegacyFundingResult

422 Validation Error

application/json

POST/billing/top-ups/{identity}/cancelCancel Top Up

Required scopes: spending:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

LegacyFundingResult

422 Validation Error

application/json

POST/billing/top-ups/{identity}/confirmConfirm Top Up

Required scopes: spending:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

LegacyFundingResult

422 Validation Error

application/json

GET/billing/verification-usageCustomer Verification Usage

Required scopes: usage:read

Parameters

Field	Type and constraints
`start`Requiredquery	`number`
`end`Requiredquery	`number`
`campaign`Optionalquery	`string` \| `null`
`before`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `100`

Responses

200 Successful Response

application/json

VerificationUsagePage

422 Validation Error

application/json

GET/v1/billing/data-autopayGet

Required scopes: billing:read

Responses

200 Successful Response

application/json

MandateView

PATCH/v1/billing/data-autopayUpdate

Required scopes: billing:write spending:write

Parameters

Field	Type and constraints
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

MandateChange

Field	Type and constraints
`revision`Required	`integer` Minimum: `0.0`
`enabled`Required	`boolean`
`policy_id`Required	`"data-autopay-test-v1" \| "data-autopay-live-v1"`
`billing_revision`Required	`integer` Minimum: `0.0`
`low_water_minor`Required	`integer` Minimum: `0.0` · Maximum: `100000.0`
`refill_minor`Required	`integer` Minimum: `500.0` · Maximum: `100000.0`
`max_charge_minor`Required	`integer` Minimum: `500.0` · Maximum: `100000.0`
`max_month_minor`Required	`integer` Minimum: `500.0` · Maximum: `10000000.0`
`expires_at`Optional	`number` \| `null`

Responses

200 Successful Response

application/json

MandateView

422 Validation Error

application/json

GET/v1/billing/data-balanceBalance

Required scopes: billing:read

Responses

200 Successful Response

application/json

DataBalance

Only available money is spendable; adding a verified card earns the separate bonus without enabling top-up

{
  "currency": "usd",
  "available_minor": 500,
  "promotional_minor": 500,
  "debt_minor": 0,
  "purchase_blocked": false,
  "signup_bonus": {
    "card_bonus_minor": 500,
    "card_bonus_state": "pending"
  }
}

POST/v1/billing/data-funding-reviewsReview

Required scopes: billing:write spending:write

Parameters

Field	Type and constraints
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

FundingAmount

Field	Type and constraints
`amount_minor`Required	`integer` Minimum: `500.0` · Maximum: `100000.0`
`currency`Optional	`"usd"` Default: `"usd"`
`billing_revision`Required	`integer` Minimum: `0.0`

Responses

200 Successful Response

application/json

FundingReview

422 Validation Error

application/json

GET/v1/billing/data-funding-reviews/by-keyReview By Key

Required scopes: billing:read

Parameters

Field	Type and constraints
`key`Requiredquery	`string` Min length: `8` · Max length: `128`

Responses

200 Successful Response

application/json

FundingReview

422 Validation Error

application/json

GET/v1/billing/data-funding-reviews/{identity}Review Original

Required scopes: billing:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

FundingReview

422 Validation Error

application/json

GET/v1/billing/data-fundingsHistory

Required scopes: billing:read

Parameters

Field	Type and constraints
`after`Optionalquery	`string` Default: `""` · Max length: `32`

Responses

200 Successful Response

application/json

FundingHistory

422 Validation Error

application/json

POST/v1/billing/data-fundingsConfirm

Required scopes: billing:write spending:write

Parameters

Field	Type and constraints
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

FundingConfirmation

Field	Type and constraints
`review_id`Required	`string` Pattern: `"^[a-f0-9]{32}$"`
`expected_digest`Required	`string` Pattern: `"^[a-f0-9]{64}$"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/billing/data-fundings/by-keyBy Key

Required scopes: billing:read

Parameters

Field	Type and constraints
`key`Requiredquery	`string` Min length: `8` · Max length: `128`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/billing/data-fundings/{identity}Original

Required scopes: billing:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

POST/v1/billing/data-fundings/{identity}/cancelCancel

Required scopes: billing:write spending:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

POST/v1/billing/data-fundings/{identity}/confirmConfirmation

Required scopes: billing:write spending:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Request body Required

application/json

FundingConfirmation

Field	Type and constraints
`review_id`Required	`string` Pattern: `"^[a-f0-9]{32}$"`
`expected_digest`Required	`string` Pattern: `"^[a-f0-9]{64}$"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/billing/data-usageUsage

Required scopes: billing:read

Parameters

Field	Type and constraints
`after`Optionalquery	`string` Default: `""` · Max length: `128`

Responses

200 Successful Response

application/json

DataUsage

422 Validation Error

application/json

Campaign copy policy1 operations

GET/campaign-copy-policyCopy Policy

Required scopes: campaigns:read

Responses

200 Successful Response

application/json

CopyPolicy

Campaign copy preview1 operations

POST/campaign-copy-previewCopy Preview

Required scopes: campaigns:write

Request body Required

application/json

CopyPreviewIn

Field	Type and constraints
`template_format`Optional	`integer` Default: `1` · Minimum: `1.0` · Maximum: `2.0`
`campaign`Required	`string` Min length: `1` · Max length: `128`
`recipient`Required	`string` Min length: `1` · Max length: `320`
`fields`Optional	`object`
`subject`Optional	`string` \| `null`
`body`Required	`string` Min length: `1` · Max length: `100000`
`step`Required	`integer` Minimum: `0.0`
`variation`Required	`integer` Minimum: `0.0` · Maximum: `999999.0`
`sender_mailbox`Optional	`string` \| `null`

Responses

200 Successful Response

application/json

CopyPreview

422 Validation Error

application/json

Campaigns50 operations

GET/campaignsCampaigns

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cursor`Optionalquery	`string` Default: `""` · Max length: `4096`
`limit`Optionalquery	`integer` Default: `100` · Minimum: `1` · Maximum: `1000`
`archive`Optionalquery	`"current" \| "archived" \| "all"` Default: `"current"`
`name_prefix`Optionalquery	`string` Literal ASCII-case-insensitive prefix. A nonempty prefix orders by normalized name then ID ascending; otherwise newest first. Default: `""` · Max length: `200`
`state`Optionalquery	`"draft" \| "active" \| "paused" \| "complete"` \| `null` Filter by current Campaign state.

Responses

200 Successful Response

application/json

CampaignListPage

422 Validation Error

application/json

POST/campaignsCreate

Required scopes: campaigns:write

Request body Required

application/json

CampaignIn

Field	Type and constraints
`list_ids`Optional	array of `string` Max items: `50`
`operation_id`Optional	`string` \| `null`
`name`Required	`string` Min length: `1` · Max length: `200`
`offer`Optional	`string` Default: `""` · Max length: `10000`
`audience_prompt`Optional	`string` Default: `""` · Max length: `10000`
`steps`Required	array of `Step` Min items: `1` · Max items: `10`
`schedule`Optional	`Window`
`daily_limit`Optional	`integer` Finite campaign outbound sends per local sending day. Zero means unallocated: no new outbound sends or automatic preparation. The selected sending pool, shared capacity and current safeguards still apply. Default: `0` · Minimum: `0.0` · Maximum: `15000.0`
`sending_pool`Optional	`"mailbox" \| "transactional" \| "all"` Authorized sending capacity: mailbox by default, transactional or all only with an admin grant. Does not classify message content. Default: `"mailbox"`
`allow_catch_all`Optional	`boolean` Default: `false`
`template_format`Optional	`integer` Default: `1` · Minimum: `1.0` · Maximum: `2.0`
`name_cleaning`Optional	`NameMapping` \| `null`
`import_digest`Optional	`string` Default: `""` · Pattern: `"^(?:[0-9a-f]{64})?$"`
`id`Required	`string` Min length: `1` · Max length: `128`
`contacts`Optional	array of `Contact` Max items: `1000`
`expected_contacts`Optional	`integer` Default: `0` · Minimum: `0.0` · Maximum: `100000.0`

Responses

200 With operation_id: immutable Result, identical to the draft-operation original. Without it: CampaignCreated stored row; no keyed recovery.

application/json

Result | CampaignCreated

Synthetic empty draft created with operation_id=create-empty. No contact, charge or send. After response loss, GET the original; an exact keyed replay returns this same receipt.

{
  "operation": {
    "id": "create-empty",
    "workspace": "workspace",
    "campaign": "empty-draft",
    "action": "create",
    "request_digest": "48a409ab38799ab2dd66fc587789befc87153409b62f0029f32e6224e74928e5",
    "actor": "service:1074c3d56ba74f8c5bc2e4d260925e5fc9ec104cc000848b66289d0897c4942a",
    "expected_revision": null,
    "before_revision": null,
    "after_revision": 1,
    "outcome": "recorded",
    "state_after": "draft",
    "counts": {
      "contacts": 0,
      "added": 0,
      "excluded": 0
    },
    "recorded_at": 1791763200
  }
}

409 Conflict

application/json

CampaignConflict

422 Validation Error

application/json

PATCH/campaigns/allocationsUpdate

Required scopes: campaigns:write spending:write

Request body Required

application/json

AllocationApply

Field	Type and constraints
`operation_id`Required	`string` Min length: `1` · Max length: `128` · Pattern: `"^[A-Za-z0-9][A-Za-z0-9._~-]*$"`
`configuration`Required	`string` Pattern: `"^[a-f0-9]{64}$"`
`changes`Required	array of `AllocationChange` Min items: `1` · Max items: `100`

Responses

200 Successful Response

application/json

AllocationResult

422 Validation Error

application/json

POST/campaigns/allocations/previewInspect

Required scopes: campaigns:read

Request body Required

application/json

AllocationPreviewIn

Field	Type and constraints
`timezone`Optional	`string` Default: `"UTC"` · Max length: `128`
`changes`Optional	array of `AllocationChange` Max items: `100`

Responses

200 Successful Response

application/json

AllocationPreview

422 Validation Error

application/json

GET/campaigns/allocations/{operation_id}Original

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`operation_id`Requiredpath	`string`

Responses

200 Successful Response

application/json

AllocationResult

422 Validation Error

application/json

POST/campaigns/schedule-adviceRead

Required scopes: campaigns:read

Request body Required

application/json

ScheduleAdviceRequest

Field	Type and constraints
`items`Required	array of `ScheduleAdviceDraft` \| `ScheduleAdviceSaved` Min items: `1` · Max items: `50`

Responses

200 Successful Response

application/json

ScheduleAdviceResponse

422 Validation Error

application/json

GET/campaigns/{cid}Campaign

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`cursor`Optionalquery	`string` Default: `""`
`limit`Optionalquery	`integer` Default: `100` · Minimum: `1` · Maximum: `1000`

Responses

200 Successful Response

application/json

CampaignDetail

422 Validation Error

application/json

PATCH/campaigns/{cid}Update

Required scopes: campaigns:write

Conditional scopes

sources requires contacts:read.

published_behavior requires spending:write.

Atomically save changed fields; published behavior also requires owner and spending:write. Omission preserves values. Only name_cleaning accepts null (clear). Steps, schedule and recipient field maps replace their respective values. Source selection additionally requires contacts:read. Published behavior includes copy, schedule, policy, recipients and source selection. Retained steps keep their IDs; new follow-ups omit id. Array order defines the current sequence. Omit a follow-up to remove future mutable work; accepted and uncertain originals remain. Step zero stays first. Recent finished people join new follow-ups only while the new wait is still prospective (at most 30 days since their last accepted touch); completed campaigns still require explicit Resume. Save never launches or buys. Later saves coalesce propagation without erasing originals. Recover the exact original operation_id after a lost response; do not mint another ID.

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`

Request body Required

application/json

CampaignSave

Field	Type and constraints
`operation_id`Required	`string` Min length: `1` · Max length: `128` · Pattern: `"^[A-Za-z0-9][A-Za-z0-9._~-]*$"`
`expected_revision`Required	`integer` Minimum: `1.0`
`name`Optional	`string` \| `null`
`offer`Optional	`string` \| `null`
`audience_prompt`Optional	`string` \| `null`
`steps`Optional	array of `Step` \| `null`
`schedule`Optional	`Window` \| `null`
`daily_limit`Optional	`integer` \| `null` Finite daily allocation; zero stops new campaign outbound work without cancelling queued originals. Omission preserves the current allocation; null is invalid.
`sending_pool`Optional	`"mailbox" \| "transactional" \| "all"` \| `null`
`allow_catch_all`Optional	`boolean` \| `null`
`template_format`Optional	`integer` \| `null`
`name_cleaning`Optional	`NameMapping` \| `null`
`recipients`Optional	array of `RecipientFields` Max items: `25`
`sources`Optional	`SourceSelection` \| `null`

Responses

200 Successful Response

application/json

SaveResult

409 Conflict

application/json

CampaignConflict

422 Validation Error

application/json

GET/campaigns/{cid}/audienceAudience

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`cursor`Optionalquery	`string` Default: `""`
`limit`Optionalquery	`integer` Default: `100` · Minimum: `1` · Maximum: `1000`
`refill`Optionalquery	`string` \| `null`

Responses

200 Successful Response

application/json

CampaignAudiencePage

422 Validation Error

application/json

POST/campaigns/{cid}/contactsAppend Contacts

Required scopes: audiences:write

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`

Request body Required

application/json

ContactsIn

Field	Type and constraints
`operation_id`Optional	`string` \| `null`
`contacts`Required	array of `Contact` Min items: `1` · Max items: `1000`
`expected_revision`Optional	`integer` \| `null`

Responses

200 Successful Response

application/json

Result | AppendCounts

Synthetic keyed append. Recover this same receipt through draft-operations before replay; current contact totals are not this original.

{
  "operation": {
    "id": "append-original",
    "workspace": "workspace",
    "campaign": "campaign",
    "action": "append",
    "request_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "actor": "service:example",
    "expected_revision": 1,
    "before_revision": 1,
    "after_revision": 2,
    "outcome": "recorded",
    "state_after": "draft",
    "counts": {
      "contacts": 2,
      "added": 1,
      "excluded": 0
    },
    "recorded_at": 1791763200
  }
}

Unkeyed append has counts, not an original operation. New clients should use operation_id.

{
  "added": 1,
  "contacts": 2,
  "revision": 2
}

422 Validation Error

application/json

GET/campaigns/{cid}/copy-changes/{identity}Inspect

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

CopyChangeReceipt

422 Validation Error

application/json

GET/campaigns/{cid}/draft-operations/{identity}Original

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

Result

GET /campaigns/empty-draft/draft-operations/create-empty after lost Create response. Matches the original POST receipt, not current Campaign state. Missing original stays unknown; do not generate another operation ID.

{
  "operation": {
    "id": "create-empty",
    "workspace": "workspace",
    "campaign": "empty-draft",
    "action": "create",
    "request_digest": "48a409ab38799ab2dd66fc587789befc87153409b62f0029f32e6224e74928e5",
    "actor": "service:1074c3d56ba74f8c5bc2e4d260925e5fc9ec104cc000848b66289d0897c4942a",
    "expected_revision": null,
    "before_revision": null,
    "after_revision": 1,
    "outcome": "recorded",
    "state_after": "draft",
    "counts": {
      "contacts": 0,
      "added": 0,
      "excluded": 0
    },
    "recorded_at": 1791763200
  }
}

422 Validation Error

application/json

CampaignEligibilityBreakdown

GET/campaigns/{cid}/eligibilityCampaign Eligibility

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`limit`Optionalquery	`integer` Default: `100000` · Minimum: `1` · Maximum: `100000`

Responses

200 Successful Response

application/json

First-email qualification is not sending capacity or confirmed delivery

{
  "observed_at": 1767240000.0,
  "complete": true,
  "inspected": 3,
  "total": 3,
  "counts": {
    "qualified": 1,
    "preparing": 0,
    "waiting": 1,
    "ineligible": 1,
    "contacted": 0,
    "stopped": 0,
    "needs_review": 0
  },
  "reason_counts": {
    "recontact_cooldown": 1,
    "catch_all_not_allowed": 1
  },
  "contacted_total": 0,
  "queued_followups": 0,
  "qualified_upper_bound": 1,
  "recontact_days": 30,
  "semantics": "first_email_qualification_not_send_capacity"
}

422 Validation Error

application/json

POST/campaigns/{cid}/launchLaunch Campaign

Required scopes: campaigns:write spending:write

Conditional scopes

review.source_intake requires contacts:read, contacts:write, audiences:write, data:purchase.

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`

Request body Required

application/json

LaunchIn

Field	Type and constraints
`id`Required	`string` Min length: `1` · Max length: `128`
`review_id`Required	`string` Min length: `1` · Max length: `128`
`capacity_operation`Required	`string` Min length: `1` · Max length: `128`

Responses

200 Successful Response

application/json

LaunchResult

Synthetic original launch receipt; started is not delivery.

{
  "id": "launch-original",
  "campaign": "campaign",
  "state": "started",
  "campaign_revision": 3,
  "capacity_operation": "in_original",
  "send_price_cents": 0,
  "send_budget_cents": 0,
  "commercial_policy_version": "startwave-core-v1",
  "started_at": 1791633600
}

422 Validation Error

application/json

GET/campaigns/{cid}/launches/{identity}Launch Receipt

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

LaunchResult

Recovery returns the same original, not a new launch.

{
  "id": "launch-original",
  "campaign": "campaign",
  "state": "started",
  "campaign_revision": 3,
  "capacity_operation": "in_original",
  "send_price_cents": 0,
  "send_budget_cents": 0,
  "commercial_policy_version": "startwave-core-v1",
  "started_at": 1791633600
}

422 Validation Error

application/json

GET/campaigns/{cid}/materializationStatus

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`

Responses

200 Successful Response

application/json

MaterializationStatus

422 Validation Error

application/json

GET/campaigns/{cid}/name-qualityRead

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`cursor`Optionalquery	`string` Default: `""` · Max length: `128`
`limit`Optionalquery	`integer` Default: `100` · Minimum: `1` · Maximum: `200`
`state`Optionalquery	`"unchecked" \| "ready" \| "pending" \| "held" \| "unavailable"` \| `null`

Responses

200 Successful Response

application/json

Quality

422 Validation Error

application/json

GET/campaigns/{cid}/refillsHistory

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`before`Optionalquery	`integer` Default: `0` · Minimum: `0` · Maximum: `9007199254740991`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

RefillHistory

422 Validation Error

application/json

GET/campaigns/{cid}/refills/{identity}Detail

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`identity`Requiredpath	`string`
`after`Optionalquery	`integer` Default: `0` · Minimum: `0` · Maximum: `1000`
`limit`Optionalquery	`integer` Default: `100` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

RefillResult

Original after response loss; identical to POST, not another append. Invalid row content is absent.

{
  "id": "refill-original",
  "campaign": "campaign",
  "added": 1,
  "duplicates": 1,
  "suppressed": 0,
  "conflicting": 0,
  "invalid": 1,
  "submitted": 3,
  "errors": [
    {
      "index": 2,
      "reason": "invalid_email"
    }
  ],
  "next_error_cursor": null,
  "audience_revision": 2,
  "send_budget_added_cents": 0,
  "send_budget_cents": null,
  "actor": "service:example",
  "created_at": 1791763200
}

422 Validation Error

application/json

POST/campaigns/{cid}/reply-budgetReply Budget

Required scopes: inbox:write spending:write

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`

Request body Required

application/json

ReplyBudgetIn

Owner-authorized reply-only ceiling; never spends or changes cold campaign allowance.

Field	Type and constraints
`id`Required	`string` Min length: `1` · Max length: `128`
`expected_revision`Required	`integer` Minimum: `1.0`
`expected_send_price_cents`Required	`integer` Minimum: `0.0` · Maximum: `1000000.0`
`reply_budget_cents`Required	`integer` Minimum: `0.0` · Maximum: `1000000000.0`

Responses

200 Successful Response

application/json

ReplyBudgetOriginal

422 Validation Error

application/json

GET/campaigns/{cid}/reply-budget-reviewsReply Budget Reviews

Required scopes: inbox:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`cursor`Optionalquery	`string` Default: `""` · Max length: `128`
`limit`Optionalquery	`integer` Default: `100` · Minimum: `1` · Maximum: `100`

Responses

200 Successful Response

application/json

ReplyBudgetPage

422 Validation Error

application/json

GET/campaigns/{cid}/saves/{identity}Original

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

SaveResult

422 Validation Error

application/json

GET/campaigns/{cid}/schedule-changes/{identity}Inspect

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

ScheduleChangeReceipt

422 Validation Error

application/json

GET/campaigns/{cid}/send-events/{event}Inspect Event

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`event`Requiredpath	`integer`

Responses

200 Successful Response

application/json

RecordedSend

422 Validation Error

application/json

GET/campaigns/{cid}/send-plan/{identity}Inspect

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

SendDetail

422 Validation Error

application/json

GET/campaigns/{cid}/send-readinessReadiness

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`cursor`Optionalquery	`string` Default: `""` · Max length: `4096`
`limit`Optionalquery	`integer` Default: `25` · Minimum: `1` · Maximum: `100`

Responses

200 Successful Response

application/json

ReadinessPage

409 Invalid or expired readiness cursor, or unavailable campaign; inspect detail.code

application/json

422 Validation Error

application/json

GET/campaigns/{cid}/source-admission-reviews/by-keyReview By Key

Required scopes: campaigns:read contacts:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`key`Requiredquery	`string` Min length: `8` · Max length: `128`

Responses

200 Successful Response

application/json

AdmissionReview

422 Validation Error

application/json

GET/campaigns/{cid}/source-admission-reviews/{identity}Review Original

Required scopes: campaigns:read contacts:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

AdmissionReview

422 Validation Error

application/json

GET/campaigns/{cid}/source-admissionsHistory

Required scopes: campaigns:read contacts:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`cursor`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` Default: `20` · Minimum: `1` · Maximum: `50`

Responses

200 Successful Response

application/json

AdmissionHistoryPage

422 Validation Error

application/json

POST/campaigns/{cid}/source-admissionsConfirm

Required scopes: audiences:write spending:write contacts:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

AdmissionConfirmIn

Field	Type and constraints
`review_id`Required	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

AdmissionResult

422 Validation Error

application/json

GET/campaigns/{cid}/source-admissions/by-keyResult By Key

Required scopes: campaigns:read contacts:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`key`Requiredquery	`string` Min length: `8` · Max length: `128`

Responses

200 Successful Response

application/json

AdmissionResult

422 Validation Error

application/json

GET/campaigns/{cid}/source-admissions/{identity}Result Original

Required scopes: campaigns:read contacts:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

AdmissionResult

422 Validation Error

application/json

GET/campaigns/{cid}/source-operations/by-keyBy Key

Required scopes: campaigns:read contacts:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`key`Requiredquery	`string` Min length: `8` · Max length: `128`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/campaigns/{cid}/source-operations/{identity}Original

Required scopes: campaigns:read contacts:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/campaigns/{cid}/source-refillsHistory

Required scopes: campaigns:read contacts:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`after`Optionalquery	`string` Default: `""`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

RefillPage

422 Validation Error

application/json

POST/campaigns/{cid}/source-refillsCreate

Required scopes: campaigns:write spending:write audiences:write contacts:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

RefillConsentIn

Field	Type and constraints
`expected_campaign_revision`Required	`integer` Minimum: `1.0`
`expected_sources_revision`Required	`integer` Minimum: `1.0`
`source_ids`Required	array of `string` Min items: `1` · Max items: `50`
`max_people`Required	`integer` Minimum: `1.0` · Maximum: `1000000.0`
`max_memberships`Required	`integer` Minimum: `1.0` · Maximum: `50000000.0`
`expires_at`Required	`number`
`max_send_budget_added_cents`Required	`integer` Minimum: `0.0` · Maximum: `1000000000.0`
`included_preparation`Optional	`IncludedPreparationTerms` \| `null`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/campaigns/{cid}/source-refills/by-keyOriginal

Required scopes: campaigns:read contacts:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`key`Requiredquery	`string` Min length: `8` · Max length: `128`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/campaigns/{cid}/source-refills/{identity}Status

Required scopes: campaigns:read contacts:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

POST/campaigns/{cid}/source-refills/{identity}/cancelCancel

Required scopes: campaigns:write audiences:write contacts:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/campaigns/{cid}/sourcesSources

Required scopes: campaigns:read contacts:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`

Responses

200 Successful Response

application/json

SourceCollection

422 Validation Error

application/json

POST/campaigns/{cid}/sourcesConnect

Required scopes: campaigns:write contacts:read

Conditional scopes

published_campaign requires spending:write.

Connect a List; published campaigns require owner authority and key spending:write. Connections do not authorize intake, purchases or sends. Recover an exact original before repeating a mutation; original reads do not require new-change authority.

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

SourceConnect

Field	Type and constraints
`expected_campaign_revision`Required	`integer` Minimum: `1.0`
`expected_sources_revision`Required	`integer` Minimum: `1.0`
`list_id`Required	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

PATCH/campaigns/{cid}/sources/{identity}Edit

Required scopes: campaigns:write contacts:read

Conditional scopes

published_campaign requires spending:write.

Edit a List connection; published campaigns require owner authority and key spending:write. Draft operators retain connection editing. Existing original-operation reads remain available under their ordinary scopes; this change never launches or broadens consent.

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

SourceEdit

Field	Type and constraints
`expected_campaign_revision`Required	`integer` Minimum: `1.0`
`expected_sources_revision`Required	`integer` Minimum: `1.0`
`expected_revision`Required	`integer` Minimum: `1.0`
`state`Required	`"connected" \| "disconnected"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/campaigns/{cid}/startCurrent Start

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`

Responses

200 Successful Response

application/json

CurrentCampaignStart

422 Validation Error

application/json

POST/campaigns/{cid}/start-reviewStart Review

Required scopes: campaigns:write

Conditional scopes

source_refill requires contacts:read, contacts:write, audiences:write, data:purchase.

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`

Request body Required

application/json

StartReviewIn

Field	Type and constraints
`id`Required	`string` Min length: `1` · Max length: `128`
`expected_revision`Required	`integer` Minimum: `1.0`
`spending_mode`Optional	`"finite" \| "capacity"` Default: `"finite"`
`quote_id`Optional	`string` \| `null`
`capacity_operation`Optional	`string` \| `null`
`source_refill`Optional	`RefillScope` \| `null`

Responses

200 Successful Response

application/json

StartReview

Synthetic funded subscription review; values are observations, not client constants.

{
  "id": "review-original",
  "kind": "start",
  "commercial_policy_version": "startwave-core-v1",
  "spending_mode": "capacity",
  "schedule": {
    "definition": "campaign-pacing-upper-bound-v1",
    "observed_at": 1791633600,
    "local_date": "2026-10-10",
    "timezone": "America/New_York",
    "first_eligible_at": 1791633600,
    "opens_at": 1791604800,
    "closes_at": 1791691200,
    "nominal_gap_seconds": 1920,
    "daily_limit": 45,
    "quota_used": 0,
    "quota_remaining": 45,
    "pacing_slots_upper_bound": 30,
    "completion_guaranteed": false
  },
  "campaign": "campaign",
  "campaign_revision": 2,
  "capacity": {
    "quote_id": null,
    "capacity_operation": "in_original",
    "period_seconds": 2592000,
    "rate_cents_per_block": 3750,
    "rate_version": "subscription-30d-v1",
    "maximum_new_capacity_cents": 0,
    "daily_capacity": 90,
    "expires_at": 1794225540,
    "billing_mode": "subscription-30d-v1",
    "renewal": {
      "revision": 1,
      "enabled": true,
      "recurring_max_cents": 7500
    }
  },
  "audience_revision": 1,
  "remaining_send_count": 4,
  "state": "reviewed",
  "send_price_cents": 0,
  "send_budget_cents": 0,
  "audience_count": 2,
  "sequence_steps": 2,
  "send_committed_cents": 0,
  "reviewed_at": 1791633600,
  "reviewed_by": "service:example"
}

422 Validation Error

application/json

GET/campaigns/{cid}/start-reviewsStart Reviews

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`cursor`Optionalquery	`string` Default: `""` · Max length: `128`
`limit`Optionalquery	`integer` Default: `100` · Minimum: `1` · Maximum: `100`

Responses

200 Successful Response

application/json

StartReviewPage

422 Validation Error

application/json

POST/campaigns/{cid}/stateState

Required scopes: campaigns:write

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`

Request body Required

application/json

CampaignState

Field	Type and constraints
`state`Required	`"active" \| "paused"`

Responses

200 Current Campaign after the requested state change; not an immutable Pause original. Resume requires the reviewed Launch owner under paid configuration.

application/json

CampaignCreated

422 Validation Error

application/json

GET/campaigns/{cid}/summaryRead Campaign Summary

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`

Responses

200 Successful Response

application/json

CampaignSummary

422 Validation Error

application/json

CampaignVerificationPage

GET/campaigns/{cid}/verificationVerification Status

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`cursor`Optionalquery	`string` Default: `""`
`limit`Optionalquery	`integer` Default: `100` · Minimum: `1` · Maximum: `1000`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

CurrentVerificationBatch

GET/campaigns/{cid}/verification/batchesCurrent

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/campaigns/{cid}/windowsCampaign Windows

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`cid`Requiredpath	`string`
`cursor`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` Default: `7` · Minimum: `1` · Maximum: `31`

Responses

200 Successful Response

application/json

CampaignWindowsPage

422 Validation Error

application/json

Capacity15 operations

GET/capacity/currentCurrent Capacity

Required scopes: usage:read

Responses

200 Successful Response

application/json

CurrentCapacity

CapacityExpansionResponse

GET/capacity/expansions/{identity}Status

Required scopes: usage:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

CapacityExpansionResponse

POST/capacity/expansions/{identity}/cancelCancel

Required scopes: campaigns:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

CapacityExpansionResponse

POST/capacity/expansions/{identity}/confirmConfirm

Required scopes: campaigns:write spending:write

New legacy expansion confirmation is retired under subscription billing. An already-submitted original continues its recovery on replay.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/capacity/lease-healthCustomer

Required scopes: usage:read

Parameters

Field	Type and constraints
`operation`Optionalquery	`string` Default: `""` · Max length: `128`
`cursor`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` Default: `25` · Minimum: `1` · Maximum: `50`

Responses

200 Successful Response

application/json

LeaseHealthPage

422 Validation Error

application/json

GET/capacity/limitRead

Required scopes: usage:read

Parameters

Field	Type and constraints
`after`Optionalquery	`string` Default: `""` · Max length: `128`

Responses

200 Successful Response

application/json

AccountLimit

422 Validation Error

application/json

CapacityPage_CapacityOperation_

GET/capacity/operationsCapacity Operations

Required scopes: usage:read

Parameters

Field	Type and constraints
`before`Optionalquery	`string` Default: `""` · Max length: `1024`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

CapacityPage_CapacityExpansionResponse_

GET/capacity/operations/{activation}/expansionsHistory

Required scopes: usage:read

Parameters

Field	Type and constraints
`activation`Requiredpath	`string`
`cursor`Optionalquery	`string` Default: `""` · Max length: `128`
`limit`Optionalquery	`integer` Default: `100` · Minimum: `1` · Maximum: `100`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/capacity/operations/{operation}Capacity Operation

Required scopes: usage:read

Read the original funded term and its recovery state, including retired legacy operations.

Parameters

Field	Type and constraints
`operation`Requiredpath	`string`

Responses

200 Successful Response

application/json

CapacityOperation

422 Validation Error

application/json

CapacityPage_CapacityReactivationResponse_

GET/capacity/operations/{operation}/reactivationsList Reactivations

Required scopes: usage:read

Parameters

Field	Type and constraints
`operation`Requiredpath	`string`
`before`Optionalquery	`string` Default: `""` · Max length: `128`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `100`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

CapacityReactivationResponse

GET/capacity/reactivations/{identity}Get Reactivation

Required scopes: usage:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

CapacityReactivationResponse

POST/capacity/reactivations/{identity}/cancelCancel Reactivation

Required scopes: campaigns:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

CapacityReactivationResponse

POST/capacity/reactivations/{identity}/confirmConfirm Reactivation

Required scopes: campaigns:write spending:write

New legacy confirmation is retired under subscription billing. An already-submitted original continues its recovery on replay.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

CapacityRequestReview | CapacityRequestConfirmation | CapacityRequestIncomplete

GET/capacity/requests/{identity}Read Request

Required scopes: usage:read

Read an immutable legacy review, preparation blocker or original confirmation recovery state.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

CapacityRequestConfirmation

POST/capacity/requests/{identity}/confirmConfirm Request

Required scopes: campaigns:write spending:write

New legacy confirmation is retired under subscription billing. Replay of an already-confirmed original continues its recovery.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Request body

application/json

CapacityConsentIn

Field	Type and constraints
`recurring_consent`Optional	`string` \| `null`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

LookupResult_CompanyPreview_

Companies3 operations

POST/v1/companies/lookupLookup Companies

Required scopes: search:read

Request body Required

application/json

SourceLookup

Field	Type and constraints
`ids`Required	array of `string` Min items: `1` · Max items: `100`
`id_type`Optional	`"source" \| "record"` Default: `"source"`

Responses

200 Successful Response

application/json

429 Workspace discovery or request capacity exhausted; preserve the query and offer explicit retry.

Response headers

Field	Type and constraints
`Retry-After`Optional	`integer` Seconds until retry may be attempted. Minimum: `1.0`

application/json

422 Validation Error

application/json

POST/v1/companies/resolveResolve Companies

Required scopes: search:read

Parameters

Field	Type and constraints
`Idempotency-Key`Optionalheader	`string` \| `null` Required for multiple inputs; preserves the frozen result across retries.

Request body Required

application/json

ResolveRequest

Field	Type and constraints
`inputs`Required	array of `ResolveInput` Min items: `1` · Max items: `100`

Responses

200 Successful Response

application/json

429 Workspace discovery or request capacity exhausted; preserve the query and offer explicit retry.

Response headers

Field	Type and constraints
`Retry-After`Optional	`integer` Seconds until retry may be attempted. Minimum: `1`

application/json

202 Matching continues on the same result set. Repeat the same body and Idempotency-Key to read progress without starting another lookup.

application/json

422 Validation Error

application/json

GET/v1/companies/{identity}Company

Required scopes: search:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Min length: `1` · Max length: `256` · Pattern: `"^[^\\x00-\\x1f\\x7f]+$"`
`id_type`Optionalquery	`"source" \| "record"` Default: `"source"`

Responses

200 Successful Response

application/json

CompanyPreview

429 Workspace discovery or request capacity exhausted; preserve the query and offer explicit retry.

Response headers

Field	Type and constraints
`Retry-After`Optional	`integer` Seconds until retry may be attempted. Minimum: `1`

application/json

422 Validation Error

application/json

Compliance1 operations

GET/complianceRead

Required scopes: campaigns:read

Responses

200 Successful Response

application/json

ComplianceStatus

Contacts10 operations

GET/v1/contactsPeople

Required scopes: contacts:read

Parameters

Field	Type and constraints
`cursor`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`
`state`Optionalquery	`"active" \| "archived"` Default: `"active"`
`name_prefix`Optionalquery	`string` Default: `""` · Max length: `200`
`sort`Optionalquery	`"id" \| "name" \| "updated_at"` Default: `"id"`
`order`Optionalquery	`"asc" \| "desc"` Default: `"asc"`
`ownership`Optionalquery	`"all" \| "net_new" \| "saved"` Default: `"all"`
`list_id`Optionalquery	`string` \| `null`
`data_access`Optionalquery	`"licensed"` \| `null` Only records with a selected licensed snapshot in this workspace; email availability is irrelevant.
`source_freshness`Optionalquery	`"current" \| "update_available" \| "unavailable"` \| `null`
`q`Optionalquery	`string` Literal Unicode-folded substring over permitted saved or selected owned fields. Examines at most 1000 indexed candidates; follow next_cursor even on empty pages. Default: `""` · Max length: `200`
`view`Optionalquery	`"saved" \| "contacts"` Default: `"saved"`
`company_record_id`Optionalquery	`string` \| `null`
`JOB_TITLE`Optionalquery	`string` \| `null`

Responses

200 Successful Response

application/json

Page_PersonView_

422 Validation Error

application/json

POST/v1/contactsCreate Person

Required scopes: contacts:write

Parameters

Field	Type and constraints
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

PersonFields

Field	Type and constraints
`UUID`Optional	`string` \| `null`
`FIRST_NAME`Optional	`string` \| `null`
`LAST_NAME`Optional	`string` \| `null`
`PHOTO_URL`Optional	`string` \| `null`
`COMPANY_NAME`Optional	`string` \| `null`
`JOB_TITLE`Optional	`string` \| `null`
`COMPANY_LOGO_URL`Optional	`string` \| `null`
`PERSONAL_CITY`Optional	`string` \| `null`
`PERSONAL_STATE`Optional	`string` \| `null`
`PERSONAL_COUNTRY`Optional	`string` \| `null`
`COMPANY_DOMAIN`Optional	`string` \| `null`
`MIDDLE_NAME`Optional	`string` \| `null`
`DEPARTMENT`Optional	`string` \| `null`
`SENIORITY_LEVEL`Optional	`string` \| `null`
`HEADLINE`Optional	`string` \| `null`
`SUMMARY`Optional	`string` \| `null`
`SKILLS`Optional	array of `string` \| `null`
`WORK_EXPERIENCE`Optional	array of `WorkExperience` \| `null`
`EDUCATION_HISTORY`Optional	array of `EducationHistory` \| `null`
`POSTS`Optional	array of `object` \| `null`
`CURRENT_BUSINESS_EMAIL`Optional	`string` \| `null`
`CURRENT_BUSINESS_EMAIL_VALIDATION_STATUS`Optional	`string` \| `null`
`CURRENT_BUSINESS_EMAIL_VALIDATION_DATE`Optional	`string` \| `null`
`EMAILS`Optional	`string` \| array of `string` \| `null`
`PHONES`Optional	`string` \| array of `string` \| `null`
`MOBILE_PHONE`Optional	`string` \| `null`
`MOBILE_PHONE_VALIDATION_STATUS`Optional	`string` \| `null`
`LINKEDIN_URL`Optional	`string` \| `null`
`PERSONAL_ADDRESS`Optional	`string` \| `null`
`PERSONAL_ZIP`Optional	`string` \| `null`
`LAST_UPDATED`Optional	`string` \| `null`
`COMPANY_DESCRIPTION`Optional	`string` \| `null`
`COMPANY_INDUSTRY`Optional	`string` \| `null`
`COMPANY_REVENUE_RANGE`Optional	`string` \| `null`
`COMPANY_NUM_EMPLOYEE_RANGE`Optional	`string` \| `null`
`COMPANY_OWNERSHIP`Optional	`string` \| `null`
`COMPANY_LATEST_FUNDING_STAGE`Optional	`string` \| `null`
`COMPANY_LATEST_FUNDING_ROUND_DATE`Optional	`string` \| `null`
`COMPANY_TOTAL_FUNDING`Optional	`integer` \| `number` \| `null`
`COMPANY_STOCK_EXCHANGE`Optional	`string` \| `null`
`COMPANY_TICKER_SYMBOL`Optional	`string` \| `null`
`COMPANY_STOCK_SYMBOL`Optional	`string` \| `null`
`COMPANY_MARKET_CAPITALIZATION`Optional	`integer` \| `number` \| `null`
`COMPANY_TOTAL_REVENUE`Optional	`integer` \| `number` \| `null`
`COMPANY_NUMBER_OF_FOLLOWERS`Optional	`integer` \| `null`
`COMPANY_CITY`Optional	`string` \| `null`
`COMPANY_STATE`Optional	`string` \| `null`
`COMPANY_COUNTRY`Optional	`string` \| `null`
`COMPANY_COUNTRY_NUMERIC`Optional	`string` \| `null`
`COMPANY_ADDRESS`Optional	`string` \| `null`
`COMPANY_ZIP_CODE`Optional	`string` \| `null`
`COMPANY_FOUNDED_YEAR`Optional	`string` \| `null`
`COMPANY_LINKEDIN_URL`Optional	`string` \| `null`
`COMPANY_FACEBOOK_URL`Optional	`string` \| `null`
`COMPANY_TWITTER_URL`Optional	`string` \| `null`
`COMPANY_ANGELLIST_URL`Optional	`string` \| `null`
`COMPANY_TECHNOLOGIES`Optional	`string` \| array of `string` \| `null`
`COMPANY_RETAIL_LOCATION_COUNT`Optional	`integer` \| `null`
`company_record_id`Optional	`string` \| `null` Optional workspace company relationship; never the dataset COMPANY_ID.

Responses

200 Successful Response

application/json

422 Validation Error

application/json

POST/v1/contacts/from-searchSave Person

Required scopes: contacts:write

Parameters

Field	Type and constraints
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

SavePersonSource

Field	Type and constraints
`UUID`Required	`string` Min length: `1` · Max length: `256` · Pattern: `"^[^\\x00-\\x1f\\x7f]+$"`
`target`Optional	`SourceTarget` \| `null` Explicitly attach to this active manual record; never infer a merge from matching contact fields.

Responses

200 Successful Response

application/json

422 Validation Error

application/json

LookupResult_PersonView_

POST/v1/contacts/lookupLookup People

Required scopes: contacts:read

Request body Required

application/json

RecordLookup

Field	Type and constraints
`ids`Required	array of `string` Min items: `1` · Max items: `100`
`id_type`Optional	`"source" \| "record"` Default: `"record"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/contacts/{identity}Person

Required scopes: contacts:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Min length: `1` · Max length: `256` · Pattern: `"^[^\\x00-\\x1f\\x7f]+$"`
`id_type`Optionalquery	`"source" \| "record"` Default: `"record"`

Responses

200 Successful Response

application/json

PersonView

422 Validation Error

application/json

PATCH/v1/contacts/{identity}Edit Person

Required scopes: contacts:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

PersonEdit

Field	Type and constraints
`expected_revision`Required	`integer`
`state`Optional	`"active" \| "archived"` \| `null`
`UUID`Optional	`string` \| `null`
`FIRST_NAME`Optional	`string` \| `null`
`LAST_NAME`Optional	`string` \| `null`
`PHOTO_URL`Optional	`string` \| `null`
`COMPANY_NAME`Optional	`string` \| `null`
`JOB_TITLE`Optional	`string` \| `null`
`COMPANY_LOGO_URL`Optional	`string` \| `null`
`PERSONAL_CITY`Optional	`string` \| `null`
`PERSONAL_STATE`Optional	`string` \| `null`
`PERSONAL_COUNTRY`Optional	`string` \| `null`
`COMPANY_DOMAIN`Optional	`string` \| `null`
`MIDDLE_NAME`Optional	`string` \| `null`
`DEPARTMENT`Optional	`string` \| `null`
`SENIORITY_LEVEL`Optional	`string` \| `null`
`HEADLINE`Optional	`string` \| `null`
`SUMMARY`Optional	`string` \| `null`
`SKILLS`Optional	array of `string` \| `null`
`WORK_EXPERIENCE`Optional	array of `WorkExperience` \| `null`
`EDUCATION_HISTORY`Optional	array of `EducationHistory` \| `null`
`POSTS`Optional	array of `object` \| `null`
`CURRENT_BUSINESS_EMAIL`Optional	`string` \| `null`
`CURRENT_BUSINESS_EMAIL_VALIDATION_STATUS`Optional	`string` \| `null`
`CURRENT_BUSINESS_EMAIL_VALIDATION_DATE`Optional	`string` \| `null`
`EMAILS`Optional	`string` \| array of `string` \| `null`
`PHONES`Optional	`string` \| array of `string` \| `null`
`MOBILE_PHONE`Optional	`string` \| `null`
`MOBILE_PHONE_VALIDATION_STATUS`Optional	`string` \| `null`
`LINKEDIN_URL`Optional	`string` \| `null`
`PERSONAL_ADDRESS`Optional	`string` \| `null`
`PERSONAL_ZIP`Optional	`string` \| `null`
`LAST_UPDATED`Optional	`string` \| `null`
`COMPANY_DESCRIPTION`Optional	`string` \| `null`
`COMPANY_INDUSTRY`Optional	`string` \| `null`
`COMPANY_REVENUE_RANGE`Optional	`string` \| `null`
`COMPANY_NUM_EMPLOYEE_RANGE`Optional	`string` \| `null`
`COMPANY_OWNERSHIP`Optional	`string` \| `null`
`COMPANY_LATEST_FUNDING_STAGE`Optional	`string` \| `null`
`COMPANY_LATEST_FUNDING_ROUND_DATE`Optional	`string` \| `null`
`COMPANY_TOTAL_FUNDING`Optional	`integer` \| `number` \| `null`
`COMPANY_STOCK_EXCHANGE`Optional	`string` \| `null`
`COMPANY_TICKER_SYMBOL`Optional	`string` \| `null`
`COMPANY_STOCK_SYMBOL`Optional	`string` \| `null`
`COMPANY_MARKET_CAPITALIZATION`Optional	`integer` \| `number` \| `null`
`COMPANY_TOTAL_REVENUE`Optional	`integer` \| `number` \| `null`
`COMPANY_NUMBER_OF_FOLLOWERS`Optional	`integer` \| `null`
`COMPANY_CITY`Optional	`string` \| `null`
`COMPANY_STATE`Optional	`string` \| `null`
`COMPANY_COUNTRY`Optional	`string` \| `null`
`COMPANY_COUNTRY_NUMERIC`Optional	`string` \| `null`
`COMPANY_ADDRESS`Optional	`string` \| `null`
`COMPANY_ZIP_CODE`Optional	`string` \| `null`
`COMPANY_FOUNDED_YEAR`Optional	`string` \| `null`
`COMPANY_LINKEDIN_URL`Optional	`string` \| `null`
`COMPANY_FACEBOOK_URL`Optional	`string` \| `null`
`COMPANY_TWITTER_URL`Optional	`string` \| `null`
`COMPANY_ANGELLIST_URL`Optional	`string` \| `null`
`COMPANY_TECHNOLOGIES`Optional	`string` \| array of `string` \| `null`
`COMPANY_RETAIL_LOCATION_COUNT`Optional	`integer` \| `null`
`company_record_id`Optional	`string` \| `null` Optional workspace company relationship; never the dataset COMPANY_ID.
`remove_overrides`Optional	array of "FIRST_NAME" \| "LAST_NAME" \| "PHOTO_URL" \| "COMPANY_NAME" \| "JOB_TITLE" \| "COMPANY_LOGO_URL" \| "PERSONAL_CITY" \| "PERSONAL_STATE" \| "PERSONAL_COUNTRY" \| "COMPANY_DOMAIN" \| "MIDDLE_NAME" \| "DEPARTMENT" \| "SENIORITY_LEVEL" \| "HEADLINE" \| "SUMMARY" \| "SKILLS" \| "WORK_EXPERIENCE" \| "EDUCATION_HISTORY" \| "POSTS" \| "CURRENT_BUSINESS_EMAIL" \| "CURRENT_BUSINESS_EMAIL_VALIDATION_STATUS" \| "CURRENT_BUSINESS_EMAIL_VALIDATION_DATE" \| "EMAILS" \| "PHONES" \| "MOBILE_PHONE" \| "MOBILE_PHONE_VALIDATION_STATUS" \| "LINKEDIN_URL" \| "PERSONAL_ADDRESS" \| "PERSONAL_ZIP" \| "LAST_UPDATED" \| "COMPANY_DESCRIPTION" \| "COMPANY_INDUSTRY" \| "COMPANY_REVENUE_RANGE" \| "COMPANY_NUM_EMPLOYEE_RANGE" \| "COMPANY_OWNERSHIP" \| "COMPANY_LATEST_FUNDING_STAGE" \| "COMPANY_LATEST_FUNDING_ROUND_DATE" \| "COMPANY_TOTAL_FUNDING" \| "COMPANY_STOCK_EXCHANGE" \| "COMPANY_TICKER_SYMBOL" \| "COMPANY_STOCK_SYMBOL" \| "COMPANY_MARKET_CAPITALIZATION" \| "COMPANY_TOTAL_REVENUE" \| "COMPANY_NUMBER_OF_FOLLOWERS" \| "COMPANY_CITY" \| "COMPANY_STATE" \| "COMPANY_COUNTRY" \| "COMPANY_COUNTRY_NUMERIC" \| "COMPANY_ADDRESS" \| "COMPANY_ZIP_CODE" \| "COMPANY_FOUNDED_YEAR" \| "COMPANY_LINKEDIN_URL" \| "COMPANY_FACEBOOK_URL" \| "COMPANY_TWITTER_URL" \| "COMPANY_ANGELLIST_URL" \| "COMPANY_TECHNOLOGIES" \| "COMPANY_RETAIL_LOCATION_COUNT" Remove selected provided overrides and use the selected owned snapshot values. Requires a catalogue-backed licensed record; omission preserves overrides, null still masks a value. No purchase or source refresh. Min items: `1` · Max items: `64`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/contacts/{identity}/campaignsContact Campaigns

Required scopes: contacts:read campaigns:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`cursor`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` At most 50 campaigns with up to 50 connected List memberships each. Default: `50` · Minimum: `1` · Maximum: `50`

Responses

200 Successful Response

application/json

Page_ContactCampaign_

422 Validation Error

application/json

POST/v1/contacts/{identity}/preview-refreshesRefresh Person

Required scopes: contacts:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

PreviewRefresh

Field	Type and constraints
`expected_revision`Required	`integer`
`expected_check_revision`Required	`integer`
`version_id`Required	`string` Pattern: `"^[a-f0-9]{32}$"`
`reset_overrides`Optional	array of "FIRST_NAME" \| "LAST_NAME" \| "MIDDLE_NAME" \| "JOB_TITLE" \| "DEPARTMENT" \| "SENIORITY_LEVEL" \| "HEADLINE" \| "SUMMARY" \| "SKILLS" \| "WORK_EXPERIENCE" \| "EDUCATION_HISTORY" \| "POSTS" \| "CURRENT_BUSINESS_EMAIL" \| "CURRENT_BUSINESS_EMAIL_VALIDATION_STATUS" \| "CURRENT_BUSINESS_EMAIL_VALIDATION_DATE" \| "EMAILS" \| "PHONES" \| "MOBILE_PHONE" \| "MOBILE_PHONE_VALIDATION_STATUS" \| "LINKEDIN_URL" \| "PERSONAL_CITY" \| "PERSONAL_STATE" \| "PERSONAL_COUNTRY" \| "PERSONAL_ADDRESS" \| "PERSONAL_ZIP" \| "LAST_UPDATED" \| "COMPANY_NAME" \| "COMPANY_DOMAIN" \| "COMPANY_DESCRIPTION" \| "COMPANY_INDUSTRY" \| "COMPANY_REVENUE_RANGE" \| "COMPANY_NUM_EMPLOYEE_RANGE" \| "COMPANY_OWNERSHIP" \| "COMPANY_LATEST_FUNDING_STAGE" \| "COMPANY_LATEST_FUNDING_ROUND_DATE" \| "COMPANY_TOTAL_FUNDING" \| "COMPANY_STOCK_EXCHANGE" \| "COMPANY_TICKER_SYMBOL" \| "COMPANY_STOCK_SYMBOL" \| "COMPANY_MARKET_CAPITALIZATION" \| "COMPANY_TOTAL_REVENUE" \| "COMPANY_NUMBER_OF_FOLLOWERS" \| "COMPANY_CITY" \| "COMPANY_STATE" \| "COMPANY_COUNTRY" \| "COMPANY_COUNTRY_NUMERIC" \| "COMPANY_ADDRESS" \| "COMPANY_ZIP_CODE" \| "COMPANY_FOUNDED_YEAR" \| "COMPANY_LINKEDIN_URL" \| "COMPANY_FACEBOOK_URL" \| "COMPANY_TWITTER_URL" \| "COMPANY_ANGELLIST_URL" \| "COMPANY_TECHNOLOGIES" \| "COMPANY_RETAIL_LOCATION_COUNT" \| "COMPANY_ID" \| "COMPANY_LOGO_URL" \| "UUID" \| "PHOTO_URL" Max items: `64`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/contacts/{identity}/source-checksPerson History

Required scopes: contacts:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`after`Optionalquery	`integer` Default: `0` · Minimum: `0` · Maximum: `9007199254740991`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

SourceCheckHistory

422 Validation Error

application/json

POST/v1/contacts/{identity}/source-checksCheck Person

Required scopes: contacts:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

SourceCheck

Field	Type and constraints
`expected_revision`Required	`integer`
`expected_check_revision`Required	`integer`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

Conversations14 operations

GET/conversationsConversations

Required scopes: inbox:read

Parameters

Field	Type and constraints
`before`Optionalquery	`string` Default: `""` · Max length: `2048`
`status`Optionalquery	`"all" \| "needs_reply" \| "waiting" \| "closed" \| "sent" \| "handed_off"` Default: `"all"`
`archive`Optionalquery	`"current" \| "archived" \| "all"` Default: `"current"`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`
`mine`Optionalquery	`boolean` Default: `false`
`unassigned`Optionalquery	`boolean` Default: `false`
`assignee`Optionalquery	`string` \| `null`
`read`Optionalquery	`"all" \| "read" \| "unread"` Default: `"all"`
`q`Optionalquery	`string` Default: `""` · Max length: `100`
`intent`Optionalquery	`"all" \| "needs_review" \| "interested" \| "not_interested" \| "opt_out" \| "out_of_office" \| "automated" \| "recipient_unavailable"` Default: `"all"`
`attention`Optionalquery	`"all" \| "needs_person"` Default: `"all"`

Responses

200 Successful Response

application/json

ConversationPage

Synthetic list page; unread is an integer, next_cursor is nullable and not a total.

{
  "items": [
    {
      "workspace": "one",
      "id": "conversation-example",
      "last_activity": 1791633600,
      "last_inbound_seq": 1,
      "status": "needs_reply",
      "revision": 2,
      "assignee": null,
      "archived": 0,
      "has_sent": 0,
      "email": "one@example.test",
      "campaign": "campaign-one",
      "campaign_name": "campaign-one",
      "unread": 1,
      "attention_seq": 1,
      "handoff": null,
      "inbox": {
        "workflow": "needs_reply",
        "reply_delivery": "none",
        "intent": "needs_review"
      }
    }
  ],
  "next_cursor": null
}

422 Validation Error

application/json

GET/conversations/{identity}Detail

Required scopes: inbox:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`
`before`Optionalquery	`integer` Default: `0` · Minimum: `0` · Maximum: `9007199254740991`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

ConversationDetail

Synthetic inbound-only detail; optional source/classification fields are omitted when absent.

{
  "conversation": {
    "workspace": "one",
    "id": "conversation-example",
    "last_activity": 1791633600,
    "last_inbound_seq": 1,
    "status": "needs_reply",
    "revision": 2,
    "assignee": null,
    "archived": 0,
    "has_sent": 0,
    "email": "one@example.test",
    "campaign": "campaign-one",
    "attention_seq": 1,
    "handoff": null,
    "inbox": {
      "workflow": "needs_reply",
      "reply_delivery": "none",
      "intent": "needs_review"
    },
    "unread": 1
  },
  "followups": {
    "state": "inactive",
    "next_eligible_at": null,
    "step": null,
    "stop_id": null,
    "stopped_at": null,
    "can_stop": false
  },
  "read_by": [],
  "read_by_more": false,
  "items": [
    {
      "seq": 1,
      "direction": "in",
      "authorship": "external",
      "occurred_at": 1791633600,
      "event_id": "one-a",
      "message_id": "<one@example.test>",
      "kind": "reply",
      "content": "Thanks",
      "intent": "needs_review",
      "revision": 1,
      "delivery_action": null,
      "delivery_status": null,
      "delivery_confidence": null,
      "participants": null
    }
  ],
  "next_cursor": null
}

Synthetic unresolved outbound reply; retain the original job, never resubmit it under a new ID.

{
  "conversation": {
    "workspace": "one",
    "id": "conversation-example",
    "last_activity": 1791633600,
    "last_inbound_seq": 1,
    "status": "needs_reply",
    "revision": 2,
    "assignee": null,
    "archived": 0,
    "has_sent": 0,
    "email": "one@example.test",
    "campaign": "campaign-one",
    "attention_seq": 1,
    "handoff": null,
    "inbox": {
      "workflow": "needs_reply",
      "reply_delivery": "unconfirmed",
      "intent": "needs_review"
    },
    "unread": 1
  },
  "followups": {
    "state": "inactive",
    "next_eligible_at": null,
    "step": null,
    "stop_id": null,
    "stopped_at": null,
    "can_stop": false
  },
  "read_by": [],
  "read_by_more": false,
  "items": [
    {
      "seq": 2,
      "direction": "out",
      "authorship": "human",
      "occurred_at": 1791633600,
      "job_id": "reply-original",
      "submitted_by": "service",
      "message_id": "<reply@example.test>",
      "state": "unknown",
      "error": "",
      "subject": "Re: Hello",
      "content": "Thanks for your reply.",
      "has_html": false,
      "attachments": []
    },
    {
      "seq": 1,
      "direction": "in",
      "authorship": "external",
      "occurred_at": 1791633600,
      "event_id": "one-a",
      "message_id": "<one@example.test>",
      "kind": "reply",
      "content": "Thanks",
      "intent": "needs_review",
      "revision": 1,
      "delivery_action": null,
      "delivery_status": null,
      "delivery_confidence": null,
      "participants": null
    }
  ],
  "next_cursor": null
}

422 Validation Error

application/json

PATCH/conversations/{identity}/archiveConversation

Required scopes: inbox:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Request body Required

application/json

ArchiveIn

Field	Type and constraints
`id`Required	`string` Min length: `1` · Max length: `128`
`expected_revision`Required	`integer` Minimum: `1.0`
`archived`Required	`boolean`

Responses

200 Successful Response

application/json

ConversationArchive

422 Validation Error

application/json

ConversationHistory_ConversationArchive_

GET/conversations/{identity}/archive-historyConversation History

Required scopes: inbox:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`
`before`Optionalquery	`integer` Default: `0` · Minimum: `0` · Maximum: `9007199254740991`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

PATCH/conversations/{identity}/assignmentAssign

Required scopes: inbox:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Request body Required

application/json

AssignmentIn

Field	Type and constraints
`id`Required	`string` Min length: `1` · Max length: `128`
`expected_revision`Required	`integer` Minimum: `1.0`
`assignee`Required	`string` \| `null`

Responses

200 Successful Response

application/json

ConversationAssignment

422 Validation Error

application/json

ConversationHistory_ConversationAssignment_

GET/conversations/{identity}/assignmentsHistory

Required scopes: inbox:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`
`before`Optionalquery	`integer` Default: `0` · Minimum: `0` · Maximum: `9007199254740991`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

ConversationHistory_ConversationChange_

GET/conversations/{identity}/changesChanges

Required scopes: inbox:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`
`before`Optionalquery	`integer` Default: `0` · Minimum: `0` · Maximum: `9007199254740991`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

ConversationDoNotContact

POST/conversations/{identity}/do-not-contactDo Not Contact

Required scopes: inbox:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Request body Required

application/json

DoNotContactIn

Field	Type and constraints
`id`Required	`string` Min length: `1` · Max length: `128`
`expected_revision`Required	`integer` Minimum: `1.0`
`event_id`Required	`string` Min length: `1` · Max length: `256`
`expected_reply_revision`Required	`integer` Minimum: `1.0`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/conversations/{identity}/messages/{event}/attachments/{part}Attachment Download

Required scopes: inbox:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`
`event`Requiredpath	`string`
`part`Requiredpath	`integer` Minimum: `0` · Maximum: `200`

Responses

200 Successful Response

application/octet-stream

string

422 Validation Error

application/json

ConversationHistory_ConversationNote_

GET/conversations/{identity}/notesNotes

Required scopes: inbox:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`
`before`Optionalquery	`integer` Default: `0` · Minimum: `0` · Maximum: `9007199254740991`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

POST/conversations/{identity}/notesAdd Note

Required scopes: inbox:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Request body Required

application/json

NoteIn

Field	Type and constraints
`id`Required	`string` Min length: `1` · Max length: `128`
`expected_revision`Required	`integer` Minimum: `1.0`
`body`Required	`string` Min length: `1` · Max length: `10000` · Pattern: `"\\S"`

Responses

200 Successful Response

application/json

ConversationNote

422 Validation Error

application/json

POST/conversations/{identity}/readRead

Required scopes: inbox:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Request body Required

application/json

ReadIn

Field	Type and constraints
`through_seq`Required	`integer` Minimum: `0.0`
`unread`Optional	`boolean` Default: `false`

Responses

200 Successful Response

application/json

ConversationRead

422 Validation Error

application/json

PATCH/conversations/{identity}/statusStatus

Required scopes: inbox:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Request body Required

application/json

StatusIn

Field	Type and constraints
`id`Required	`string` Min length: `1` · Max length: `128`
`expected_revision`Required	`integer` Minimum: `1.0`
`status`Required	`"closed" \| "needs_reply"`

Responses

200 Successful Response

application/json

ConversationChange

422 Validation Error

application/json

POST/conversations/{identity}/stop-followupsStop Followups

Required scopes: inbox:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Request body Required

application/json

StopFollowupsIn

Field	Type and constraints
`id`Required	`string` Min length: `1` · Max length: `128`
`expected_revision`Required	`integer` Minimum: `1.0`

Responses

200 Successful Response

application/json

ConversationStop

422 Validation Error

application/json

Data capabilities1 operations

GET/v1/data-capabilitiesCapabilities

Required scopes: contacts:read

Responses

200 Successful Response

application/json

DataCapabilities

Data job capabilities1 operations

GET/v1/data-job-capabilitiesCapabilities

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:read.

suppressions requires suppressions:read.

Responses

200 Successful Response

application/json

JobCapabilities

Data jobs12 operations

GET/v1/data-jobsHistory

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:read.

suppressions requires suppressions:read.

Parameters

Field	Type and constraints
`cursor`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`
`sort`Optionalquery	`"created_at" \| "state" \| "amount_minor"` Default: `"created_at"`
`order`Optionalquery	`"asc" \| "desc"` Default: `"desc"`
`category`Optionalquery	`"contacts" \| "suppressions"` Default: `"contacts"`
`import_id`Optionalquery	`string` \| `null`
`campaign_id`Optionalquery	`string` \| `null`

Responses

200 Successful Response

application/json

Page_JobView_

422 Validation Error

application/json

POST/v1/data-jobsCreate

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:write.

suppressions requires suppressions:write.

export requires contacts:read.

export_suppressions requires suppressions:read.

export_campaign requires contacts:read, campaigns:read.

Conditional scopes

scope requires contacts:read.

scope.resource=people|companies requires search:read.

kind=unlock|refresh requires search:read, data:purchase, spending:write.

kind=export requires contacts:read.

kind=export_suppressions requires suppressions:read.

kind=export_campaign requires contacts:read, campaigns:read.

kind=export,input.kind=identifiers requires search:read.

kind=export,export.version_mode!=owned_only requires search:read, data:purchase, spending:write.

kind=campaign_admission requires campaigns:write, contacts:read, audiences:write, spending:write.

Parameters

Field	Type and constraints
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

JobRequest

Field	Type and constraints
`kind`Required	`"import_records" \| "list_membership" \| "unlock" \| "refresh" \| "export" \| "suppressions" \| "contact_history" \| "export_suppressions" \| "export_campaign" \| "campaign_admission"`
`import_id`Optional	`string` \| `null`
`expected_digest`Optional	`string` \| `null`
`scope`Optional	`JobIdsScope` \| `JobListScope` \| `JobQueryScope-Input` \| `JobRecordsScope` \| `null`
`max_records`Required	`integer` Minimum: `1.0` · Maximum: `5000000.0`
`prepare`Optional	`boolean` Prepare a native scoped action without spending or producing an artifact. Explicit confirmation is required before execution. Default: `false`
`list_id`Optional	`string` \| `null`
`expected_membership_revision`Optional	`integer` \| `null`
`action`Optional	`"add" \| "remove"` Default: `"add"`
`purchase`Optional	`OrderTerms` \| `null`
`export`Optional	`JobExport` \| `null`
`review`Optional	`null`
`delivery`Optional	`null`
`campaign`Optional	`CampaignAdmissionTarget` \| `null`
`exclusions`Optional	`SuppressionExport` \| `null`
`recipients`Optional	`CampaignExport` \| `null`

Responses

200 Original job is no longer queued or awaiting action.

Response headers

Field	Type and constraints
`Location`Optional	`string` Relative URI of the original data job.

application/json

202 Original job is queued or awaiting action. Read it for progress.

Response headers

Field	Type and constraints
`Location`Optional	`string` Relative URI of the original data job.

application/json

Synthetic accepted original with Location /v1/data-jobs/11111111111111111111111111111111. Recover by the same Idempotency-Key through /v1/data-jobs/by-key; read progress rather than submit another job. Staging and submission do not purchase or send.

{
  "id": "11111111111111111111111111111111",
  "parameters": {
    "kind": "import_records",
    "import_id": "22222222222222222222222222222222",
    "expected_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "max_records": 1
  },
  "entity_type": "person",
  "state": "queued",
  "revision": 1,
  "counts": {
    "processed": 0,
    "created": 0,
    "added": 0,
    "removed": 0,
    "unchanged": 0,
    "invalid": 0,
    "newly_granted": 0,
    "already_owned": 0,
    "excluded": 0,
    "checked": 0,
    "changed": 0,
    "missing": 0
  },
  "total_rows": 1,
  "target_revision": null,
  "reason": null,
  "created_at": "2026-10-12T00:00:00Z",
  "updated_at": "2026-10-12T00:00:00Z",
  "expires_at": "2026-10-19T00:00:00Z",
  "completed_at": null,
  "policy": null,
  "amount_minor": 0,
  "funding_required_minor": 0,
  "pending_order_id": null
}

422 Validation Error

application/json

GET/v1/data-jobs/by-keyBy Key

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:read.

suppressions requires suppressions:read.

Parameters

Field	Type and constraints
`key`Requiredquery	`string` Min length: `8` · Max length: `128`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/data-jobs/{identity}Original

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:read.

suppressions requires suppressions:read.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/data-jobs/{identity}/artifactArtifact

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:read.

suppressions requires suppressions:read.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

JobArtifact

422 Validation Error

application/json

POST/v1/data-jobs/{identity}/cancelCancel

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:write.

suppressions requires suppressions:write.

export requires contacts:read.

export_suppressions requires suppressions:read.

export_campaign requires contacts:read, campaigns:read.

Conditional scopes

job.scope requires contacts:read.

job.scope.resource=people|companies requires search:read.

job.kind=unlock|refresh requires search:read, data:purchase, spending:write.

job.kind=export requires contacts:read.

job.kind=export_suppressions requires suppressions:read.

job.kind=export_campaign requires contacts:read, campaigns:read.

job.kind=export,input.kind=identifiers requires search:read.

job.kind=export,job.export.version_mode!=owned_only requires search:read, data:purchase, spending:write.

job.kind=campaign_admission requires campaigns:write, contacts:read, audiences:write, spending:write.

job.kind=source_check requires search:read.

job.kind=export_review|review_delivery requires contacts:read.

job.kind=review_delivery,billable_units>0 requires data:purchase, spending:write.

job.kind=review_delivery,billable_source_records requires search:read.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

POST/v1/data-jobs/{identity}/confirmConfirm

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:write.

suppressions requires suppressions:write.

export requires contacts:read.

export_suppressions requires suppressions:read.

export_campaign requires contacts:read, campaigns:read.

Conditional scopes

job.scope requires contacts:read.

job.scope.resource=people|companies requires search:read.

job.purchase requires search:read, data:purchase, spending:write.

destination!=null requires contacts:write.

job.kind=export requires contacts:read.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

JobConfirm

Field	Type and constraints
`expected_revision`Required	`integer` Minimum: `1.0`
`quote_revision`Required	`integer` Minimum: `1.0`
`currency`Required	`"usd"`
`max_amount_minor`Required	`integer` Minimum: `0.0` · Maximum: `10000000.0`
`destination`Optional	`JobExistingList` \| `JobNewList` \| `null`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/data-jobs/{identity}/deliveryDelivery

Required scopes: contacts:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`after`Optionalquery	`integer` Default: `0` · Minimum: `0` · Maximum: `5000000`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `100`

Responses

200 Successful Response

application/json

ReviewDeliveryPage

422 Validation Error

application/json

GET/v1/data-jobs/{identity}/downloadDownload

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:read.

suppressions requires suppressions:read.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`session_binding`Optionalquery	`string` \| `null`
`sha256`Optionalquery	`string` \| `null`

Responses

200 Successful Response

text/csv

string

application/json

string

application/x-ndjson

string

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

string

422 Validation Error

application/json

HEAD/v1/data-jobs/{identity}/downloadDownload

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:read.

suppressions requires suppressions:read.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`session_binding`Optionalquery	`string` \| `null`
`sha256`Optionalquery	`string` \| `null`

Responses

200 Successful Response

422 Validation Error

application/json

GET/v1/data-jobs/{identity}/resultsResults

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:read.

suppressions requires suppressions:read.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`after`Optionalquery	`integer` Default: `0` · Minimum: `0` · Maximum: `5000000`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

JobResults

Synthetic committed suppression prefix. Recover each immutable receipt through /suppressions/operations/{suppression_operation_id}; duplicates cost zero and do not repeat audience cancellation. Job state owns remaining progress.

{
  "items": [
    {
      "ordinal": 1,
      "key": "customer-one",
      "record_id": null,
      "outcome": "added",
      "reason": null,
      "suppression_operation_id": "import-11111111111111111111111111111111-1",
      "amount_minor": 0
    },
    {
      "ordinal": 2,
      "key": "duplicate",
      "record_id": null,
      "outcome": "unchanged",
      "reason": null,
      "suppression_operation_id": "import-11111111111111111111111111111111-2",
      "amount_minor": 0
    },
    {
      "ordinal": 3,
      "key": "bad-target",
      "record_id": null,
      "outcome": "invalid",
      "reason": "invalid_suppressions",
      "suppression_operation_id": null,
      "amount_minor": 0
    }
  ],
  "next_after": null
}

410 Per-row results expired; job totals and original purchase receipts remain available.

422 Validation Error

application/json

POST/v1/data-jobs/{identity}/resumeResume

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:write.

suppressions requires suppressions:write.

export requires contacts:read.

export_suppressions requires suppressions:read.

export_campaign requires contacts:read, campaigns:read.

Conditional scopes

job.scope requires contacts:read.

job.scope.resource=people|companies requires search:read.

job.kind=unlock|refresh requires search:read, data:purchase, spending:write.

job.kind=export requires contacts:read.

job.kind=export_suppressions requires suppressions:read.

job.kind=export_campaign requires contacts:read, campaigns:read.

job.kind=export,input.kind=identifiers requires search:read.

job.kind=export,job.export.version_mode!=owned_only requires search:read, data:purchase, spending:write.

job.kind=campaign_admission requires campaigns:write, contacts:read, audiences:write, spending:write.

job.kind=source_check requires search:read.

job.kind=review_delivery requires contacts:read.

job.kind=review_delivery,billable_units>0 requires data:purchase, spending:write.

job.kind=review_delivery,billable_source_records requires search:read.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

JobResume

Field	Type and constraints
`expected_revision`Required	`integer` Minimum: `1.0`
`expected_membership_revision`Optional	`integer` \| `null`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

Data orders11 operations

GET/v1/data-ordersHistory

Required scopes: contacts:read

Parameters

Field	Type and constraints
`cursor`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`
`sort`Optionalquery	`"created_at" \| "state" \| "amount_minor"` Default: `"created_at"`
`order`Optionalquery	`"asc" \| "desc"` Default: `"desc"`

Responses

200 Successful Response

application/json

Page_OrderSummary_

422 Validation Error

application/json

POST/v1/data-ordersPurchase

Required scopes: data:purchase spending:write

SourceUnlock accepts a source ID without a saved record or review. It additionally requires search:read and contacts:write. Its Idempotency-Key is optional; owned reuse is free and never refreshes. IdentifierUnlock accepts up to100 keyed exact identifiers in one request, requires the same scopes and Idempotency-Key, and also reuses selected ownership without refreshing. RecordRefresh explicitly updates an owned contact/account with its expected revision and requires the same scopes plus Idempotency-Key. Equivalent licensed content is free.

Parameters

Field	Type and constraints
`Idempotency-Key`Optionalheader	`string` \| `null`

Request body Required

application/json

SourceUnlock | IdentifierUnlock | RecordRefresh

Responses

200 Original order no longer awaiting funds.

Response headers

Field	Type and constraints
`Location`Optional	`string` Relative URI of the original data order.

application/json

OrderView

202 Original order awaits data funds and deliberate continuation. Reading it does not resume it.

Response headers

Field	Type and constraints
`Location`Optional	`string` Relative URI of the original data order.

application/json

OrderView

Synthetic original awaiting data funds; GET does not resume it. Prices are examples, not client constants.

{
  "id": "order-example",
  "state": "awaiting_funds",
  "policy": {
    "id": "fixture-person",
    "entity_type": "person",
    "currency": "usd",
    "unit_amount_minor": 2
  },
  "currency": "usd",
  "max_amount_minor": 100,
  "amount_minor": 0,
  "funding_required_minor": 2,
  "items": [],
  "matches": null,
  "created_at": "2026-10-11T00:00:00.000000Z",
  "completed_at": null,
  "automatic_funding": true,
  "funding_error": ""
}

Synthetic matched person awaiting data funds; no licensed fields disclosed and no automatic continuation.

{
  "id": "order-example",
  "state": "awaiting_funds",
  "policy": {
    "id": "fixture-person",
    "entity_type": "person",
    "currency": "usd",
    "unit_amount_minor": 2
  },
  "currency": "usd",
  "max_amount_minor": 100,
  "amount_minor": 0,
  "funding_required_minor": 2,
  "items": [],
  "matches": null,
  "created_at": "2026-10-11T00:00:00.000000Z",
  "completed_at": null,
  "automatic_funding": true,
  "funding_error": ""
}

Synthetic matched company awaiting data funds; fixture price is illustrative, not a server constant.

{
  "id": "order-example",
  "state": "awaiting_funds",
  "policy": {
    "id": "fixture-company",
    "entity_type": "company",
    "currency": "usd",
    "unit_amount_minor": 1
  },
  "currency": "usd",
  "max_amount_minor": 100,
  "amount_minor": 0,
  "funding_required_minor": 1,
  "items": [],
  "matches": null,
  "created_at": "2026-10-11T00:00:00.000000Z",
  "completed_at": null,
  "automatic_funding": true,
  "funding_error": ""
}

429 New unfunded purchase exceeds pending-order capacity. No new order or debit is committed; fund, resume or cancel original purchases before retrying. Funded work and original recovery remain available.

Response headers

Field	Type and constraints
`Retry-After`Optional	`integer` Seconds before retrying admission.

422 Validation Error

application/json

GET/v1/data-orders/by-keyBy Key

Required scopes: contacts:read

Parameters

Field	Type and constraints
`key`Requiredquery	`string` Min length: `8` · Max length: `128`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

ReviewView | PreparingReview

GET/v1/data-orders/reviews/by-keyBy Key

Required scopes: contacts:read

Parameters

Field	Type and constraints
`key`Requiredquery	`string` Min length: `8` · Max length: `128`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

ReviewView | PreparingReview

GET/v1/data-orders/reviews/{identity}Original

Required scopes: contacts:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

ReviewView | PreparingReview

POST/v1/data-orders/reviews/{identity}/cancelCancel

Required scopes: contacts:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

POST/v1/data-orders/reviews/{identity}/confirmConfirm

Required scopes: contacts:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

ReviewConfirm

Field	Type and constraints
`expected_revision`Required	`integer` Minimum: `1.0`
`expected_digest`Required	`string` Pattern: `"^[a-f0-9]{64}$"`
`delivery`Optional	`"json" \| "csv" \| "json_job" \| "csv_job"` Default: `"json"`
`currency`Optional	`"usd"` Default: `"usd"`
`max_amount_minor`Optional	`integer` Default: `0` · Minimum: `0.0` · Maximum: `10000000.0`

Responses

200 Original order or job result.

Response headers

Field	Type and constraints
`Location`Optional	`string` Relative URI of the original data order or data job, according to delivery mode.

application/json

ReviewDelivery | ReviewPurchase | JobView

202 Original awaits funds, queued work or explicit action.

Response headers

Field	Type and constraints
`Location`Optional	`string` Relative URI of the original data order or data job, according to delivery mode.

application/json

ReviewPurchase | JobView

429 New unfunded purchase exceeds pending-order capacity; no new purchase is committed. Existing purchase recovery remains available.

Response headers

Field	Type and constraints
`Retry-After`Optional	`integer` Seconds before retrying admission.

422 Validation Error

application/json

GET/v1/data-orders/{identity}Original

Required scopes: contacts:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

POST/v1/data-orders/{identity}/cancelCancel

Required scopes: data:purchase spending:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/data-orders/{identity}/downloadDownload

Required scopes: contacts:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

text/csv

string

application/json

string

application/x-ndjson

string

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

string

422 Validation Error

application/json

POST/v1/data-orders/{identity}/resumeResume

Required scopes: data:purchase spending:write

Deliberately settle the original authorized purchase using its frozen inputs, policy and spending ceiling. No request body or new purchase key is needed; repeating a terminal order returns its original receipt. Does not fetch source data or charge a payment card. Source unlock, refresh and enrichment originals additionally require search:read and contacts:write; review originals require contacts:read. Job-owned orders must resume through their revision-checked job instead.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Original order no longer awaiting funds.

Response headers

Field	Type and constraints
`Location`Optional	`string` Relative URI of the original data order.

application/json

OrderView | ReviewPurchase

202 Original order awaits data funds and deliberate continuation. Reading it does not resume it.

Response headers

Field	Type and constraints
`Location`Optional	`string` Relative URI of the original data order.

application/json

Response headers

Field	Type and constraints
`Retry-After`Optional	`integer` Seconds before retrying admission.

422 Validation Error

application/json

Import capabilities1 operations

GET/v1/import-capabilitiesCapabilities

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:read.

suppressions requires suppressions:read.

Responses

200 Successful Response

application/json

ImportCapabilities

Imports9 operations

GET/v1/importsHistory

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:read.

suppressions requires suppressions:read.

Parameters

Field	Type and constraints
`cursor`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`
`sort`Optionalquery	`"created_at" \| "state"` Default: `"created_at"`
`order`Optionalquery	`"asc" \| "desc"` Default: `"desc"`
`category`Optionalquery	`"contacts" \| "suppressions"` Default: `"contacts"`

Responses

200 Successful Response

application/json

Page_ImportView_

422 Validation Error

application/json

POST/v1/importsCreate

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:write.

suppressions requires suppressions:write.

Parameters

Field	Type and constraints
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

ImportCreate

Field	Type and constraints
`entity_type`Optional	`"person" \| "company"` \| `null`
`kind`Required	`"records" \| "identifiers" \| "ids" \| "suppressions" \| "contact_history"`
`defaults`Optional	`SuppressionDefaults` \| `null`
`history_source`Optional	`string` \| `null` Optional immutable source label for contact-history rows without their own source column.
`format`Optional	`"ndjson" \| "csv"` Default: `"ndjson"`
`columns`Optional	`object`
`max_rows`Required	`integer` Minimum: `1.0` · Maximum: `5000000.0`
`max_bytes`Required	`integer` Minimum: `1.0` · Maximum: `8589934592.0`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/imports/by-keyBy Key

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:read.

suppressions requires suppressions:read.

Parameters

Field	Type and constraints
`key`Requiredquery	`string` Min length: `8` · Max length: `128`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/imports/{identity}Original

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:read.

suppressions requires suppressions:read.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

POST/v1/imports/{identity}/cancelCancel

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:write.

suppressions requires suppressions:write.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/imports/{identity}/chunks/{position}Chunk

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:read.

suppressions requires suppressions:read.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`position`Requiredpath	`integer` Minimum: `0`

Responses

200 Successful Response

application/json

ChunkView

422 Validation Error

application/json

PUT/v1/imports/{identity}/chunks/{position}Upload

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:write.

suppressions requires suppressions:write.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`position`Requiredpath	`integer` Minimum: `0`

Request body Required

text/csv

string

application/x-ndjson

string

Responses

200 Successful Response

application/json

ChunkView

422 Validation Error

application/json

GET/v1/imports/{identity}/rowsRows

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:read.

suppressions requires suppressions:read.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`after`Optionalquery	`integer` Default: `0` · Minimum: `0` · Maximum: `5000000`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

ImportRows

422 Validation Error

application/json

POST/v1/imports/{identity}/sealSeal

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:write.

suppressions requires suppressions:write.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Request body Required

application/json

ImportSeal

Field	Type and constraints
`expected_chunks`Required	`integer` Minimum: `1.0` · Maximum: `50000.0`
`expected_rows`Required	`integer` Minimum: `1.0` · Maximum: `5000000.0`
`expected_digest`Required	`string` Pattern: `"^[a-f0-9]{64}$"`
`allow_invalid_rows`Optional	`boolean` Default: `false`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

Inbox3 operations

GET/inboxInbox

Required scopes: inbox:read

Parameters

Field	Type and constraints
`limit`Optionalquery	`integer` Default: `100` · Minimum: `1` · Maximum: `1000`
`cursor`Optionalquery	`string` Default: `""`

Responses

200 Successful Response

application/json

InboxPage

422 Validation Error

application/json

GET/inbox/reviewReply Review Queue

Required scopes: inbox:read

Page recorded reply intents without making mutable intent part of the ordering key.

Parameters

Field	Type and constraints
`before`Optionalquery	`string` Default: `""` · Max length: `2048`
`intent`Optionalquery	`"all" \| "needs_review" \| "interested" \| "not_interested" \| "opt_out" \| "out_of_office" \| "automated" \| "recipient_unavailable"` Default: `"needs_review"`
`archive`Optionalquery	`"current" \| "archived" \| "all"` Default: `"current"`
`pending`Optionalquery	`boolean` Default: `false`
`read`Optionalquery	`"all" \| "read" \| "unread"` Default: `"all"`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

ReplyReviewQueue

Synthetic intent review with unavailable classifier evidence; not an empty or successful classification.

{
  "items": [
    {
      "event_id": "one-a",
      "intent": "needs_review",
      "revision": 1,
      "received_at": 1791633600,
      "conversation": "conversation-example",
      "status": "needs_reply",
      "conversation_revision": 2,
      "last_inbound_seq": 1,
      "attention_seq": 1,
      "archived": 0,
      "unread": 1,
      "email": "one@example.test",
      "campaign": "campaign-one",
      "campaign_name": "campaign-one",
      "classifier_state": null,
      "suggestion": null,
      "choice_confidence": null,
      "explicit_opt_out": null,
      "classifier_error": null,
      "classifier_updated_at": null,
      "classifier_origin": null,
      "reason": null,
      "probabilities": null
    }
  ],
  "next_cursor": null,
  "review_revision": 1
}

422 Validation Error

application/json

PATCH/inbox/{event_id}/intentReply Intent

Required scopes: inbox:write

Parameters

Field	Type and constraints
`event_id`Requiredpath	`string`

Request body Required

application/json

ReplyIntentIn

Field	Type and constraints
`intent`Required	`"needs_review" \| "interested" \| "not_interested" \| "opt_out" \| "out_of_office" \| "automated" \| "recipient_unavailable"`
`expected_revision`Required	`integer` Minimum: `1.0`

Responses

200 Successful Response

application/json

IntentResult

422 Validation Error

application/json

Jobs1 operations

GET/jobs/{jid}/retriesHistory

Required scopes: inbox:read

Parameters

Field	Type and constraints
`jid`Requiredpath	`string`
`after`Optionalquery	`string` Default: `""`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

RetryPage

422 Validation Error

application/json

Ledger1 operations

GET/ledgerLedger

Required scopes: usage:read

Parameters

Field	Type and constraints
`limit`Optionalquery	`integer` Default: `100` · Minimum: `1` · Maximum: `1000`
`cursor`Optionalquery	`string` Default: `""`

Responses

200 Historical sending-wallet entries, not subscription invoices or the contact data balance. Use /billing/history for bounded date-filtered reads.

application/json

LedgerPage

422 Validation Error

application/json

Lists10 operations

GET/v1/listsLists

Required scopes: contacts:read

Parameters

Field	Type and constraints
`cursor`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`
`state`Optionalquery	`"active" \| "archived" \| "all"` Default: `"active"`
`name_prefix`Optionalquery	`string` Default: `""` · Max length: `200`
`sort`Optionalquery	`"id" \| "name" \| "updated_at"` Default: `"id"`
`order`Optionalquery	`"asc" \| "desc"` Default: `"asc"`
`entity_type`Optionalquery	`"person" \| "company"` \| `null`
`q`Optionalquery	`string` Literal Unicode-folded substring of the List name. Examines at most 1000 indexed candidates; follow next_cursor even on empty pages. Default: `""` · Max length: `200`
`record_id`Optionalquery	`string` \| `null` Lists containing this workspace record; requires entity_type and ID sort. Sparse state filters may return an empty page with a cursor.

Responses

200 Successful Response

application/json

Page_ListView_

422 Validation Error

application/json

POST/v1/listsCreate List

Required scopes: contacts:write

Parameters

Field	Type and constraints
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

ListCreate

Field	Type and constraints
`name`Required	`string` Min length: `1` · Max length: `200`
`entity_type`Required	`"person" \| "company"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/lists/{identity}Listing

Required scopes: contacts:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

ListView

422 Validation Error

application/json

PATCH/v1/lists/{identity}Edit List

Required scopes: contacts:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

ListEdit

Field	Type and constraints
`expected_revision`Required	`integer`
`state`Optional	`"active" \| "archived"` \| `null`
`name`Optional	`string` \| `null`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/lists/{identity}/campaignsListing Campaigns

Required scopes: contacts:read campaigns:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`cursor`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

Page_ListCampaign_

422 Validation Error

application/json

Page_Union_PersonView__CompanyView__

GET/v1/lists/{identity}/membersMembers

Required scopes: contacts:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`cursor`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

POST/v1/lists/{identity}/membership-changesChange Members

Required scopes: contacts:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

MembershipChange

Field	Type and constraints
`expected_membership_revision`Required	`integer`
`action`Required	`"add" \| "remove"`
`ids`Required	array of `string` Min items: `1` · Max items: `200`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/lists/{identity}/source-check-policyStatus

Required scopes: contacts:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

CheckPolicyView

422 Validation Error

application/json

PATCH/v1/lists/{identity}/source-check-policyUpdate

Required scopes: contacts:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

CheckPolicyDisable

Field	Type and constraints
`expected_revision`Required	`integer` Minimum: `0.0`
`enabled`Required	`false`
`terms`Optional	`null`

Responses

200 Successful Response

application/json

CheckPolicyView

422 Validation Error

application/json

GET/v1/lists/{identity}/source-check-roundsHistory

Required scopes: contacts:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`cursor`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `100`

Responses

200 Successful Response

application/json

Page_CheckRoundView_

422 Validation Error

application/json

Members1 operations

GET/membersMembers

Required scopes: inbox:read

Parameters

Field	Type and constraints
`after`Optionalquery	`string` Default: `""` · Max length: `128`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

WorkspaceMembers

422 Validation Error

application/json

Operations2 operations

GET/v1/operations/by-keyOperation By Key

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:read.

suppressions requires suppressions:read.

Parameters

Field Type and constraints

kindRequiredquery

"people.create" | "people.edit" | "companies.create" | "companies.edit" | "lists.create" | "lists.edit" | "lists.membership" | "people.save_source" | "companies.save_source" | "people.check_source" | "companies.check_source" | "people.refresh_preview" | "companies.refresh_preview" | "searches.create" | "searches.edit" | "search_sets.create" | "search_sets.edit" | "data_jobs.resume" | "data_jobs.confirm"

keyRequiredquery

string

Min length: 8 · Max length: 128

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/operations/{identity}Operation

Required scopes: Resource-dependent.

Resource scopes

contacts requires contacts:read.

suppressions requires suppressions:read.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

LookupResult_PersonPreview_

People3 operations

POST/v1/people/lookupLookup People

Required scopes: search:read

Request body Required

application/json

SourceLookup

Field	Type and constraints
`ids`Required	array of `string` Min items: `1` · Max items: `100`
`id_type`Optional	`"source" \| "record"` Default: `"source"`

Responses

200 Successful Response

application/json

429 Workspace discovery or request capacity exhausted; preserve the query and offer explicit retry.

Response headers

Field	Type and constraints
`Retry-After`Optional	`integer` Seconds until retry may be attempted. Minimum: `1.0`

application/json

422 Validation Error

application/json

POST/v1/people/resolveResolve People

Required scopes: search:read

Parameters

Field	Type and constraints
`Idempotency-Key`Optionalheader	`string` \| `null` Required for multiple inputs; preserves the frozen result across retries.

Request body Required

application/json

ResolveRequest

Field	Type and constraints
`inputs`Required	array of `ResolveInput` Min items: `1` · Max items: `100`

Responses

200 Successful Response

application/json

429 Workspace discovery or request capacity exhausted; preserve the query and offer explicit retry.

Response headers

Field	Type and constraints
`Retry-After`Optional	`integer` Seconds until retry may be attempted. Minimum: `1`

application/json

202 Matching continues on the same result set. Repeat the same body and Idempotency-Key to read progress without starting another lookup.

application/json

422 Validation Error

application/json

GET/v1/people/{identity}Person

Required scopes: search:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Min length: `1` · Max length: `256` · Pattern: `"^[^\\x00-\\x1f\\x7f]+$"`
`id_type`Optionalquery	`"source" \| "record"` Default: `"source"`

Responses

200 Successful Response

application/json

PersonPreview

429 Workspace discovery or request capacity exhausted; preserve the query and offer explicit retry.

Response headers

Field	Type and constraints
`Retry-After`Optional	`integer` Seconds until retry may be attempted. Minimum: `1`

application/json

422 Validation Error

application/json

Replies3 operations

POST/repliesReply

Required scopes: inbox:write spending:write

Request body Required

application/json

ReplyIn

Field	Type and constraints
`source_event`Optional	`string` \| `null`
`recipients`Optional	array of `string` \| `null`
`expected_send_price_cents`Optional	`integer` \| `null`
`id`Required	`string` Min length: `1` · Max length: `128`
`message_id`Required	`string` Min length: `1` · Max length: `256`
`subject`Required	`string` Min length: `1` · Max length: `500`
`body`Required	`string` Literal plain-text body for a new human reply; not a campaign template. Reuse the exact original payload and ID to recover an existing reply. Min length: `1` · Max length: `100000`
`html`Optional	`string` Recovery-only for an already-recorded exact original. Must be empty for a new human reply; nonempty HTML is rejected with plain_text_reply_required before admission. Default: `""` · Max length: `100000`
`attachments`Optional	array of `object` Recovery-only for an already-recorded exact original. Must be empty for a new human reply; outgoing files are rejected with plain_text_reply_required. Incoming downloads are a separate read capability. Max items: `3`

Responses

200 Successful Response

application/json

ReplyResult

422 Validation Error

application/json

POST/replies/{jid}/reviewReply Review

Required scopes: inbox:write spending:write

Parameters

Field	Type and constraints
`jid`Requiredpath	`string`

Request body Required

application/json

ReviewIn

Field	Type and constraints
`id`Required	`string` Min length: `1` · Max length: `128`
`expected_revision`Required	`integer` Minimum: `0.0`
`action`Required	`"authorize" \| "cancel"`
`expected_send_price_cents`Optional	`integer` \| `null`

Responses

200 Successful Response

application/json

ReplyReviewReceipt

422 Validation Error

application/json

GET/replies/{jid}/reviewsHistory

Required scopes: inbox:read

Parameters

Field	Type and constraints
`jid`Requiredpath	`string`
`after`Optionalquery	`integer` Default: `0` · Minimum: `0` · Maximum: `9007199254740991`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `100`

Responses

200 Successful Response

application/json

ReplyReviewHistory

422 Validation Error

application/json

Saved searches4 operations

GET/v1/saved-searchesSearches

Required scopes: search:read

Parameters

Field	Type and constraints
`cursor`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`
`state`Optionalquery	`"active" \| "archived"` Default: `"active"`
`q`Optionalquery	`string` Literal NFKC/casefolded, whitespace-normalized name substring. At most 1000 indexed candidates per page; follow next_cursor even on empty pages. Live ID traversal, not frozen membership. Default: `""` · Max length: `200`

Responses

200 Successful Response

application/json

Page_SavedSearchView_

422 Validation Error

application/json

POST/v1/saved-searchesCreate

Required scopes: contacts:write search:read

Parameters

Field	Type and constraints
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

SavedSearchCreate

Field	Type and constraints
`name`Required	`string` Min length: `1` · Max length: `200`
`entity_type`Required	`"person" \| "company"`
`query`Required	`SearchQuery-Input`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/saved-searches/{identity}Search

Required scopes: search:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

SavedSearchView

422 Validation Error

application/json

PATCH/v1/saved-searches/{identity}Edit

Required scopes: contacts:write search:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

SavedSearchEdit

Field	Type and constraints
`expected_revision`Required	`integer`
`state`Optional	`"active" \| "archived"` \| `null`
`name`Optional	`string` \| `null`
`query`Optional	`SearchQuery-Input` \| `null`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

Schema1 operations

GET/v1/schemaSchema

Required scopes: search:read

Parameters

Field	Type and constraints
`data_source`Optionalquery	`"people" \| "companies"` Default: `"people"`

Responses

200 Successful Response

application/json

CatalogueSchema

422 Validation Error

application/json

SearchQuery-Input | SearchNext

Search3 operations

POST/v1/searchSearch

Required scopes: search:read

Request body Required

application/json

Responses

200 Successful Response

application/json

SearchPage

429 Workspace discovery or request capacity exhausted; preserve the query and offer explicit retry.

Response headers

Field	Type and constraints
`Retry-After`Optional	`integer` Seconds until retry may be attempted. Minimum: `1.0`

application/json

422 Validation Error

application/json

POST/v1/search/facetsFacets

Required scopes: search:read

Conditional scopes

query.ownership=saved|net_new requires contacts:read.

Request body Required

application/json

FacetRequest

Field	Type and constraints
`query`Required	`SearchQuery-Input`
`field`Required	`string` Min length: `1` · Max length: `80`
`text`Optional	`string` Default: `""` · Max length: `80` · Pattern: `"^[^\\x00-\\x1f\\x7f]*$"`
`limit`Optional	`integer` Default: `50` · Minimum: `1.0` · Maximum: `100.0`

Responses

200 Successful Response

application/json

FacetPage

429 Workspace discovery or request capacity exhausted; preserve the query and offer explicit retry.

Response headers

Field	Type and constraints
`Retry-After`Optional	`integer` Seconds until retry may be attempted. Minimum: `1.0`

application/json

422 Validation Error

application/json

DELETE/v1/search/results/{identity}Close

Required scopes: search:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

204 Successful Response

422 Validation Error

application/json

Search sets4 operations

GET/v1/search-setsListing

Required scopes: search:read

Parameters

Field	Type and constraints
`cursor`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`
`state`Optionalquery	`"active" \| "archived"` Default: `"active"`
`q`Optionalquery	`string` Literal NFKC/casefolded, whitespace-normalized name substring. At most 1000 indexed candidates per page; follow next_cursor even on empty pages. Live ID traversal, not frozen membership. Default: `""` · Max length: `200`

Responses

200 Successful Response

application/json

Page_DomainSetView_

422 Validation Error

application/json

POST/v1/search-setsCreate

Required scopes: contacts:write search:read

Parameters

Field	Type and constraints
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

DomainSetCreate

Field	Type and constraints
`name`Required	`string` Min length: `1` · Max length: `200` · Pattern: `"\\S"`
`format`Required	`"csv" \| "lines"`
`content`Required	`string` Min length: `1` · Max length: `4194304`
`allow_invalid_rows`Optional	`boolean` Default: `false`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

GET/v1/search-sets/{identity}Original

Required scopes: search:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

DomainSetView

422 Validation Error

application/json

PATCH/v1/search-sets/{identity}Edit

Required scopes: contacts:write search:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`Idempotency-Key`Requiredheader	`string` Min length: `8` · Max length: `128` · Pattern: `"^[A-Za-z0-9_-]+$"`

Request body Required

application/json

DomainSetEdit

Field	Type and constraints
`expected_revision`Required	`integer`
`state`Optional	`"active" \| "archived"` \| `null`
`name`Optional	`string` \| `null`

Responses

200 Successful Response

application/json

422 Validation Error

application/json

Selections6 operations

GET/v1/selectionsHistory

Required scopes: contacts:read

Parameters

Field	Type and constraints
`cursor`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

Page_SelectionView_

422 Validation Error

application/json

GET/v1/selections/by-keyBy Key

Required scopes: contacts:read

Parameters

Field	Type and constraints
`key`Requiredquery	`string` Min length: `8` · Max length: `128`

Responses

200 Successful Response

application/json

SelectionView

422 Validation Error

application/json

GET/v1/selections/{identity}Original

Required scopes: contacts:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

SelectionView

422 Validation Error

application/json

POST/v1/selections/{identity}/cancelCancel

Required scopes: contacts:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`

Responses

200 Successful Response

application/json

SelectionView

422 Validation Error

application/json

GET/v1/selections/{identity}/previewsPreview Page

Required scopes: contacts:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`cursor`Optionalquery	`string` Default: `""` · Max length: `2048`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

SelectionPreviewPage

422 Validation Error

application/json

GET/v1/selections/{identity}/rowsRows

Required scopes: contacts:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string` Pattern: `"^[a-f0-9]{32}$"`
`after`Optionalquery	`integer` Default: `0` · Minimum: `0` · Maximum: `5000000`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

ImportRows

422 Validation Error

application/json

Send calendar1 operations

GET/send-calendarCustomer Calendar

Required scopes: campaigns:read

Pagination exception: partition=day returns bounded rows independently for each local day. The root next_cursor is null even when a day has has_more=true. To continue that day, request its local start/end boundaries with partition=range and the same timezone, campaign, view and projection filters, then follow the returned next_cursor with those day-range parameters unchanged until it is null. A null root cursor on partition=day does not mean all day rows have been loaded.

Parameters

Field	Type and constraints
`start`Requiredquery	`string` Format: `"date-time"`
`end`Requiredquery	`string` Format: `"date-time"`
`timezone`Optionalquery	`string` Default: `""` · Max length: `128`
`campaign`Optionalquery	`string` Default: `""` · Max length: `128`
`cursor`Optionalquery	`string` Default: `""` · Max length: `4096`
`limit`Optionalquery	`integer` Default: `100` · Minimum: `1` · Maximum: `500`
`view`Optionalquery	`"all" \| "history" \| "planned"` Default: `"all"`
`projection`Optionalquery	`"eligibility" \| "estimated"` Default: `"eligibility"`
`partition`Optionalquery	`"range" \| "day"` Default: `"range"`

Responses

200 Successful Response

application/json

CalendarPage

409 Invalid range/timezone/cursor, changed estimate or unavailable campaign; inspect detail.code

application/json

503 Read capacity or storage temporarily unavailable; inspect detail.code and Retry-After

application/json

422 Validation Error

application/json

Sender identities1 operations

GET/sender-identitiesIdentities

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`after`Optionalquery	`string` Default: `""` · Max length: `320`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `100`

Responses

200 Successful Response

application/json

SenderIdentityPage

422 Validation Error

application/json

Starts3 operations

GET/starts/{identity}Start Status

Required scopes: campaigns:read

Read an original legacy Start and any retained-capacity recovery options.

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

CampaignStartResponse

422 Validation Error

application/json

POST/starts/{identity}/cancelCancel Start

Required scopes: campaigns:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

CampaignStartResponse

422 Validation Error

application/json

POST/starts/{identity}/release-capacityRelease Failed Start

Required scopes: campaigns:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

CapacityRelease

422 Validation Error

application/json

Suppressions6 operations

GET/suppressionsCollection

Required scopes: suppressions:read

Parameters

Field	Type and constraints
`after`Optionalquery	`string` Default: `""` · Max length: `320`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`
`scope`Optionalquery	`"email" \| "domain"` Default: `"email"`

Responses

200 Successful Response

application/json

ExclusionPage

422 Validation Error

application/json

POST/suppressionsExclude

Required scopes: suppressions:write

Request body Required

application/json

ExclusionIn

Field	Type and constraints
`id`Required	`string` Min length: `1` · Max length: `128`
`email`Optional	`string` \| `null`
`domain`Optional	`string` \| `null`
`reason`Required	`string` Min length: `1` · Max length: `500` · Pattern: `"\\S"`
`evidence`Required	`string` Min length: `1` · Max length: `2000` · Pattern: `"\\S"`

Responses

200 Successful Response

application/json

ExclusionOriginal

422 Validation Error

application/json

POST/suppressions/batchBatch

Required scopes: suppressions:write

Request body Required

application/json

ExclusionBatchIn

Field	Type and constraints
`items`Required	array of `ExclusionIn` Min items: `1` · Max items: `200`

Responses

200 Successful Response

application/json

ExclusionResults

422 Validation Error

application/json

GET/suppressions/exportExport

Required scopes: suppressions:read

Download one bounded CSV page of workspace exclusions. Pass X-Next-Cursor as after for the next page. Formula-leading CSV cells are escaped; GET /suppressions provides the lossless JSON alternative with the same scope and keyset cursor.

Parameters

Field	Type and constraints
`after`Optionalquery	`string` Default: `""` · Max length: `320`
`limit`Optionalquery	`integer` Default: `200` · Minimum: `1` · Maximum: `1000`
`scope`Optionalquery	`"email" \| "domain"` Default: `"email"`

Responses

200 CSV page ordered by the excluded email or domain.

Response headers

Field	Type and constraints
`Content-Disposition`Optional	`string` Attachment filename for the selected scope.
`X-Next-Cursor`Optional	`string` Pass as after to continue; empty at the end of the list.
`X-Export-Consistency`Optional	`"live-keyset"` Live keyset traversal, not a frozen snapshot.

text/csv

string

422 Validation Error

application/json

GET/suppressions/operationsOperations

Required scopes: suppressions:read

Parameters

Field	Type and constraints
`before`Optionalquery	`integer` Default: `0` · Minimum: `0` · Maximum: `9007199254740991`
`limit`Optionalquery	`integer` Default: `50` · Minimum: `1` · Maximum: `200`

Responses

200 Successful Response

application/json

ExclusionHistory

422 Validation Error

application/json

GET/suppressions/operations/{identity}Operation

Required scopes: suppressions:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

ExclusionOriginal

422 Validation Error

application/json

Usage1 operations

GET/usageUsage

Required scopes: usage:read

Responses

200 Sending-wallet projection with at most 100 recent entries. Not the sending subscription, data balance or an all-time ledger page.

application/json

WalletUsage

Verification2 operations

GET/verification/batches/{identity}Status

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

VerificationBatchView

422 Validation Error

application/json

POST/verification/batches/{identity}/cancelCancel

Required scopes: audiences:write

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

VerificationBatchView

422 Validation Error

application/json

Workspace3 operations

GET/workspace/sending-outlookRead Sending Outlook

Required scopes: campaigns:read

Parameters

Field	Type and constraints
`projection`Optionalquery	`"eligibility" \| "estimated"` Default: `"eligibility"`
`timezone`Optionalquery	`string` Default: `""` · Max length: `128`

Responses

200 Successful Response

application/json

SendingOutlook

409 Invalid projection timezone or current projection conflict; inspect detail.code

application/json

503 Read capacity or storage temporarily unavailable; inspect detail.code and Retry-After

application/json

422 Validation Error

application/json

GET/workspace/sending-policyRead

Required scopes: usage:read

Responses

200 Successful Response

application/json

PolicyStatus

GET/workspace/sending-policy/operations/{identity}Inspect

Required scopes: usage:read

Parameters

Field	Type and constraints
`identity`Requiredpath	`string`

Responses

200 Successful Response

application/json

SendingPolicyOperation

422 Validation Error

application/json