> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.laposta.org/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.laposta.org/_mcp/server.

# Relaties synchroniseren via de API

> Houd je lijst gelijk aan je webshop of CRM: toevoegen, bijwerken, afmelden en fouten afvangen.

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`**

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

**`PHP`**

```php title="PHP"
$laposta = new Laposta('JOUW_API_SLEUTEL');
$velden = $laposta->fieldApi()->all('BaImMu3JZA');
```

> **Tip**
>
> Haal de veldnamen niet op bij elke aanmelding, maar bewaar ze in je eigen systeem en ververs ze bijvoorbeeld één keer per dag. Velden veranderen zelden, en elke aanroep telt mee voor je limiet van 30 aanvragen per minuut (120 op een betaald account). Bij een drukke webshop ben je die anders zo kwijt aan het opvragen van gegevens die je al had.

## Een relatie toevoegen en bijwerken

#### Stuur het e-mailadres, het IP-adres en je eigen velden mee

Het IP-adres is verplicht: daarmee leg je vast waar de aanmelding vandaan kwam. Dat heb je nodig om aan te tonen dat iemand zich zelf heeft aangemeld.

**`curl`**

```bash title="curl"
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
```

**`PHP`**

```php title="PHP"
$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'],
]);
```

#### Vang de melding af als het adres al bestaat

Staat het adres al in de lijst, dan krijg je een `400` met foutcode `204`. Wil je in dat geval de bestaande gegevens bijwerken in plaats van een foutmelding krijgen, zet dan `options[upsert]` op `true`.

#### Werk gegevens later bij

Doe een POST op de relatie zelf om gegevens bij te werken. Je hoeft alleen mee te sturen wat er verandert. De andere velden blijven ongewijzigd. Je kunt daarbij het `member_id` gebruiken, maar ook gewoon het e-mailadres.

**`curl`**

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

**`PHP`**

```php title="PHP"
$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.

| Wat je doet | Hoe                                                  | Wat er gebeurt                                                                                                                  |
| ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Afmelden    | wijzigen met `state` op `unsubscribed`               | De relatie blijft bestaan en ontvangt niets meer. Meldt iemand zich later opnieuw aan, dan zie je dat terug in de geschiedenis. |
| Verwijderen | [Relatie verwijderen](/relaties/relatie-verwijderen) | De relatie verdwijnt definitief, inclusief de geschiedenis.                                                                     |

## 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)](/lijsten/lijst-synchroniseren-bulk): hiermee stuur je in één aanroep tot 500.000 relaties als JSON.

**`JSON`**

```json title="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:

**`PHP`**

```php title="PHP"
$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.

> **Warning**
>
> Bulk staat niet standaard aan. Het is alleen beschikbaar voor betaalde accounts, en Laposta moet het per account inschakelen. Krijg je een `401` met "Not permitted to issue bulk requests (1)", neem dan contact op met de helpdesk via [helpdesk@laposta.nl](mailto:helpdesk@laposta.nl) en vermeld je accountnummer.

## 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](/veelgemaakte-fouten-met-de-api).
* 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](/veelgemaakte-fouten-met-de-api).
* 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

#### [Webhooks gebruiken voor wijzigingen in een lijst](/webhooks-gebruiken)

Met een webhook geeft Laposta een seintje aan jouw systeem zodra iemand zich aanmeldt…

#### [Wat zijn veelgemaakte fouten met de API?](/veelgemaakte-fouten-met-de-api)

Valkuilen bij koppelingen met de Laposta API, met de foutmelding die je krijgt en de…

#### [Wat zijn de limieten en foutmeldingen van de API?](/api-limieten-en-foutmeldingen)

Hoeveel aanvragen de API per minuut toestaat en welke status- en foutcodes je kunt…