Contact lists

Team-member access: operators can create + delete lists and add or remove members; viewers can list + get but get 403 not_operator on any mutation. Lists aren't scoped per bot, every member sees every list on the account. See the Team members reference.

A contact list is a named bag of recipient phone numbers. Every broadcast picks one list and an audience: rcs (the default) leaves out the numbers the list's check found unreachable, not_rcs sends only to those, and all sends to every number. Numbers that opted out are never sent. See Audience.

A check is optional. Number checks work only with an active bot that supports them. Not every bot does. Through the API, a check needs your own active bot that supports number checks. The answers of a check count for broadcasts from every bot on your account, including bots that cannot check. A list that was never checked goes to every number except the people who opted out; numbers that cannot get RCS fail and are not charged.

POST   /api/v1/rcs/contact-lists
GET    /api/v1/rcs/contact-lists
DELETE /api/v1/rcs/contact-lists/{id}

POST   /api/v1/rcs/contact-lists/{id}/members
GET    /api/v1/rcs/contact-lists/{id}/members
DELETE /api/v1/rcs/contact-lists/{id}/members/{phone}

POST   /api/v1/rcs/contact-lists/{id}/import      # CSV import

POST   /api/v1/rcs/contact-lists/{id}/check-reachability
GET    /api/v1/rcs/contact-lists/{id}/audience?bot_id={bot_id}
DELETE /api/v1/rcs/contact-lists/{id}/unreachable
GET    /api/v1/rcs/contact-lists/{id}/reachable.csv
POST   /api/v1/rcs/contact-lists/{id}/create-reachable-list

Create a list

POST /api/v1/rcs/contact-lists
{ "name": "May launch, opted in" }

Response:

{
  "success": true,
  "list_id": "a1b2…",
  "name":    "May launch, opted in",
  "count":   0,
  "created_at": "2026-05-27T09:14:00Z"
}

Add members (bulk)

CSV-style uploads are passed as JSON. Phones follow the same rule as Import CSV below; a phone holding several numbers adds each one.

POST /api/v1/rcs/contact-lists/{id}/members
{
  "members": [
    { "phone": "+919876543210", "name": "Asha",  "extra": { "city": "Mumbai" } },
    { "phone": "+919876543211", "name": "Rohan", "extra": { "city": "Pune"   } }
  ]
}

Up to 100,000 members per request. Members already in the list overwrite (idempotent, safe to retry on partial network failure).

Response:

{
  "success": true,
  "added":   2,
  "skipped": 0,
  "count":   2
}

skipped counts numbers that are not a valid mobile, numbers Excel changed into a short form (9.87654E+09), and rows that could not be saved.

List members

GET /api/v1/rcs/contact-lists/{id}/members?size=200

size defaults to 200, max 1000. For huge lists prefer slicing by phone prefix using the extra map at upload time.

A member carries reachable (true or false) only when the list's answers that count stand behind it, the same answers the audience counts and a broadcast uses. A member with no answer that counts has no reachable. Answers from a check made with a bot that does not support number checks are not shown: those members read as not checked.

Delete a member

DELETE /api/v1/rcs/contact-lists/{id}/members/{phone}

{phone} is the number with its + written as %2B. A number without a + is read the same way as in Import CSV, so 9876543210 removes +919876543210.

Delete a list

DELETE /api/v1/rcs/contact-lists/{id}

Removes the list plus every member. Broadcasts that already snapshotted this list at create time keep running. They don't read the list table after the snapshot.

Deleting a list also stops an import or a reachability check that is running on it.

Import CSV

Bulk-import a CSV of phones (and optional name / custom fields) into an existing list. Streams the upload, the file is never loaded fully in memory.

POST /api/v1/rcs/contact-lists/{id}/import
Content-Type: multipart/form-data

Form fields:

field	type	required	description
`file`	file	yes	The CSV upload. 10 MB / 50 000 rows cap; larger returns `413`.
`mapping`	JSON string	yes	Column mapping. See below.
`dedup`	bool	no (default `true`)	Drop rows whose phone is already on this list.
`dry_run`	bool	no (default `false`)	When `true`, parse + validate + summarise but do not insert.

Mapping schema

