Audiences — Reference

List audiences

get /v1/audiences

curl TypeScript

curl -X GET "https://api.clement.so/v1/audiences" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.audiences.list();

Query parameters

limit integer
starting_after string
ending_before string

Response200

OK

Property	Type	Description
`object` required	enum (1)	`"list"`
`data` required	array<Audience>
`has_more` required	boolean
`next_cursor` required	string \| null
`prev_cursor` required	string \| null

Example response

{
  "object": "list",
  "data": [
    {
      "id": "aud_01HZ8X3J9K7P2QV6R5N4M3T2L3",
      "object": "audience",
      "mode": "live",
      "name": "Q2 outbound prospects",
      "description": "Pulled from HubSpot \"Tier 1\" segment, May import.",
      "contact_count": 1842,
      "created_at": "2026-05-02T16:00:00Z",
      "updated_at": "2026-05-02T16:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "string",
  "prev_cursor": "string"
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.

Create an audience

post /v1/audiences

curl TypeScript

curl -X POST "https://api.clement.so/v1/audiences" \
  -H "Authorization: Bearer $CLEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
      "name": "Alice Liddell",
      "description": "A short human-readable description."
    }'

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.audiences.create({
  "name": "Alice Liddell",
  "description": "A short human-readable description."
});

Request body

Property	Type	Description
`name` required	string
`description`	string

Response201

Created

Property	Type	Description
`id` required	string	Example: `"aud_AM788072KD0X99RP8HK5AH0000"`
`object` required	enum (1)	`"audience"`
`mode` required	enum (2)	`"live""test"`
`name` required	string
`description` required	string \| null
`contact_count` required	integer
`created_at` required	string (date-time)
`updated_at` required	string (date-time)

Example response

{
  "id": "aud_01HZ8X3J9K7P2QV6R5N4M3T2L3",
  "object": "audience",
  "mode": "live",
  "name": "Q2 outbound prospects",
  "description": "Pulled from HubSpot \"Tier 1\" segment, May import.",
  "contact_count": 1842,
  "created_at": "2026-05-02T16:00:00Z",
  "updated_at": "2026-05-02T16:00:00Z"
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.

Retrieve an audience

get /v1/audiences/{id}

curl TypeScript

curl -X GET "https://api.clement.so/v1/audiences/obj_01HZ8X3J9K7P2QV6R5N4M3T2L1" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.audiences.retrieve("obj_01HZ8X3J9K7P2QV6R5N4M3T2L1");

Path parameters

id string required

Response200

OK

Property	Type	Description
`id` required	string	Example: `"aud_AM788072KD0X99RP8HK5AH0000"`
`object` required	enum (1)	`"audience"`
`mode` required	enum (2)	`"live""test"`
`name` required	string
`description` required	string \| null
`contact_count` required	integer
`created_at` required	string (date-time)
`updated_at` required	string (date-time)

Example response

{
  "id": "aud_01HZ8X3J9K7P2QV6R5N4M3T2L3",
  "object": "audience",
  "mode": "live",
  "name": "Q2 outbound prospects",
  "description": "Pulled from HubSpot \"Tier 1\" segment, May import.",
  "contact_count": 1842,
  "created_at": "2026-05-02T16:00:00Z",
  "updated_at": "2026-05-02T16:00:00Z"
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.

Update an audience

patch /v1/audiences/{id}

curl TypeScript

curl -X PATCH "https://api.clement.so/v1/audiences/obj_01HZ8X3J9K7P2QV6R5N4M3T2L1" \
  -H "Authorization: Bearer $CLEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
      "name": "Alice Liddell",
      "description": "A short human-readable description."
    }'

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.audiences.update("obj_01HZ8X3J9K7P2QV6R5N4M3T2L1", {
  "name": "Alice Liddell",
  "description": "A short human-readable description."
});

Path parameters

id string required

Request body

Property	Type	Description
`name`	string
`description`	string \| null

Response200

Updated

Property	Type	Description
`id` required	string	Example: `"aud_AM788072KD0X99RP8HK5AH0000"`
`object` required	enum (1)	`"audience"`
`mode` required	enum (2)	`"live""test"`
`name` required	string
`description` required	string \| null
`contact_count` required	integer
`created_at` required	string (date-time)
`updated_at` required	string (date-time)

Example response

{
  "id": "aud_01HZ8X3J9K7P2QV6R5N4M3T2L3",
  "object": "audience",
  "mode": "live",
  "name": "Q2 outbound prospects",
  "description": "Pulled from HubSpot \"Tier 1\" segment, May import.",
  "contact_count": 1842,
  "created_at": "2026-05-02T16:00:00Z",
  "updated_at": "2026-05-02T16:00:00Z"
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.

Delete an audience

delete /v1/audiences/{id}

Cascades to `audience_contacts`; underlying contacts are unaffected. `?confirm=true` is required when the audience contains any contacts.

curl TypeScript

curl -X DELETE "https://api.clement.so/v1/audiences/obj_01HZ8X3J9K7P2QV6R5N4M3T2L1" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.audiences.delete("obj_01HZ8X3J9K7P2QV6R5N4M3T2L1");

Path parameters

id string required

Query parameters

confirm string

Response200

Deleted

Property	Type	Description
`id` required	string	Example: `"aud_AM788072KD0X99RP8HK5AH0000"`
`object` required	enum (1)	`"audience"`
`mode` required	enum (2)	`"live""test"`
`name` required	string
`description` required	string \| null
`contact_count` required	integer
`created_at` required	string (date-time)
`updated_at` required	string (date-time)

Example response

{
  "id": "aud_01HZ8X3J9K7P2QV6R5N4M3T2L3",
  "object": "audience",
  "mode": "live",
  "name": "Q2 outbound prospects",
  "description": "Pulled from HubSpot \"Tier 1\" segment, May import.",
  "contact_count": 1842,
  "created_at": "2026-05-02T16:00:00Z",
  "updated_at": "2026-05-02T16:00:00Z"
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.

Attach contacts to an audience

post /v1/audiences/{id}/contacts

Idempotent on `(audience, contact)`. Up to 1,000 contact IDs per call.

curl TypeScript

curl -X POST "https://api.clement.so/v1/audiences/obj_01HZ8X3J9K7P2QV6R5N4M3T2L1/contacts" \
  -H "Authorization: Bearer $CLEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
      "contact_ids": [
        "string"
      ]
    }'

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.audiences.attachContacts("obj_01HZ8X3J9K7P2QV6R5N4M3T2L1", [
  "string"
]);

Path parameters

id string required

Request body

Property	Type	Description
`contact_ids` required	array<string>

Response200

Result

Property Type Description

object required

enum (1)

"attach_result"

attached required integer

skipped required integer

errors required

array<object>

Show properties

Property Type Description

index required integer

contact_id required string

error required

object

Show properties

Property	Type	Description
`type` required	string
`code` required	string
`message` required	string

Example response

{
  "object": "attach_result",
  "attached": 0,
  "skipped": 0,
  "errors": [
    {
      "index": 0,
      "contact_id": "con_01HZ8X3J9K7P2QV6R5N4M3T2L2",
      "error": {
        "type": "string",
        "code": "string",
        "message": "string"
      }
    }
  ]
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.

Detach one contact from an audience

delete /v1/audiences/{id}/contacts/{contact_id}

curl TypeScript

curl -X DELETE "https://api.clement.so/v1/audiences/obj_01HZ8X3J9K7P2QV6R5N4M3T2L1/contacts/con_01HZ8X3J9K7P2QV6R5N4M3T2L1" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.audiences.detachContact("obj_01HZ8X3J9K7P2QV6R5N4M3T2L1", "con_01HZ8X3J9K7P2QV6R5N4M3T2L1");

Path parameters

id string required
contact_id string required

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.