Audiences | Smallest AI Docs

An Audience is a curated list of phone numbers your campaigns will dial. Think of it as a segment—leads to call, customers to survey, appointments to confirm.

Creating an Audience

Use create_audience with a list of phone numbers and optional contact names:

1 from smallestai.atoms.audience import Audience
2 
3 audience = Audience()
4 
5 response = audience.create(
6     name="Q1 Sales Leads",
7     phone_numbers=["+916366821717", "+919353662554"],
8     names=[("John", "Doe"), ("Jane", "Smith")]
9 )
10 
11 audience_id = response["data"]["_id"]

The response confirms creation with the audience ID:

1 {
2   "status": true,
3   "data": {
4     "name": "Q1 Sales Leads",
5     "phoneNumberColumnName": "phoneNumber",
6     "_id": "696ddd56b905442f52b71392"
7   }
8 }

Phone numbers must use E.164 format: + followed by country code and number. Example: +916366821717

Listing Audiences

list() returns all audiences with their campaign associations:

1 audiences = audience.list()

Each audience includes campaign associations and member counts:

1 {
2   "status": true,
3   "data": [
4     {
5       "_id": "696ddd56b905442f52b71392",
6       "name": "Q1 Sales Leads",
7       "memberCount": 2,
8       "hasCampaigns": true,
9       "campaigns": [
10         {"_id": "...", "name": "January Outreach", "status": "completed"}
11       ]
12     }
13   ]
14 }

Viewing Members

get_members() returns a paginated list of contacts in the audience:

1 members = audience.get_members(
2     audience_id=audience_id,
3     page=1,
4     offset=10
5 )

Each member stores their contact data:

1 {
2   "status": true,
3   "data": {
4     "members": [
5       {
6         "_id": "696ddd56b905442f52b71394",
7         "data": {
8           "firstName": "John",
9           "lastName": "Doe",
10           "phoneNumber": "+916366821717"
11         }
12       }
13     ],
14     "totalCount": 2,
15     "totalPages": 1,
16     "hasMore": false
17   }
18 }

Adding Members

add_contacts() appends new contacts to an existing audience:

1 audience.add_contacts(
2     audience_id=audience_id,
3     phone_numbers=["+919876543210"],
4     names=[("New", "Contact")]
5 )

The response reports how many were added:

1 {
2   "status": true,
3   "data": [{"message": "1 members added successfully", "data": {"added": 1, "skipped": 0}}]
4 }

Deleting an Audience

delete() removes the audience and all its members:

1 audience.delete(audience_id=audience_id)

Audiences with active campaigns cannot be deleted. Complete or delete the campaigns first.

SDK Reference

Method	Description
`create(name, phone_numbers, names)`	Create a new audience
`list()`	List all audiences
`get(id)`	Get a single audience
`get_members(id, page, offset)`	Paginated member list
`add_contacts(id, phone_numbers, names)`	Append contacts
`delete(id)`	Remove an audience

Tips

What phone number format should I use?

E.164 format is required: + followed by country code and number with no spaces or dashes. Example: +14155551234 for US, +916366821717 for India.

Can I update existing member data?

Currently, you can add new members but not update existing ones. To change a contact’s info, delete and recreate the audience or add the corrected record (duplicates are skipped).

How many members can an audience have?

Audiences can scale to thousands of contacts. For very large lists, consider splitting into segments for easier management.

Why was my member skipped?

Members with duplicate phone numbers within the same audience are skipped. Check that each phone number is unique.