Managing Contacts

Quick start

Using the example below, replace “API_NYCKEL” with a bearer token that you create in the user portal.

curl -X GET "https://api.ip1sms.com/v2/contacts/" \
-H "Authorization: Bearer API_NYCKEL" \
-H "Content-Type: application/json" \

call

Read a collection of contacts

Endpoint: contacts

Methodology: GET

This endpoint provides you with a collection of contacts for which you can see the contact document definition below.

Examples of calls

https://api.ip1sms.com/v2/contacts

Example of calls with filters

This collection can also be filtered by properties, metadata and/or labels using query parameters. Metadata is only available if meta is added as a query parameter.

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

Read an individual contact

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

Endpoint: contacts/{contactId}

Methodology: GET

Examples of calls

https://api.ip1sms.com/v2/contacts/606312a5d233ab8484e18404

Fields for call data

Field name Type Description Example
contactId String ID of the contact. 

606312a5d233ab8484e18404

Update a contact

Endpoint: contacts/{contactId}

Method 1: PATCH

Method 2: PUT

These endpoints allow you to update a contact and change stored data. By using the HTTP verb PATCH do a partial update, specifying any values that exist and removing any obvious null values if null values exist. If you use PUT all existing data is replaced with new data regardless of previous values.

Examples of calls

https://api.ip1sms.com/v2/contacts/606312a5d233ab8484e18404

Fields for calls

Field name Mandatory Type Description Example
id Yes String Unique ID of the contact. 
606312a5d233ab8484e18404
properties Yes Object Contains the actual information of the contact. Here fields are defined as phoneNumber, firstName and email. 
{ "phoneNumber": "+46123456789", "firstName": "Bertilsson" }
labels No, it is not. Array A list of strings used to group or categorize the contact. 
["Coworker", "Sales"]

Add/import contacts

Endpoint: contacts

Methodology: POST

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).

Examples of calls

https://api.ip1sms.com/v2/contacts

Fields for calls

Field name Mandatory Type Description Example
properties Yes Object Contains the actual information of the contact. Here fields are defined as phoneNumber, firstName and email. 
{ "phoneNumber": "+46123456789", "firstName": "Icarus" }
labels No, it is not. Array A list of strings used to group or categorize the contact. 
["Coworker", "Sales"]

Delete contact

Endpoint: POST /v2/contacts/{contactId}

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

Examples of calls

https://api.ip1sms.com/v2/contacts/606312a5d233ab8484e18404

Fields for calls

Field name Type Description Example
contactId String ID of the contact. 

606312a5d233ab8484e18404

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" ] }

Fields for response data

Field name Type Description Example
id String Unique ID of the contact in the system. Used for reference in future calls (GET, PATCH, DELETE). 
606312a5d233ab8484e18404
ownerId String ID of the account (system user) that owns and has access to the contact. 
ip1-XXXXX
properties Object A collection of the contact's raw data such as phone number, name and department. Contains the fields defined at creation/update. 
{ "phoneNumber": "+46123456789", "firstName": "Icarus" }
metadata Object System-generated information that validates and enriches the properties of the contact. Included only if the query parameter ?meta used. 
{ "phoneNumber": { "isValidPhoneNumber": "true", "parsedMSISDN": "46123456789" }
labels Array A list of strings representing the labels the connector is grouped under. 
[ "coworker", "all" ]

Fields for metadata

Property (Metadata) Type Description
isPossiblePhoneNumber String (Boolean) Indicates whether the number looks correct structurally.
isValidPhoneNumber String (Boolean) Confirms if the number is an actual existing format for the country in question.
phoneNumberType String Describes the type of subscription, e.g. MOBILE, FIXED_LINE or VOIP.
parsedMSISDN String The number formatted as MSISDN (without prefix), which is the format the system uses for mailing.
isBlocked String (Boolean) Shows if the contact is on the account's blacklist/barred list.

Code example

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

Add a contact C#

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Threading.Tasks;

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", "DIN_API_NYCKEL");

    // Create a single contact
    var contact = new Contact()
    {
        properties = new Dictionary() {
            { "phoneNumber", "+46123456789"},
            { "email", "icarus@example.com" },
            { "firstName", "Icarus" },
            { "lastName", "Sol" },
            { "department", "Sales" }
        },
        labels = new List() { "Coworker", "Sales" }
    };

    var contactList = new List { contact };

    HttpResponseMessage response = await client.PostAsJsonAsync("contacts", contactList);

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Success: Contact(s) accepted for import.");
    }
    else
    {
        string errorDetails = await response.Content.ReadAsStringAsync();
        Console.WriteLine($"Failed, {response.StatusCode}: {errorDetails}");
    }
}

public class Contact
{
    public Dictionary properties { get; set; }
    public List labels { get; set; }
}