Managing Contacts

Read a collection of contacts

Endpoint: GET /v2/contacts

This endpoint gives you a collection of contacts for which you can see the definition of the contact document below. This collection can be filtered by properties, metadata and / or labels using query parameters. Metadata is only available if meta is added as a query parameter.

Examples of filters:

https://api.ip1sms.com/v2/contacts?labels=Coworker&properties%5BphoneNumber%5D=%2B46123456789&metadata%5BphoneNumber.isBlocked%5D=false

Read an individual contact

Endpoint: Get /v2/contacts/{contactId}

This endpoint gives you a single specific contact. Metadata is only available if "meta" is added as a query parameter.

Update a contact

Endpoint: PATCH /v2/contacts/{contactId}
Endpoint: PUT /v2/contacts/{contactId}

With these endpoints you can update a contact and change stored data. The first endpoint makes a partial update, indicates any values ​​that exist and removes all clear null values ​​if any. The other replaces everything with new data regardless of previous values.

Add/import contacts

Endpoint: POST /v2/contacts

This endpoint allows you to add/import new contacts. It takes a collection of contact documents. By default, the contacts are accepted and then imported into the background, but this can be done directly by adding sync as a query parameter. Direct import is recommended only for small collections of contacts (less than 1000).

Delete contact

Endpoint: POST /v2/contacts/{contactId}

This endpoint allows you to delete a contact. There is also an endpoint for deleting more than one contact, see the section for Mass Operations.

Response data type

{ "id": "606312a5d233ab8484e18404", "ownerId": "ip1-XXXXX", "properties": { "phoneNumber": "+46123456789", "email": "icarus@example.com", "firstName": " Icarus", "lastName": "Sol", "department": "Sales" }, "metadata": { "phoneNumber": { "isPossiblePhoneNumber": "true", "isValidPhoneNumber": "true", "phoneNumberType": "MOBILE", "parsedMSISDN": "46123456789", "isBlocked": "false" } }, "labels": [ "Coworker", "all" ] }

id

Contact ID, used to refer to a specific contact.

ownerId

The account that owns the contact.

properties

A dictionary of contact properties, such as telephone numbers, names, company information, etc.

metadata

Metadata about certain properties. A dictionary with metadata properties for each metadata property. Things like validation results and blocked status

labels

A collection of labels for the connector. Most often used to categorize or group contacts.

Code example

Below you will find a simple code example including authentication for adding a contact.

Add a contact C#

using (var client = new HttpClient()) { client.BaseAddress = new Uri(https://api.ip1sms.com/v2); client.DefaultRequestHeaders.Accept.Clear(); client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json")); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "API Key"); var contact = new Contact() { properties = new Dictionary() { { "phoneNumber", "46712345678"}, {"email" , icarus@example.com}, {"firstName" , "Icarus"}, {"lastName " , "Sol"}, {"department" , "Sales"} }, labels = new List() { "Coworker", "Sales" } }; HttpResponseMessage response = await client.PostAsJsonAsync("contacts", contact); if (response.IsSuccessStatusCode) { Console.WriteLine("Late"); } else { Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync()); } } public class Contact { public Dictionary properties { get; set; } public List labels { get; set; } }