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:

NameRequired?ExampleDescription
pageNo3Fetch the specified results page. The default is 1.
limitNo25The number of results per page. The default is 10.
sharedNo1Determines whether the contacts in shared lists should be included in the response. The default is 0 (false).

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 resourcesSee 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:

ParameterExampleDescription
id27074Contact ID.
firstName Charles Contact first name.
lastNameConwayContact last name.
companyNameExample Ltd.Company name.
phone 447860021130 Phone number in E.164 format.
emailcharles@example.comContact email address.
countryStandard country objectContact country.
customFieldsArray of customField objectsSee Custom Fields section.

Country resource structure

You will receive a response in the following format:

ParameterExampleDescription
idMETwo-letter ISO country code.
nameMontenegroCountry 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:

NameRequired?ExampleDescription
pageNo3Fetch specified results page. Default is 1.
limitNo25How many results to return. 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 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:

NameRequired?ExampleDescription
phoneYes 447860021130 Phone number in E.164 format.
listsYes 10541,18599Contact list ID. Each contact must be assigned to at least one list.
firstNameNoCharlesContact first name.
lastNameNoConwayContact last name.
companyNameNoExample Ltd.Company name.
emailNocharles@example.comContact email address.

If successful, you will receive the standard link response:

ParameterExampleDescription
id27074Contact ID.
href /api/v2/contacts/27074Link 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:

NameRequired?ExampleDescription
phoneYes 447860021130 Phone number in E.164 format.
listsYes10541,18599Comma-separated list ID. Each contact must be assigned to at least one list.
firstNameNoCharlesContact first name.
lastNameNoConwayContact last name.
companyNameNoExample Ltd.Company name.
emailNo charles@example.comContact email address.

If successful, you will receive the standard link response:

ParameterExampleDescription
id27074Contact ID.
href/api/v2/contacts/27074Link 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:

NameRequired?ExampleDescription
pageNo3Fetch specified results page. Default is 1.
limitNo25How many results to return. 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 unsubscriber resourcesSee 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:

ParameterExampleDescription
id27074Unsubscribed contact ID.
firstName Charles Unsubscribed contact first name.
lastNameConwayUnsubscribed contact last name.
phone 447860021130 Phone number in E.164 format.
unsubscribeTime2015-01-09T18:59:46+0000Time when contact has been opted-out.

Manually unsubscribe a contact

To unsubscribe a contact manually, use:

POST /api/v2/unsubscribers

with the following parameters:

NameRequired?ExampleDescription
phoneYes 447860021130 Phone number in E.164 format.

If successful, you will receive the standard link response:

ParameterExampleDescription
id27074Unsubscribed contact ID.
href /api/v2/unsubscribers/27074Link 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.