Hantera kontakter

Quick start

Använd exemplet nedan och byt ut “API_NYCKEL” mot en bearer token som du skapar i användarportalen.

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

Anrop

Läs en samling av kontakter

Endpoint: contacts

Metod: GET

Denna endpoint ger dig en samling kontakter för vilka du kan se definitionen av kontaktdokumentet nedan.

Exempel på anrop

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

Exempel på anrop med filter

Denna samling kan även filtreras efter egenskaper, metadata och/eller etiketter med hjälp av frågeparametrar. Metadata finns bara om meta läggs till som en query-parameter.

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

Läs en enskild kontakt

Denna endpoint ger dig en enda specifik kontakt. Metadata finns bara om “meta” läggs till som en query parameter

Endpoint: contacts/{contactId}

Metod: GET

Exempel på anrop

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

Fält för anropsdata

Fältnamn Typ Beskrivning Exempel
contactId String Kontaktens ID. 

606312a5d233ab8484e18404

Uppdatera en kontakt

Endpoint: contacts/{contactId}

Metod 1: PATCH

Metod 2: PUT

Med dessa endpoints kan du uppdatera en kontakt och ändra lagrad data. Genom att använda HTTP-verbet PATCH gör du en delvis uppdatering, anger eventuella värden som finns och tar bort alla tydliga null-värden om null-värden existerar. Om du använder PUT ersätts all existerande data med nya data oavsett tidigare värden.

Exempel på anrop

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

Fält för anrop

Fältnamn Obligatoriskt Typ Beskrivning Exempel
id Ja String Kontaktens unika ID. 
606312a5d233ab8484e18404
properties Ja Object Innehåller kontaktens faktiska information. Här definieras fält som phoneNumber, firstName och email. 
{ "phoneNumber": "+46123456789", "firstName": "Bertilsson" }
labels Nej Array En lista av strängar som används för att gruppera eller kategorisera kontakten. 
["Coworker", "Sales"]

Lägg till/importera kontakter

Endpoint: contacts

Metod: POST

Denna endpoint låter dig lägga till/importera nya kontakter. Den tar en samling kontaktdokument. Som standard accepteras kontakterna och importeras sedan i bakgrunden, men det kan göras direkt genom att lägga till sync som en frågeparameter. Direktimport rekommenderas endast för små samlingar av kontakter (färre än 1000).

Exempel på anrop

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

Fält för anrop

Fältnamn Obligatoriskt Typ Beskrivning Exempel
properties Ja Object Innehåller kontaktens faktiska information. Här definieras fält som phoneNumber, firstName och email. 
{ "phoneNumber": "+46123456789", "firstName": "Icarus" }
labels Nej Array En lista av strängar som används för att gruppera eller kategorisera kontakten. 
["Coworker", "Sales"]

Radera kontakter

Endpoint: DELETE contacts/{contactId}

Denna endpoint låter dig ta bort en kontakt. Det finns också en endpoint för att ta bort mer än en kontakt, se avsnittet för Massoperationer.

Exempel på anrop

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

Fält för anrop

Fältnamn Typ Beskrivning Exempel
contactId String Kontaktens ID. 

606312a5d233ab8484e18404

Responsdata-typ

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

Fält för responsdata

Fältnamn Typ Beskrivning Exempel
id String Kontaktens unika ID i systemet. Används för referens vid framtida anrop (GET, PATCH, DELETE). 
606312a5d233ab8484e18404
ownerId String ID för det konto (systemanvändare) som äger och har behörighet till kontakten. 
ip1-XXXXX
properties Object En samling av kontaktens rådata såsom telefonnummer, namn och avdelning. Innehåller de fält som definierats vid skapande/uppdatering. 
{ "phoneNumber": "+46123456789", "firstName": "Icarus" }
metadata Object Systemgenererad information som validerar och berikar kontaktens egenskaper. Inkluderas endast om query-parametern ?meta används. 
{ "phoneNumber": { "isValidPhoneNumber": "true", "parsedMSISDN": "46123456789" } }
labels Array En lista av strängar som representerar de etiketter kontakten är grupperad under. 
["Coworker", "all"]

Fält för metadata

Egenskap (Metadata) Typ Beskrivning
isPossiblePhoneNumber String (Boolean) Indikerar om numret ser korrekt ut strukturellt.
isValidPhoneNumber String (Boolean) Bekräftar om numret är ett faktiskt existerande format för det aktuella landet.
phoneNumberType String Beskriver typen av abonnemang, t.ex. MOBILE, FIXED_LINE eller VOIP.
parsedMSISDN String Numret formaterat som MSISDN (utan prefix), vilket är det format systemet använder för utskick.
isBlocked String (Boolean) Visar om kontakten finns med på kontots blacklist/spärrlista.

Kodexempel

Nedan hittar du ett enkelt kodexempel med autentisering och funktionalitet för att lägga till en kontakt.

Lägg till en kontakt i 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");

    // Skapa en enskild kontakt
    var contact = new Contact()
    {
        properties = new Dictionary<string, string>() {
            { "phoneNumber", "+46123456789"},
            { "email", "icarus@example.com" },
            { "firstName", "Icarus" },
            { "lastName", "Sol" },
            { "department", "Sales" }
        },
        labels = new List<string>() { "Coworker", "Sales" }
    };

    var contactList = new List<Contact> { 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<string, string> properties { get; set; }
    public List<string> labels { get; set; }
}