Keep Your Contacts Organized

To make sending messages easier, you can use contacts instead of phone numbers. Your contacts will be safely kept on TextMagic servers and will be available from any location. This page shows how to create, edit and delete contacts.

Get all contacts

To retrieve all contacts, use:

GET /api/v2/contacts

with the 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.
shared No 1 Determines whether the contacts in shared lists should be included in the response. The default is 0 (false).

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 next section for contact resource format details.

Get the details of a specific contact

To get a single contact, use:

GET /api/v2/contacts/{id}

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

You will receive a response in the following format:

Parameter Example Description
id 27074 Contact ID.
firstName Charles Contact first name.
lastName Conway Contact last name.
companyName Example Ltd. Company name.
phone 447860021130 Phone number in E.164 format.
email charles@example.com Contact email address.
country Standard country object Contact country.
customFields Array of customField objects See Custom Fields section.

Country resource structure

You will receive a response in the following format:

Parameter Example Description
id ME Two-letter ISO country code.
name Montenegro Country name.

Get all the lists in which the contact is included

To get all lists that the contact is assigned to, use:

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

where id is a contact ID, with these parameters:

Name Required? Example Description
page No 3 Fetch specified results page. Default is 1.
limit No 25 How many results to return. 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 the Lists chapter for list resource format details.

Add a new contact

To add a new contact, use:

POST /api/v2/contacts

with the following parameters:

Name Required? Example Description
phone Yes 447860021130 Phone number in E.164 format.
lists Yes 10541,18599 Contact list ID. Each contact must be assigned to at least one list.
firstName No Charles Contact first name.
lastName No Conway Contact last name.
companyName No Example Ltd. Company name.
email No charles@example.com Contact email address.

If successful, you will receive the standard link response:

Parameter Example Description
id 27074 Contact ID.
href /api/v2/contacts/27074 Link to Contact.

Edit a contact

To modify contact metadata, use:

PUT /api/v2/contacts/{id}

where id is contact ID, use the same parameters as when creating a contact:

Name Required? Example Description
phone Yes 447860021130 Phone number in E.164 format.
lists Yes 10541,18599 Comma-separated list ID. Each contact must be assigned to at least one list.
firstName No Charles Contact first name.
lastName No Conway Contact last name.
companyName No Example Ltd. Company name.
email No charles@example.com Contact email address.

If successful, you will receive the standard link response:

Parameter Example Description
id 27074 Contact ID.
href /api/v2/contacts/27074 Link to Contact.

Delete a contact

To delete a contact, use the following command:

DELETE /api/v2/contacts/{id}

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

This command removes your contact completely. If it was assigned or saved to a shared list, it will disappear from there too. If you only need to remove a contact from selected lists, instead use the Contact assignment command in the Lists section rather than deleting the contact.

Get all unsubscribed contacts

When one of your message recipients sends a request with one of the STOP-words, they will be immediately opted-out of your send lists and their contact status will change to an unsubscribed contact. To retrieve information on all contacts who have unsubscribed, use:

GET /api/v2/unsubscribers

with the parameters:

Name Required? Example Description
page No 3 Fetch specified results page. Default is 1.
limit No 25 How many results to return. 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 unsubscriber resources See next section for unsubscriber resource format details.

Get the details of a specific unsubscribed contact

To get a single contact, use:

GET /api/v2/unsubscriber/{id}

where id is an unsubscribed contact ID. Note, this command has no parameters.

You will receive a response in the following format:

Parameter Example Description
id 27074 Unsubscribed contact ID.
firstName Charles Unsubscribed contact first name.
lastName Conway Unsubscribed contact last name.
phone 447860021130 Phone number in E.164 format.
unsubscribeTime 2015-01-09T18:59:46+0000 Time when contact has been opted-out.

Manually unsubscribe a contact

To unsubscribe a contact manually, use:

POST /api/v2/unsubscribers

with the following parameters:

Name Required? Example Description
phone Yes 447860021130 Phone number in E.164 format.

If successful, you will receive the standard link response:

Parameter Example Description
id 27074 Unsubscribed contact ID.
href /api/v2/unsubscribers/27074 Link to the Unsubscribed contact.

Please note, if you unsubscribe a contact, this action cannot be reversed.

The next step

Now you’ve learned how to manage contacts via TextMagic API, in the next section, we will show how you can store extra contact data in custom fields.