Introductie

Zivver biedt moeiteloze beveiliging van uitgaande e-mail. Het gebruik van sterke authenticatie voor ontvangers is essentieel om de beveiliging te waarborgen en is vereist door regelgeving zoals de Nederlandse NTA7516 en het Europese eIDAS-framework. Dit betekent dat gevoelige inhoud moet worden beschermd met verificatiemethoden voor ontvangers, zoals sms of toegangscodes. Het instellen hiervan zorgt echter voor extra handelingen voor gebruikers bovenop hun normale e-mailflow.

Contact-Sync lost dit op door het mogelijk te maken om contactgegevens automatisch in Zivver te synchroniseren via een API. Je kunt vanuit bronsystemen zoals CRM-oplossingen of elektronische patiëntendossiers met deze API verbinden, zodat de informatie voor verificatiemethoden van contacten altijd up-to-date is. Met deze inrichting is sterke authenticatie beschikbaar voor gebruikers, met minimale inspanning voor zowel hen als beheerders.

Hoog-over oplossing

We maken realtime beheer van contactgegevens uit ieder bronsysteem mogelijk via een REST API. Wanneer een API-integratie tussen het systeem van de klant en Zivver is ingesteld, worden Zivver-contactgegevens automatisch beheerd.

De API-endpoint maakt het mogelijk om contacten te maken, op te halen, bij te werken en te verwijderen met de volgende informatie:

• Unieke identificatie van derde partij
• E-mailadres
• Volledige naam
• Telefoonnummer(s)
• Toegangs­code
• Toegangs­codehint

De communicatie is éénrichtingsverkeer: van het systeem van de derde partij naar Zivver, niet andersom.

Een integratie bouwen

Contact Sync biedt twee API-eindpunten aan die beveiligd zijn met een API-sleutel:

• PATCH https://app.zivver.com/api/organization/verification_suggestions/contact_sync
• GET https://app.zivver.com/api/organization/verification_suggestions/contact_sync/{third_party_id}

Een API-sleutel kan worden aangemaakt via https://app.zivver.com/organization/api-keys door een Zivver beheerder. De aangemaakte sleutel moet worden toegevoegd als een Authorization-header aan elke API-aanroep naar dit eindpunt:

• Authorization: Bearer {plaats hier de API-sleutel}

Contactpersonen kunnen in één enkele call worden toegevoegd, bijgewerkt of verwijderd, hoewel dit niet verplicht is. De structuur per contactpersoon is als volgt:

• thirdPartyId: Unieke identificatie van de contactpersoon binnen je organisatie (string, max. 255 tekens).
• fullName: Volledige naam van de contactpersoon (optioneel, string, max. 255 tekens).
• email: E-mailadres van de contactpersoon (optioneel, moet een geldig e-mailadres zijn).
• phoneNumber: Telefoonnummer van de contactpersoon (optioneel, moet een geldig nummer zijn dat tekstberichten kan ontvangen).
  Geaccepteerde formaten zijn 00<landcode><nummer>, +<landcode><nummer> of <nummer> (als het nummer met een nul begint, wordt die nul vervangen door de landcode). Bijvoorbeeld: een Nederlands nummer kan worden opgegeven als 0031612345678, +31612345678 of 0612345678.
• accessCode: Toegangscode voor de contactpersoon (optioneel, string, max. 255 tekens).
• accessCodeHint: Hint voor de toegangscode (optioneel, string, max. 255 tekens).

Contacten toevoegen

Om een nieuw contact toe te voegen, moet je minimaal de thirdPartyId, email en één van de volgende waarden opgeven: phoneNumber of accessCode. Geldige voorbeelden zijn:

{
    "thirdPartyId": "123",
    "fullName": "John Doe",
    "email": "johndoe@gmail.com",
    "accessCode": "123"
}

{
    "thirdPartyId": "johndoe.12345",
    "email": "johndoe@gmail.com",
    "phoneNumber": "+31612345678"
}

{
    "thirdPartyId": "abcdef",
    "email": "johndoe@gmail.com",
    "phoneNumber": "+31612345678",
    "accessCode": "123",
    "accessCodeHint": "The first three digits"
}

