Skip to main content
POST
Set contact status
Use this endpoint to block, unblock, subscribe, or unsubscribe a contact.

Authorizations

Authorization
string
header
required

Recommended authentication for new integrations. Generate a short-lived JWT from your API Secret ID and API Secret Key, then pass the signed JWT as a bearer token in the Authorization header.

API Secret credentials are available in the Heymarket app under Settings > Integrations > API. The Secret Key is shown only when it is generated, so copy and store it securely before closing the dialog.

Use the following JWT values:

Replace CURRENT_UNIX_TIMESTAMP with the current Unix timestamp in seconds when generating the token.

Sign the JWT with HMAC-SHA256 using this signing secret:

Send the signed JWT as a bearer token:

Tokens expire 5 minutes after the iat timestamp. Generate a new JWT per request, or cache it briefly for less than 5 minutes. Generate JWTs only from trusted server-side code; do not expose the API Secret Key in browser, mobile, or other client-side code.

Body

application/json

Heymarket ID of the contact and status to set

id
integer
Example:

10000

phone
string<phone>
Example:

"12345678900"

status
string
Example:

"active"

inbox_ids
integer[]

Optional inbox ids to scope a subscribed/active/unsubscribed status change to specific inboxes instead of team-wide. Applies only to teams on per-inbox opt-out mode (requires the inbox-level opt-out entitlement). Omitting this field keeps the existing global (team-wide) behavior, or pass user_id to cover that user's inboxes. Ignored for the blocked/unblocked statuses.

Example:
user_id
integer

Optional acting user, applied to subscribed/active/unsubscribed. On a team using per-inbox opt-out, supplying user_id WITHOUT inbox_ids scopes the change to the inboxes that user belongs to (skipping inboxes with no phone number). Supplied together with inbox_ids it does not change the scope, but every requested inbox must be one the user can access. On a team using global opt-out the change stays team-wide with user_id recorded as the actor. The user must be an active member of the authenticated team.

Example:

4242

Response

Status set. Returns the text body success, except when the change landed team-wide although the request tried to scope it: that answers JSON with applied_scope: team_wide and no inbox list, so a wider-than-requested scope is visible in the body. Two cases reach it — user_id supplied on a team whose mode keeps every change team-wide, and a subscribed/active request scoped with inbox_ids against a removable team-wide opt-out, which is revoked in full across every inbox on the team.

The response is of type string.