{
  "phone_col": 0,
  "name_col": 1,
  "custom_cols": [
    { "index": 2, "name": "city" },
    { "index": 3, "name": "plan" }
  ]
}

Rules:

phone_col is required and must appear exactly once. Any other role picking the same column returns a 400.
name_col is optional; at most one column can be name.
custom_cols[] accepts up to 10 entries. Each name becomes a key in the member's extra map, so the operator can address the fields at broadcast render time. Custom column names are trimmed to 40 chars.

If the first row of the CSV has no digits in any cell it is treated as a header row and skipped from the insert.

Without a +, only an Indian mobile is accepted: 10 digits starting 6 to 9, optionally with 0, 91 or 0091 in front, saved as +91 and the 10 digits. With a +, any country is kept as written, but +91 must be followed by a 10-digit mobile. Other rows are reported in malformed_rows and skipped.

Sample request

curl -X POST https://api.splashifypro.com/api/v1/rcs/contact-lists/<list_id>/import \
     -H "Authorization: Bearer <panel_jwt>" \
     -F "[email protected]" \
     -F "dedup=true" \
     -F 'mapping={"phone_col":0,"name_col":1,"custom_cols":[{"index":2,"name":"city"}]}'

Sample CSV

phone,name,city
+919876543210,Asha,Mumbai
9876543211,Rohan,Pune
918293834982,Kiran,Bengaluru
9812345678,Priya,Chennai

Response

{
  "success": true,
  "inserted": 4890,
  "duplicates_skipped": 33,
  "malformed_rows": [
    { "row": 42,  "phone": "abc",  "reason": "not a valid Indian mobile number" },
    { "row": 118, "phone": "98765432",  "reason": "not a valid Indian mobile number" }
  ],
  "elapsed_ms": 4218
}

When dry_run=true, inserted is 0 and an additional would_insert field carries the count that WOULD have been written.

Dedup

toggle	when applied	O(cost)
`dedup`	after parse, before insert	one full read of this list's members

Access

Operators + owners can import. Viewers get 403 not_operator.

Check reachability

POST /api/v1/rcs/contact-lists/{id}/check-reachability?bot_id={bot_id}

Starts a background check of the list's numbers and answers 202 at once. The check runs with one bot, and its answers count for broadcasts from every bot on your account. Pass the bot as ?bot_id=, the X-Bot-Id header, or {"bot_id": "…"} in the body.

Through the API, only your own active bot that supports number checks can run one. Without a bot, your first active bot that supports them is used. To know whether a given bot is one, read check_bot_ok from the audience endpoint, or check the bots on your account.

In the panel, an account with no bot that supports number checks can still check its lists: we run the check for you, and the list's check shows no bot name. This applies only in the panel. An API call from such an account is refused as before: 400 no_check_bot, or 400 bot_cannot_check when it names a bot.

Which numbers a check covers:

Case	Numbers checked
The list has no answers that count (never checked, or only a check that does not count)	Every number
Same bot as the last check, that check finished cleanly, and no `?force=true`	Only numbers with no answer yet (`incremental: true`)
Any other check of a list with answers that count, with any bot, with or without `?force=true`	Numbers the check found unreachable, and numbers with no answer that counts. Every reachable answer is kept and not checked again (`keeps_can_get: true`)
The last check with this bot stopped part way	The rest: answers it already saved are kept, even with `force=true` (`resumed: true`)

There is no way to check a reachable answer again. To send to those numbers anyway, create the broadcast with audience: "all".

You never have to wait for a check to send: a broadcast created or started while a check runs uses the answers saved when its recipients are prepared. While a check runs, and after one fails or stops part way, the answers from the check before it still count, together with the answers the new check has saved. On a list with no answers that count before the check (has_answers was false), there is no check before it: the new answers count once the check finishes, and until then every number reads as not checked.

A check of 5,000 numbers or more runs in the background on the network's side and can take up to an hour; poll the list as for any check. Numbers the network does not answer for stay unchecked, and the check finishes with a note saying how many. When the bot is not live on the network yet, the check stops at once and reachability_check_error says Your bot is not live on the network yet, so its numbers could not be checked. Check again after it goes live. No answer from that check is used.

An account runs at most two checks of 5,000 numbers or more at a time. Another one stops at once, with nothing checked, and reachability_check_error says Too many number checks of big lists are running on your account. Run this one when one of them finishes. Start it again when one finishes.