Contacten ophalen

De API maakt het mogelijk om per oproep de informatie van één contact op te halen. Om de informatie van een specifiek contact op te halen, stuur je een GET-verzoek naar:

https://app.zivver.com/api/organization/verification_suggestions/contact_sync/{third_party_id}

Vervang {third_party_id} door het ID van het contact dat je wilt ophalen. Bijvoorbeeld:

GET https://app.zivver.com/api/organization/verification_suggestions/contact_sync/johndoe.12345

Dit verzoek geeft de volgende JSON-output terug:

{
    "items": [
        {
            "thirdPartyId": "johndoe.12345",
            "fullName": "John Doe",
            "email": "johndoe@gmail.com",
            "phoneNumber": "+31612345678"
        }
    ]
}

Als er in je organisatie geen contact met dit ID bestaat, reageert de server met 404 Not Found.

Contactpersonen bijwerken

Om een bestaande contactpersoon bij te werken, moet je alle eerder opgegeven informatie opnieuw opnemen, behalve de waarde die moet worden gewijzigd. Bijvoorbeeld: als John Doe is toegevoegd met de volgende informatie:

{
  "thirdPartyId": "johndoe.12345",
  "fullName": "John Doe",
  "email": "johndoe@gmail.com",
  "phoneNumber": "+31612345678"
}

Als John Doe zijn telefoonnummer heeft gewijzigd, ziet de bijgewerkte data er zo uit:

{
  "thirdPartyId": "johndoe.12345",
  "fullName": "John Doe",
  "email": "johndoe@gmail.com",
  "phoneNumber": "+31612345677"
}

Later, als John Doe ook zijn e-mailadres heeft gewijzigd, ziet de bijgewerkte data er zo uit:

{
  "thirdPartyId": "johndoe.12345",
  "fullName": "John Doe",
  "email": "johndoe@hotmail.com",
  "phoneNumber": "+31612345677"
}

Gegevens van een klant verwijderen

In sommige gevallen moet specifieke data van een klant worden verwijderd. Bijvoorbeeld, een klant wil geen code via SMS ontvangen omdat hij of zij niet wil dat het telefoonnummer bij Zivver bekend is. In dat geval moet alleen een toegangscode worden verstrekt.

Als bijvoorbeeld de volgende gegevens zijn opgegeven:

{
    "thirdPartyId": "johndoe.12345",
    "fullName": "John Doe",
    "email": "johndoe@gmail.com",
    "phoneNumber": "+31612345678"
}

Om dit te wijzigen naar een toegangscode en het telefoonnummer uit de Zivver-database te verwijderen, moeten de volgende gegevens worden verzonden:

{
    "thirdPartyId": "johndoe.12345",
    "fullName": "John Doe",
    "email": "johndoe@gmail.com",
    "accessCode": "123"
}

Een contact verwijderen

Om de contactgegevens van een gastontvanger te verwijderen, hoeft alleen de thirdPartyId te worden opgegeven. Als bijvoorbeeld het volgende contact is toegevoegd:

{
  "thirdPartyId": "johndoe.12345",
  "fullName": "John Doe",
  "email": "johndoe@gmail.com",
  "phoneNumber": "+31612345678"
}

Dan kan het worden verwijderd door het volgende te verzenden:

{
  "thirdPartyId": "johndoe.12345"
}

Gegevens naar Zivver sturen

Het is mogelijk om de contactgegevens van elke gastontvanger afzonderlijk naar Zivver te sturen, of ze te groeperen. Het versturen van een enkel contact naar Zivver gebeurt als volgt:

{
    "items": [
        {
            "thirdPartyId": "134",
            "fullName": "John Doe",
            "email": "johnDoe@gmail.com",
            "accessCode": "123"
        }
    ]
}

Het toevoegen van de contactgegevens van een tweede gastontvanger gebeurt door een komma (,) achter het eerste datapunt te plaatsen, gevolgd door het tweede datapunt:

{
    "items": [
        {
            "thirdPartyId": "134",
            "fullName": "John Doe",
            "email": "john7@gmail.com",
            "accessCode": "123"
        },
        {
            "thirdPartyId": "135",
            "fullName": "John Doe",
            "email": "john8@gmail.com",
            "accessCode": "123"
        }
    ]
}

Extra contactpersonen kunnen op dezelfde manier worden toegevoegd: voeg een komma (,) toe na de vorige contactpersoon, gevolgd door de nieuwe contactpersoon.

Info

Je kunt maximaal 1000 contactpersonen in één enkele API-aanroep verzenden. Als je meer dan 1000 contactpersonen wilt verzenden, splits deze dan op in meerdere aanroepen.

Controleren of de gegevens correct zijn ontvangen

Wanneer Zivver contactgegevens ontvangt, valideert het eerst de gegevens en verwerkt het deze vervolgens volledig of helemaal niet. Dit betekent dat als een batch van bijvoorbeeld 5 gegevenspunten naar Zivver wordt gestuurd en één is incorrect, geen van de gegevenspunten zal worden verwerkt. In de API-respons geeft Zivver aan welke gegevens incorrect waren en voor welk contact.

Opmerking

Houd rekening met het volgende:

• Zivver maakt beslissingen op basis van de thirdPartyId van het contact. Als de thirdPartyId al bestaat en nieuwe gegevens met dezelfde thirdPartyId worden aangeleverd, worden de oude gegevens overschreven.
• Als het telefoonnummer geen sms-berichten kan ontvangen, wordt het ongeldig beschouwd en worden de contactgegevens niet opgeslagen of bijgewerkt.
• Als noch accessCode noch telefoonnummer is gedefinieerd, zijn de gegevens ongeldig omdat er geen verificatiemethode is opgegeven; in dat geval worden de contactgegevens niet opgeslagen of bijgewerkt.

Wanneer de gegevens geldig zijn, retourneert Zivver het aantal nieuw toegevoegde/bijgewerkte contacten en het aantal verwijderde contacten.

Elk individueel contact kan ook worden gecontroleerd via de GET-endpoint.

Responses from Zivver’s API

Foutmeldingen

Dubbele thirdPartyId

{
    "items": [
        {
        "thirdPartyId": "134",
        "fullName": "John Doe",
        "email": "john7@gmail.com",
        "accessCode": "123"
        },
        {
        "thirdPartyId": "134",
        "fullName": "John Doe",
        "email": "john8@gmail.com",
        "accessCode": "123"
        }
    ]
}

Dit zal resulteren in een 400-fout.

{
    "status": "duplicate third party ids were found",
    "data": [
        {
            "data": "134"
        }
   ]
}

Geen e-mailadres

{
    "items": [
        {
            "thirdPartyId": "134",
            "fullName": "John Doe",
            "accessCode": "123"
        }
    ]
}

Dit zal resulteren in een 400-fout:

{
    "status": "Invalid data found",
    "data": [
        {
            "data": "Error for thirdPartyUserId 134: Email is invalid"
        }
    ]
}

Geen telefoonnummer of access code opgegeven

{
    "items": [
        {
            "thirdPartyId": "134",
            "fullName": "John Doe",
            "email": "John7@gmail.com"
        }
    ]
}

Dit zal resulteren in de volgende foutmelding:

{
    "status": "Invalid data found",
    "data": [
        {
            "data": "Error for thirdPartyUserId 134: No phone or access code was specified"
        }
    ]
}

Succes respons

{
    "items": [
        {
            "thirdPartyId": "134",
            "fullName": "John Doe",
            "email": "john.doe@gmail.com",
            "accessCode": "123"
        },
        {
            "thirdPartyId": "135",
            "fullName": "Anne Smith",
            "email": "anne.smith@gmail.com",
            "accessCode": "123"
        },
        {
            "thirdPartyId": "136",
            "fullName": "Tom Jones",
            "email": "tom.jones@gmail.com",
            "accessCode": "123"
        }
    ]
}

Er wordt een 200-respons geretourneerd:

{
    "status": "Verification methods updated successfully",
    "data": {
        "recipientsAdded": 3,
        "recipientsDeleted": 0
    }
}