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:

Name Required? Example Description
page No 3 Fetch the specified results page. The default is 1.
limit No 25 The number of results per page. The default is 10.

You will receive the standard paginated response:

Parameter Example Description
page 3 The current fetched page.
limit 25 The number of results per page.
pageCount 150 The total number of pages.
resources Array of list resources See 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:

Parameter Example Description
id 715 List ID.
name Private list List name.
description Private contacts of C. R. Conway List description.
shared false Is 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:

Name Required? Examples Description
name Yes Private list List name.
shared No 0 Should new list be shared among all the sub-accounts? The default is 0 (false).

If successful, you will receive the standard link response:

Parameter Example Description
id 715 List ID.
href /api/v2/lists/715 Link 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:

Name Required? Example Description
name Yes Private list List name.
shared No 0 Make this list shared or not? The default is 0 (false).

If successful, you will receive the standard link response:

Parameter Example Description
id 715 List ID.
href /api/v2/lists/715 Link 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:

Name Required? Example Description
page No 3 Fetch specified results page. The default is 1.
limit No 25 How many results to return. The default is 10.

You will receive the standard paginated response:

Parameter Example Description
page 3 The current fetched page.
limit 25 The number of results per page.
pageCount 150 The total number of pages.
resources Array 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:

Name Required? Example Description
contacts Yes 318,454,30091 Comma-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:

Parameter Example Description
id 715 List ID.
href /api/v2/lists/715 Link 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:

Name Required? Example Description
contacts Yes 318,454,30091 Comma-separated array of Contacts IDs.

If successful, you will receive the standard link response:

Parameter Example Description
id 715 List ID.
href /api/v2/lists/715 Link 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.