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://ip1-api-gateway-dev.azure-api.net/v2/contacts?labels=Coworker&properties%5BphoneNumber%5D=%2B46123456789&metadata%5BphoneNumber.isBlocked%5D=false

Read an individual contact

Endpoint: Get /v2/contacts/{contactId}

Denna endpoint ger dig en enda specifik kontakt. Metadata finns bara om “meta” läggs till som en 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("Sent");
    }
    else
    {
        Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }
}
    
public class Contact
{
    public Dictionary properties { get; set; }
    public List labels { get; set; }
}