Manage Audiences

Create or replace an audience

POST https://api.connectly.ai/v1/businesses/{businessId}/create/audiences

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

Takes the csvAssetId returned by Upload recipients, reads the file, and stores the list.

Request body

Field	Type	Required	Description
`csvAssetId`	string	Yes	Asset id of the uploaded CSV.
`name`	string	No	Display name, also what identifies the audience in the Connectly app. Generated when omitted.
`recipientColumn`	string	No	Header of the column holding the recipient identifier. Defaults to the first column.
`audienceId`	string	No	Replace this audience’s recipients instead of creating a new one.

{
  "name": "black_friday_2026",
  "csvAssetId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "recipientColumn": "phone"
}

Response

{
  "data": {
    "audience": {
      "audienceId": "01925f3a-7c41-7e2b-9a10-3f0c8d5b6e47",
      "name": "black_friday_2026",
      "recipientCount": 9998,
      "variables": ["name", "order_id"],
      "createdAt": "2026-11-20T09:14:02.384Z",
      "updatedAt": "2026-11-20T09:14:02.384Z",
      "downloadUrl": "https://..."
    },
    "acceptedCount": 9998,
    "rejectedCount": 2,
    "error": {
      "message": "rejected 2 of 10000 recipients: not a valid phone number or user id",
      "type": "ERROR_TYPE_INVALID_ARGUMENT",
      "code": "ERROR_CODE_BAD_REQUEST",
      "userTitle": "Bad request sent",
      "userMessage": "Request or param(s) detected."
    }
  }
}

Rows whose recipient cannot be read are dropped and counted in rejectedCount, with the reasons in error. The request fails only when nothing survives.

Check variables against the campaign you intend to send. These are the column names Connectly stored, and they must match the campaign’s placeholders exactly.

Replacing

Pass audienceId to overwrite that audience’s recipients with a newly uploaded CSV. The id and any sends already created from it are unchanged.

{
  "audienceId": "01925f3a-7c41-7e2b-9a10-3f0c8d5b6e47",
  "csvAssetId": "c81d4e2e-bcf2-11e6-869b-7df92533d2db",
  "recipientColumn": "phone"
}

An audienceId that names nothing returns 404 — it is not created for you.

Get an audience

GET https://api.connectly.ai/v1/businesses/{businessId}/get/audiences/{audienceId}

{
  "data": {
    "audienceId": "01925f3a-7c41-7e2b-9a10-3f0c8d5b6e47",
    "name": "black_friday_2026",
    "recipientCount": 9998,
    "variables": ["name", "order_id"],
    "createdAt": "2026-11-20T09:14:02.384Z",
    "updatedAt": "2026-11-20T09:14:02.384Z",
    "downloadUrl": "https://..."
  }
}

downloadUrl is a time-limited link to the stored CSV, valid for one hour. Request the audience again for a fresh link. The recipients are never returned inline — a million-recipient list is well over 100MB. The stored CSV is not byte-for-byte your upload. The recipient column is renamed external_id, each recipient is in canonical form (E.164, or bsuid: followed by the BSUID), and the columns are sorted by name.

Delete an audience

DELETE https://api.connectly.ai/v1/businesses/{businessId}/delete/audiences/{audienceId}

Sends already created from the audience are unaffected; each keeps its own copy of the recipients.

Errors

Status	Cause
`400`	`csvAssetId` is missing, the CSV has more than 1,000,000 recipients, `recipientColumn` names no column in the file, or no recipient in the file could be read.
`404`	`csvAssetId` or `audienceId` names nothing you own.
`401`	Missing or invalid API key.
`429`	More than 60 create requests in a minute.

Next step

Send to an audience

Send a published campaign to the audience, now or on a schedule.

Get Started

Campaigns

Audiences

Messaging

Opt-Outs

Webhooks

Assets

AI Features

Analytics

Business Management

Integrations

Tools

Webchat

Resources

Create or replace an audience

Request body

Response

Replacing

Get an audience

Delete an audience

Errors

Next step

Send to an audience

​Create or replace an audience

​Request body

​Response

​Replacing

​Get an audience

​Delete an audience

​Errors

​Next step

Send to an audience

Create or replace an audience

Request body

Response

Replacing

Get an audience

Delete an audience

Errors

Next step