While a check runs, a second call gets 409 check_in_progress. The Check RCS capability page has the 202 body and how to follow progress.

A bot that cannot check is refused before anything starts:

{
  "success": false,
  "error":   "bot_cannot_check",
  "code":    "bot_cannot_check",
  "message": "This bot cannot check numbers. Pick another bot."
}

Status	`code`	When
`400`	`bot_cannot_check`	The bot you passed does not support number checks. Pick one that does.
`400`	`no_check_bot`	You passed no bot, and your account has no active bot that supports number checks. The message is `Number checks need an active bot that supports them.`
`403`	`bot_not_active`	The bot you passed is not active.
`404`	`bot_not_found`	The bot is not on your account.
`503`	`check_busy`	Panel only. We run the check for you and cannot start another one right now. The message is `Number checks are busy right now. Try again in a few minutes.` Nothing started.

Audience: who a broadcast reaches

GET /api/v1/rcs/contact-lists/{id}/audience?bot_id={bot_id}

Counts who a broadcast of this list from this bot would reach, with the same rule the send uses, for each audience at once (choices). Call it before you create a broadcast, to show the numbers or to catch a send nobody would get.

The rcs rule, per number (sendable, choices.rcs):

On your opt-out list, for the account or for this bot: not sent.
Found unreachable by the list's check, made with any of your bots: not sent.
Failed as not on RCS in a broadcast from this bot in the last 30 days: not sent, unless the list's check, made after that failure, found it reachable. A failure on another of your bots does not count. See Reachability filter.
Everything else is sent. That includes numbers never checked.

choices.not_rcs counts only the numbers found unreachable, and choices.all every number; neither has the 30-day skip, and opted-out numbers are never counted in any of them.

Only a bot that supports number checks can make that check, but its answers count for a broadcast from any of your bots, including one that cannot check. A check made earlier with a bot that does not support number checks, or with a bot you have since deleted, is ignored: the list counts as never checked.

bot_id can also come as the X-Bot-Id header. Without either, your default bot is used. Viewers can call it.

Response:

{
  "total":            1200,
  "reachable":        950,
  "unreachable":      180,
  "unchecked":        70,
  "checked_bot_id":   "9c1b7f4e-2a11-4c8e-8e0e-3f5d1b2c9e01",
  "checked_bot_name": "Acme Boutique",
  "checked_at":       "2026-09-26T10:42:00Z",
  "same_bot":         true,
  "check_running":    false,
  "check_available":  true,
  "check_bot_ok":     true,
  "opted_out":        12,
  "not_on_rcs":       8,
  "sendable":         1000,
  "reason":           "",
  "has_answers":      true,
  "choices":          { "rcs": 1000, "not_rcs": 180, "all": 1188 },
  "check_unfinished": false
}

