Merge Your Contacts Into Lists

With the Lists API, you can arrange your database contacts into different lists for sending targeted bulk text messages.

Get all lists

To get all lists, use:

GET /api/v2/lists

with these parameters:

NameRequired?ExampleDescription
pageNo3Fetch the specified results page. The default is 1.
limitNo25The number of results per page. The default is 10.

You will receive the standard paginated response:

ParameterExampleDescription
page3The current fetched page.
limit25The number of results per page.
pageCount150The total number of pages.
resourcesArray of list resourcesSee next section for list resource format details.

Unlike the similar Contacts command, this command always returns both private and shared lists.

Get the details of a specific list

To get a single list, use:

GET /api/v2/lists/{id}

where id is a list ID. Note, this command has no parameters.

You will receive a response in the following format:

ParameterExampleDescription
id 715List ID.
namePrivate listList name.
descriptionPrivate contacts of C. R. ConwayList description.
sharedfalseIs the list shared among all sub-accounts?
membersCount 311 List members count.

Create a new list

To create a new list, use:

POST /api/v2/lists

with the following parameters:

NameRequired?ExamplesDescription
nameYes Private listList name.
sharedNo0 Should new list be shared among all the sub-accounts? The default is 0 (false).

If successful, you will receive the standard link response:

ParameterExampleDescription
id 715List ID.
href /api/v2/lists/715Link to List.

Edit a list

To modify a list, use:

PUT /api/v2/lists/{id}

where id is a list ID. The command uses the same parameters as those used when creating it:

NameRequired?ExampleDescription
nameYesPrivate listList name.
sharedNo0Make this list shared or not? The default is 0 (false).

If successful, you will receive the standard link response:

ParameterExampleDescription
id 715List ID.
href /api/v2/lists/715Link to the edited list.

Delete a list

To delete a list,use:

DELETE /api/v2/lists/{id}

where id is a list ID. Note, this command has no parameters. If successful, this command will return the standard delete response (204 No Content), otherwise a standard error response will be returned.

When you delete a list, the contacts in it are deleted as well unless they were saved in other list.

Get all contacts in a list

To get all contacts assigned to a list, use:

GET /api/v2/lists/{id}/contacts

where id is a list ID, with these parameters:

NameRequired?ExampleDescription
pageNo3Fetch specified results page. The default is 1.
limitNo25How many results to return. The default is 10.

You will receive the standard paginated response:

ParameterExampleDescription
page3The current fetched page.
limit25The number of results per page.
pageCount150The total number of pages.
resourcesArray of contact resources See the Contacts chapter for contact resource format details.

Assign contacts to a list

To assign contacts to a specified list,use

PUT /api/v2/lists/{id}/contacts

where id is a list ID, with the following parameters:

NameRequired?ExampleDescription
contactsYes318,454,30091Comma-separated array of Contacts IDs.

Unlike all other PUT requests, this command does not need old contact IDs to be submitted. For example, if you have a list with contacts 150, 151 and 152 and you want to add contact ID 153, you only need to submit 153 as a parameter of PUT /api/v2/lists{id}/contacts.

If successful, you will receive the standard link response:

ParameterExampleDescription
id 715List ID.
href /api/v2/lists/715Link to List.

Remove contacts from a list

To remove contacts from a list,use:

DELETE /api/v2/lists/{id}/contacts

where id is a list ID. This command has the following parameters:

NameRequired?ExampleDescription
contactsYes318,454,30091Comma-separated array of Contacts IDs.

If successful, you will receive the standard link response:

ParameterExampleDescription
id 715List ID.
href /api/v2/lists/715Link to List.

When you remove contacts from a specific list, they will be deleted permanently, unless they are first saved in another list.

The next step

You’ve now learned how to manage lists via TextMagic API. Please continue to the next section to learn how to manage Contacts.