Contacts¶
The Contacts resource allows you to:
- Add a contact via POST
- Collect contact(s) data via GET
- Edit a contact via PUT
- Delete a contact via DELETE
Adding a Contact¶
To add a contact you make a POST request to the Contacts resource.
The POST url is: https://api.sendhub.com/v1/contacts/?username=USERNAME&api_key=APIKEY
Where:
- USERNAME - is your SendHub username.
- APIKEY - is your api key which can be found on the settings page.
You’ll also need to pass Headers and Data.
Headers:
Content-Type: application/json
Data:
For example to add the contact ‘John Doe’ you would POST:
{
"name": "John Doe",
"number": "+16501234567"
}
Note
Name and number are required fields for contact addition. Only 10 digit numbers are accepted.
Therefore, to add a contact through the API using cURL:
curl -H "Content-Type: application/json" -X POST --data '{"name" : "John Doe", "number": "+16501234567"}' 'https://api.sendhub.com/v1/contacts/?username=USERNAME&api_key=APIKEY'
If your contact is accepted you’ll get a 201 Created status and a data response similar to this:
{
"blocked": false,
"date_created": "2012-05-31T17:44:17.406108",
"date_modified": "2012-05-31T17:44:17.406139",
"groups": [],
"id": "22413",
"name": "John Doe",
"number": "+16501234567",
"resource_uri": "/api/v1/contacts/22413/"
}
Adding a Contact with Additional Data¶
You can also add additional data when creating a contact and add the contact to a relevant group(s). To add the contact to a group, include the group variable in your DATA with a list of the relevant group ids. To add additional data to the contact, simply add your own field names and content to the DATA.
For example, to add a new contact to 2 groups and include their address you could POST the following:
{
"name": "John Doe",
"number": "+16501234567",
"groups": [11,12],
"address": "1 Infinite Loop",
"city": "Cupertino",
"zip": "95014"
}
If your contact is accepted you’ll again get a 201 Created status and a data response similar to this:
{
"address": "1 Infinite Loop",
"blocked": false,
"city": "Cupertino",
"date_created": "2012-05-31T17:44:17.406108",
"date_modified": "2012-05-31T17:44:17.406139",
"groups": [
"/api/v1/groups/11/",
"/api/v1/groups/12/",
],
"id": "22413",
"name": "John Doe",
"number": "+16501234567",
"resource_uri": "/api/v1/contacts/22413/",
"zip": "95014"
}
Available Fields:
| Name | Explanation |
|---|---|
| id | The unique identifier of your new contact. Read only. |
| name | The name of your new contact. |
| number | The new contact’s cell phone number. |
| groups | The list of groups (ids) to which this contact will be added. |
| resource_uri | The uri to access this contact’s data. |
| blocked | Boolean. True if this contact has blocked your number. Read only. |
| date_created | The UTC time this contact was created. Read only. |
| date_modified | The UTC time this contact was last changed. Read only. |
Collecting Contacts Data¶
You can collect contacts data in bulk or individually.
To collect a list of contacts you make a GET request to the Contacts resource:
https://api.sendhub.com/v1/contacts/?username=USERNAME&api_key=APIKEY
If your request is accepted you’ll get a 200 Ok status and a data response similar to this:
{
"meta": {
"limit": 20,
"next": null,
"offset": 0,
"previous": null,
"total_count": 1
},
"objects": [
{
"blocked": false,
"date_created": "2012-05-31T17:44:17.406108",
"date_modified": "2012-05-31T17:44:17.406139",
"groups": [],
"id": "1111",
"name": "John Doe",
"number": "+15555555555",
"resource_uri": "/api/v1/contacts/1111/"
}
]
}
To collect an individual contact you make a GET request to the Contacts resource, including the contact’s ID:
https://api.sendhub.com/v1/contacts/CONTACT_ID/?username=USERNAME&api_key=APIKEY
Where:
- CONTACT_ID - is the contact’s id. This can be obtained from the id or resource_uri field.
If your request is accepted you’ll get a 200 Ok status and a data response similar to this:
{
"blocked": false,
"date_created": "2012-05-31T17:44:17.406108",
"date_modified": "2012-05-31T17:44:17.406139",
"groups": [],
"id": "22413",
"name": "John Doe",
"number": "+16501234567",
"resource_uri": "/api/v1/contacts/22413/"
}
Editing a Contact¶
To edit a contact you make a PUT request to the Contacts resource, with the contact’s id.
https://api.sendhub.com/v1/contacts/CONTACT_ID/?username=USERNAME&api_key=APIKEY
You’ll also need to pass Headers and Data.
Headers:
Content-Type: application/json
Data:
The following request changes the name of the contact from ‘John Doe’ to ‘Jesse Doe’ but retains the same number.
{
"id": "22413",
"name": "Jesse Doe",
"number": "+16501234567"
}
If your request is accepted you’ll get a 202 Accepted status and a data response similar to this:
{
"blocked": false,
"date_created": "2012-05-31T17:44:17.406108",
"date_modified": "2012-05-31T19:36:43.932126",
"groups": [],
"id": "22413",
"name": "Jesse Doe",
"number": "+16501234567",
"resource_uri": "/api/v1/contacts/22413/"
}
Note
ID, name and number are required fields for contact editing. Only 10 digit numbers are accepted.
Note
Editing a contact will update the date_modified field to the current time. This field also gets updated when a user changes groups.
Deleting a Contact¶
To delete a contact you make a DELETE request to the Contacts resource, with the contact’s id.
https://api.sendhub.com/v1/contacts/CONTACT_ID/?username=USERNAME&api_key=APIKEY
Where:
- CONTACT_ID - is the contact’s id. This can be obtained from the id or resource_uri field.
Therefore, to delete a contact through the API using cURL:
curl -H "Content-Type: application/json" -X DELETE 'https://api.sendhub.com/v1/contacts/CONTACT_ID/?username=USERNAME&api_key=APIKEY'
If your request is accepted you’ll get a 204 No Content status, indicating the contact has been successfully deleted.