Relaties synchroniseren via de API

Met een API-koppeling komen aanmeldingen uit je webshop, CRM of website automatisch in de juiste lijst terecht.

Velden ophalen en bewaren

Eigen velden geef je mee onder custom_fields, met de custom_name van het veld als sleutel. Die naam wijkt soms af van wat je verwacht: het veld dat in de applicatie ‘Voornaam’ heet, heet in de API meestal voornaam. Haal die namen daarom één keer op en leg ze vast in je eigen code.

curl "https://api.laposta.nl/v2/field?list_id=BaImMu3JZA" \
  -u JOUW_API_SLEUTEL:

Een relatie toevoegen en bijwerken

curl https://api.laposta.nl/v2/member \
  -u JOUW_API_SLEUTEL: \
  -d list_id=BaImMu3JZA \
  -d ip=198.51.100.10 \
  -d email=nieuwe.relatie@example.net \
  -d source_url=https://example.net/aanmelden \
  -d custom_fields[voornaam]=Sanne

$laposta = new Laposta('JOUW_API_SLEUTEL');
$relatie = $laposta->memberApi()->create('BaImMu3JZA', [
    'ip' => '198.51.100.10',
    'email' => 'nieuwe.relatie@example.net',
    'source_url' => 'https://example.net/aanmelden',
    'custom_fields' => ['voornaam' => 'Sanne'],
]);

curl https://api.laposta.nl/v2/member/nieuwe.relatie@example.net \
  -u JOUW_API_SLEUTEL: \
  -d list_id=BaImMu3JZA \
  -d custom_fields[woonplaats]=Utrecht

$laposta->memberApi()->update('BaImMu3JZA', 'nieuwe.relatie@example.net', [
    'custom_fields' => ['woonplaats' => 'Utrecht'],
]);

Een relatie afmelden of verwijderen

Meldt iemand zich af via je eigen site, dan kun je de relatie het beste op afgemeld zetten. Verwijderen gebruik je alleen als iemand vraagt om zijn gegevens helemaal te wissen.

Een hele lijst in één keer synchroniseren

Synchroniseer je per relatie, dan ben je bij duizenden relaties lang bezig en loop je tegen de limiet aan. Gebruik daarvoor Lijst synchroniseren (bulk): hiermee stuur je in één aanroep tot 500.000 relaties als JSON.

{
  "actions": ["add", "update"],
  "members": [
    { "email": "eerste@example.net", "custom_fields": { "voornaam": "Sanne" } },
    { "email": "tweede@example.net" }
  ]
}

Met de PHP-bibliotheek stuur je dezelfde inhoud als een array:

$laposta->listApi()->syncMembers('BaImMu3JZA', [
    'actions' => ['add', 'update'],
    'members' => [
        ['email' => 'eerste@example.net', 'custom_fields' => ['voornaam' => 'Sanne']],
        ['email' => 'tweede@example.net'],
    ],
]);

Met de actie unsubscribe_excluded meld je iedereen af die niet in je aanlevering staat. Gebruik dit alleen als jouw systeem de bron van waarheid is, en niet als je maar een deel van je bestand aanlevert.

Waar moet je op letten?

• Een meerkeuzeveld kun je niet leegmaken door een lege lijst mee te sturen. Stuur je een lege lijst mee voor een select_multiple-veld, dan worden de bestaande keuzes niet gewist. Zie: Veelgemaakte fouten.
• Als je een label als losse tekst meestuurt, worden alle bestaande labels gewist. Stuur "labels": ["Klant"] en niet "labels": "Klant". Doe je het verkeerd, dan krijg je gewoon een 200 met edited_count terug zonder foutmelding, maar zijn alle labels leeg. Zie: Veelgemaakte fouten.
• Een onbekend id geeft geen 404, maar een 400 met code 203. Test daar dus op.
• De limiet is krapper dan je denkt bij een gratis account: 30 aanvragen per minuut. Bouw een wachtmoment in op basis van de Retry-After-header in plaats van het opnieuw te proberen.

Gerelateerde artikelen