Field	Type	Meaning
`total`	int	Numbers on the list. `reachable` + `unreachable` + `unchecked` = `total`.
`reachable`	int	Numbers the check found can get RCS.
`unreachable`	int	Numbers the check found cannot get RCS.
`unchecked`	int	Numbers with no answer.
`checked_bot_id`	string or null	The bot of the list's latest finished check. `null` when the list was never checked, a check is running, the last check failed or stopped, or it was made with a bot that does not support number checks. While a check runs, or after one failed or stopped, the answers from the check before it can still count: then `has_answers` is `true` and `checked_bot_id` is `null`.
`checked_bot_name`	string or null	That bot's name. `null` for a check we ran for you from the panel.
`checked_at`	string or null	When that check finished, in UTC.
`same_bot`	bool	`true` when the list has answers that count for this send. Then that is true for every bot you ask about; the field keeps its old name. The three counts above then use only the answers that count, and a number with no such answer counts as `unchecked`. When `false`, the counts show the answers on the list as they are, and the send does not use them: every number that has not opted out is sent.
`check_running`	bool	A check is running on this list now, with any bot.
`check_available`	bool	A check can run for this list: your account has at least one active bot that supports number checks, or, in the panel, we can run the check for you. When `false`, no new check can run, and a list with no finished check goes to every number that has not opted out. Through the API a check still needs your own bot that supports number checks.
`check_bot_ok`	bool	The bot you asked about is active and supports number checks, so it can run a check. In the panel, when your account has no such bot and we can run the check for you, it is `true` for your other bots too. A broadcast from a bot that cannot check still skips the numbers the list's latest check found unreachable, and its `reason` can be `all_unreachable`.
`opted_out`	int	Numbers on your opt-out list, for the account or for this bot. Never sent.
`not_on_rcs`	int	Numbers skipped because they failed as not on RCS in a broadcast from this bot in the last 30 days, and would be sent otherwise.
`sendable`	int	Numbers a broadcast from this bot with `audience: "rcs"` will send to. Always the same as `choices.rcs`.
`reason`	string	For `audience: "rcs"`. `""` when `sendable` is above 0. Otherwise why nobody is sent: `empty_list`, `all_unreachable` or `all_opted_out`. `all_unreachable` can come from a check made with any of your bots, and is also the reason when the numbers left were all skipped as `not_on_rcs`.
`has_answers`	bool	The list has answers that count, at least one reachable or unreachable. When `false`, the panel offers no choice and sends with `audience: "all"`.
`choices`	object	How many numbers each `audience` sends to: `rcs`, `not_rcs` and `all`. Opted-out numbers are never counted.
`check_unfinished`	bool	A check on the list has started and not finished: it is running, or it stopped part way. Information only: a send is never held back. While the check is running (`check_running`), a prepaid broadcast started now holds `choices.all`, see Start.

When reason is set, creating a broadcast from this list and bot with audience: "rcs" is refused with 400 no_reachable_recipients. When choices.not_rcs is 0, not_rcs is refused the same way, with the reason none_cannot_get; when choices.all is 0, every audience is refused.

A count is reused for up to a minute while the list and its check stay the same.

Status	`code`	Meaning
`400`	`invalid_bot_id`	`bot_id` is not a valid id.
`400`	`no_bot`	No `bot_id` was given and the account has no bot.
`403`	`bot_not_assigned`	You are a team member and this bot is outside your bot set.
`404`	`bot_not_found`	The bot is not on your account.
`404`		`list not found`.

Remove, export or copy by reachability

DELETE /api/v1/rcs/contact-lists/{id}/unreachable
GET    /api/v1/rcs/contact-lists/{id}/reachable.csv
POST   /api/v1/rcs/contact-lists/{id}/create-reachable-list

These three act on the answers of the list's latest finished check, whatever bot made it, as long as that bot supports number checks. A check made with a bot that does not support them does not count: the list is treated as never checked. After a check that finished with gaps, only the answers that check saved count.

DELETE …/unreachable removes the numbers the check found unreachable. Numbers never checked stay. Response: { "success": true, "deleted": 180, "remaining": 1020 }. When there is nothing to remove, deleted is 0 and message says so.
GET …/reachable.csv downloads the numbers the check found reachable, as a CSV you can import again: phone, name, then your extra columns.
POST …/create-reachable-list copies those numbers into a new list. The body { "name": "Acme Boutique VIP. Reachable" } is optional; the default name is the list's name followed by . Reachable. It answers 201 with list_id, name and count.

They are refused with HTTP 409 instead of acting on answers that may be half written or older than the latest check:

`code`	When	What to do
`check_in_progress`	A check is running on the list.	Wait until it finishes, then call again.
`no_finished_check`	No finished check stands behind the answers: the list was never checked, its last check failed or stopped, or it was made with a bot that does not support number checks.	Run a check, then call again.

{
  "success": false,
  "code":    "no_finished_check",
  "message": "This list needs a finished reachability check first. Run a check, then try again."
}

create-reachable-list is refused before the new list is made, so a refusal never leaves an empty list behind.

Contact lists

Create a list#

Add members (bulk)#

List members#

Delete a member#

Delete a list#

Import CSV#

Mapping schema#

Sample request#

Sample CSV#

Response#

Dedup#

Access#

Check reachability#

Audience: who a broadcast reaches#

Remove, export or copy by reachability#

Create a list

Add members (bulk)

List members

Delete a member

Delete a list

Import CSV

Mapping schema

Sample request

Sample CSV

Response

Dedup

Access

Check reachability

Audience: who a broadcast reaches

Remove, export or copy by reachability