Articles in this section

Lists & Subscribers API Documentation

  • Updated

1. Introduction

This document describes the TXTImpact REST APIs for managing Lists (contact lists) and the Subscribers (contacts) within them. Using these endpoints you can programmatically create and manage lists, add and remove subscribers, and bulk-import contacts — the same operations available in your account under Subscribers.

Endpoints at a glance (base URL https://api.txtimpact.com/api/v2):

Operation Method Endpoint
Get all lists GET /Subscriber/Lists
Create a list POST /Subscriber/List
Rename a list PATCH /Subscriber/List/{id}
Delete a list DELETE /Subscriber/List/{id}
Add a subscriber POST /Subscriber/{campaignId}
Remove subscribers (by mobile) PATCH /Subscriber/{campaignId}
Delete subscribers (by mobile) DELETE /Subscriber/{campaignId}
Import subscribers (bulk) POST /Subscriber/Import/{campaignId}

2. Authentication

All requests must be authenticated with an API Key, sent in the apikey request header.

Header Value Required
apikey YOUR_API_KEY Yes
Content-Type application/json Yes (for requests with a body)

How to generate your API key: see How to Generate an API Key (Integrations → API Access in your account).

An invalid or missing key returns 401 Unauthorized.

3. Conventions

Item Value
Base URL https://api.txtimpact.com/api/v2
Format JSON request and response bodies (application/json)
Field names Case-insensitive (e.g. mobileNumber and mobilenumber both work)
Read-only fields Marked read-only — returned by the API, ignored on input
IDs used below. A List ID identifies a single contact list (shown as c=… in the app URL, e.g. .../subscribers/manage?c=97871). It is the same value as the campaignId in these endpoints. A Subscriber ID identifies a single contact.
Mobile number format. All mobile numbers must be in international format with the country code prefixed (e.g. US 12129204690, UK 447700900123). Digits-only is recommended; the + and common separators (spaces, dashes, parentheses) are accepted and normalized. Numbers without a country code may be rejected, or dropped during import.

4. Lists

4.1 Get All Lists

Returns all contact lists in your account, each with its current subscriber count.

GET /Subscriber/Lists

Example 

curl -X GET "https://api.txtimpact.com/api/v2/Subscriber/Lists" \
  -H "apikey: YOUR_API_KEY"

Response — array of lists: 

[
  {
    "campaignId": 97871,
    "campaignName": "VIP Customers",
    "campaignType": "list",
    "subscriberCount": 1240
  }
]

4.2 Create a List

Creates a new contact list. You supply only the list name — the list type and sending number are set automatically from your account.

POST /Subscriber/List

Request body:

Field Type Required Description
listName string Yes Display name of the new list.

Example 

curl -X POST "https://api.txtimpact.com/api/v2/Subscriber/List" \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "listName": "VIP Customers" }'

Response 201 Created — the new list's ID: 

{ "listId": 98432 }

4.3 Rename a List

PATCH /Subscriber/List/{id}
Path parameter Type Description
id integer The List ID to rename.

Request body:

Field Type Required Description
listName string Yes The new list name.

Example 

curl -X PATCH "https://api.txtimpact.com/api/v2/Subscriber/List/97871" \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "listName": "VIP Customers 2025" }'

Response 200 OK.

4.4 Delete a List

Deletes the list and removes all of its subscriber memberships. Subscribers that belong to other lists are unaffected.

DELETE /Subscriber/List/{id}
Path parameter Type Description
id integer The List ID to delete.

Example 

curl -X DELETE "https://api.txtimpact.com/api/v2/Subscriber/List/97871" \
  -H "apikey: YOUR_API_KEY"

Response 204 No Content — deleted.

5. Subscribers

5.1 Add a Subscriber to a List

Adds a single subscriber (contact) to a list. If the subscriber already exists, their record is updated.

POST /Subscriber/{campaignId}
Path parameter Type Description
campaignId integer The List ID to add the subscriber to.

Request body — Subscriber object:

Field Type Required Description
mobileNumber string Yes Subscriber's mobile number in international format, e.g. "12129204690".
subscriberName string No Contact's name.
email string No Contact's email address.
custom1–custom4 string No Custom field values.
dob string No Date of birth (MM/dd/yyyy).
status string No Subscription status, single character (e.g. "A" = active).

Example 

curl -X POST "https://api.txtimpact.com/api/v2/Subscriber/97871" \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mobileNumber": "12129204690",
    "subscriberName": "John Doe",
    "email": "john@example.com",
    "custom1": "Gold"
  }'

Response 200 OK — the saved subscriber.

5.2 Remove Subscribers from a List

Unlinks subscribers from a list by mobile number. The subscriber records are kept (they remain in any other lists). Send an array of mobile numbers to remove several at once.

PATCH /Subscriber/{campaignId}
Path parameter Type Description
campaignId integer The List ID to remove the subscribers from.

Request body — array of mobile numbers (international format, exact match): 

curl -X PATCH "https://api.txtimpact.com/api/v2/Subscriber/97871" \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '["12129204690", "13105551234"]'

Response 200 OK — status result.

5.3 Delete Subscribers

Removes subscribers from a list by mobile number and permanently deletes the subscriber record when it is not a member of any other list. Send an array of mobile numbers.

Difference from Remove: Remove (5.2) only unlinks a subscriber from the list; Delete also removes the subscriber entirely — but only if they don't belong to any other list.
DELETE /Subscriber/{campaignId}
Path parameter Type Description
campaignId integer The List ID to delete the subscribers from.

Request body — array of mobile numbers (international format, exact match): 

curl -X DELETE "https://api.txtimpact.com/api/v2/Subscriber/97871" \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '["12129204690", "13105551234"]'

Response 200 OK — status result.

5.4 Import Subscribers (Bulk Add to a List)

Adds many subscribers to a list in one request. Send the contact rows as a JSON array. Invalid or disallowed numbers are dropped and reported back.

POST /Subscriber/Import/{campaignId}
Parameter In Type Description
campaignId path integer The target List ID.
checkDuplicate query boolean Optional (default false). true skips numbers already in the list.

Request body — array of subscriber rows:

Field Type Required Description
mobileNumber string Yes Subscriber's mobile number in international format (country code prefixed).
subscriberName string No Contact's name.
email string No Contact's email address.
custom1–custom4 string No Custom field values.
dob string No Date of birth (MM/dd/yyyy).

Example 

curl -X POST "https://api.txtimpact.com/api/v2/Subscriber/Import/97871?checkDuplicate=false" \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "mobileNumber": "12129204690", "subscriberName": "John Doe", "email": "john@example.com", "custom1": "Gold" },
    { "mobileNumber": "13105551234", "subscriberName": "Jane Roe" }
  ]'

Response 201 Created — import summary: 

{
  "importedCount": 1,
  "dropped": [
    { "mobileNumber": "13105551234", "fullName": "Jane Roe", "reason": "Invalid mobile number" }
  ]
}

6. Response & Error Handling

Status Meaning
200 OK Request succeeded.
201 Created Resource created (bulk import).
400 Bad Request Missing or invalid fields.
401 Unauthorized Missing or invalid apikey.
5xx Server error — retry later or contact support.

7. Support

Questions or issues: support@wire2air.com. See also the Developer APIs section for the Send Message API and webhook documentation.