Add Opt-Outs

Endpoint

POST https://api.connectly.ai/v1/businesses/{businessId}/add/opt_outs

Parameter	Location	Description
`businessId`	Path	Your Connectly business ID.
`X-API-Key`	Header	Your API key.

Safe to repeat. Sending the same list twice suppresses nothing new the second time and reports every entry under alreadyOptedOutCount.

Request body

{
  "entries": [...]
}

`entries` array (required)

Each object names one WhatsApp contact to suppress. Maximum 10,000 per request — send the rest in further calls.

Field	Type	Required	Description
`client`	string	Yes*	Contact’s phone number in E.164 format (e.g. `+14155558234`), with or without the leading `+`. *Not required when `userId` is set.
`userId`	string	No	Business-Scoped User ID (e.g. `US.13491208655302741918`), exactly as Connectly sends it in webhooks. Read only when `client` is empty — if both are set, `client` wins.

The same contact listed twice counts once, so the returned counts can sum to less than the number of entries you sent.

Examples

Suppress by phone number

The common case for a consent export.

{
  "entries": [
    { "client": "+14155558234" },
    { "client": "+14155559345" }
  ]
}

Suppress by Business-Scoped User ID

Use userId when your records key on the BSUID you received in a webhook rather than a phone number.

{
  "entries": [
    { "userId": "US.13491208655302741918" }
  ]
}

Mixed identifiers in one request

You can mix phone numbers and BSUIDs freely.

{
  "entries": [
    { "client": "+14155558234" },
    { "userId": "US.13491208655302741918" },
    { "client": "+14155559345" }
  ]
}

Response

The API returns HTTP 200 with a data object. Counts are over the contacts you named, not rows stored.

Field	Type	Description
`addedCount`	integer	Contacts this request suppressed.
`alreadyOptedOutCount`	integer	Contacts already suppressed through this API, so nothing changed. Re-sending an unchanged list reports every entry here.
`rejectedCount`	integer	Entries dropped as unreadable.
`rejected`	array	The dropped entries with their reasons, up to the first 100. Each carries `client` — the identifier exactly as you sent it — and `reason`.
`error`	object \| null	Summary of why entries were rejected, with a count per reason. Absent when nothing was rejected.

Success response

{
  "data": {
    "addedCount": 9870,
    "alreadyOptedOutCount": 128,
    "rejectedCount": 2,
    "rejected": [
      { "client": "not-a-number", "reason": "not a valid identifier for this channel" },
      { "client": "", "reason": "client or userId is required" }
    ],
    "error": {
      "message": "rejected 2 of 10000 entries: not a valid identifier for this channel (1), client or userId is required (1)",
      "type": "ERROR_TYPE_INVALID_ARGUMENT",
      "code": "ERROR_CODE_BAD_REQUEST",
      "userTitle": "Bad request sent",
      "userMessage": "Request or param(s) detected."
    }
  }
}

Treat the counts as best-effort when reconciling. Deciding what was already suppressed takes a read that Connectly skips rather than fail your upload for. When it is unavailable every entry is written and duplicates are dropped on storage — your contacts end up suppressed correctly, but an unchanged re-upload can report its whole file under addedCount and nothing under alreadyOptedOutCount.If you reconcile against these numbers, read a full addedCount as “unknown” rather than “changed”.

Error responses

Unreadable entries are dropped and counted — they do not fail the batch. The request fails outright only when no entry survives.

HTTP status	Meaning
`400`	Request body is malformed, `entries` is empty, or no entry could be read.
`401`	Missing or invalid API key.
`429`	Rate limit exceeded.
`500`	Internal server error.

Quote cntTraceId when reporting a failure — it identifies the request in our logs.

Rejection reasons

Reason	Cause
`not a valid identifier for this channel`	The value is neither a usable phone number nor a BSUID for WhatsApp.
`client or userId is required`	The entry set neither field.
`userId must be a business-scoped user id`	`userId` was set but is not a BSUID.
`client is not a valid business-scoped user id`	`client` looked like a BSUID but is malformed.

No entry could be read

Returned as HTTP 400 when every entry was rejected, rather than a 200 with an empty result.

{
  "message": "no entry could be read: not a valid identifier for this channel (2)",
  "errorType": "ERROR_TYPE_INVALID_ARGUMENT",
  "errorCode": "XOPTOUT.INVALID_ARGUMENT",
  "userTitle": "Bad request sent",
  "userMessage": "Request or param(s) detected.",
  "cntSsId": "A3304319921049468327",
  "cntTraceId": "5443858048914164853",
  "details": {},
  "type": "ERROR_TYPE_INVALID_ARGUMENT",
  "code": "ERROR_CODE_BAD_REQUEST",
  "extra": []
}

Too many entries

Returned when entries exceeds 10,000. Split the list across calls.

{
  "message": "at most 10000 entries per request",
  "errorType": "ERROR_TYPE_INVALID_ARGUMENT",
  "errorCode": "XOPTOUT.INVALID_ARGUMENT",
  "userTitle": "Bad request sent",
  "userMessage": "Request or param(s) detected.",
  "cntSsId": "A3304319921049468327",
  "cntTraceId": "5443858048914164853",
  "details": {},
  "type": "ERROR_TYPE_INVALID_ARGUMENT",
  "code": "ERROR_CODE_BAD_REQUEST",
  "extra": []
}

Rate limiting

This endpoint is limited to 60 requests per minute. Exceeding this returns HTTP 429 Too Many Requests. At 10,000 contacts per call that is well above what a daily consent sync needs — use exponential backoff if you expect to approach it.

Get Started

Campaigns

Messaging

Opt-Outs

Webhooks

Assets

AI Features

Analytics

Business Management

Integrations

Webchat

Resources

Endpoint

Request body

`entries` array (required)

Examples

Response

Error responses

Rejection reasons

Rate limiting

​Endpoint

​Request body

​entries array (required)

​Examples

​Response

​Error responses

​Rejection reasons

​Rate limiting

Endpoint

Request body

`entries` array (required)

Examples

Response

Error responses

Rejection reasons

Rate limiting