Agreli
Probeer gratis
Docs / Snelstart

Snelstart

In zes stappen van een testsleutel naar een onboarding die je in de sandbox helemaal afrondt. Alle voorbeelden werken met een testsleutel en fictieve gegevens.

MarkdownOpenAPI

1. Maak een testsleutel

Maak in de app bij Instellingen → API en webhooks een testsleutel (hrs_test_…). Je ziet de sleutel één keer; daarna bewaren we alleen een hash. Een testsleutel werkt in je sandbox: een aparte organisatie met fictieve medewerkers, opgevangen mails en sms'jes en een gesimuleerde salarisverwerking. Alleen een eigenaar of manager kan een testsleutel maken.

Terminal
export AGRELI_API_KEY="hrs_test_…"

Kies bij het maken de rechten die je nodig hebt. Voor deze snelstart zijn dat organization:read, onboardings:read, onboardings:write en webhooks:manage.

2. Haal een vestiging en een template op

Een onboarding heeft een location_id en een template_id nodig. Die staan bij je organisatie:

Terminal
curl https://app.agreli.nl/api/public/v1/organization \
  -H "Authorization: Bearer $AGRELI_API_KEY"
Antwoord (ingekort)
{
  "id": "org_…",
  "name": "Brasserie De Haven (sandbox)",
  "locations": [{ "id": "loc_…", "name": "…", "city": "…" }],
  "templates": [{ "id": "t1", "name": "Oproepkracht bediening", "contract_type": "on_call", "cao": "Cao Horeca" }]
}

3. Maak een onboarding aan

Stuur de gegevens van de nieuwe medewerker en het dienstverband. Met een Idempotency-Key is opnieuw proberen na een time-out veilig: hetzelfde verzoek geeft hetzelfde antwoord.

Terminal
curl -X POST https://app.agreli.nl/api/public/v1/onboardings \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Idempotency-Key: 5d1f0b6e-4711-4c2a-9b1e-2f6f0e9a7c31" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "sollicitant-4711",
    "employee": { "first_name": "Sam", "last_name": "Jansen", "email": "sam@example.com" },
    "employment": {
      "position": "Bediening",
      "start_date": "2026-12-01",
      "location_id": "loc_…",
      "template_id": "t1",
      "hours_per_week": 16,
      "hourly_wage_cents": 1450
    },
    "options": { "return_url": "https://jouwapp.nl/onboarding/klaar" }
  }'

Hetzelfde in TypeScript, met fetch (Node 18 of nieuwer). Roep de API alleen aan vanaf je server: een API-sleutel hoort niet in de browser.

agreli.ts
const BASE = "https://app.agreli.nl/api/public";

export async function maakOnboarding(sollicitant: { id: string; voornaam: string; achternaam: string; email: string }, idempotencyKey: string) {
  const res = await fetch(`${BASE}/v1/onboardings`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AGRELI_API_KEY}`,
      "Content-Type": "application/json",
      // Bewaar deze sleutel bij je eigen record: een herhaling moet dezelfde sleutel gebruiken.
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify({
      reference: `sollicitant-${sollicitant.id}`,
      employee: { first_name: sollicitant.voornaam, last_name: sollicitant.achternaam, email: sollicitant.email },
      employment: {
        position: "Bediening",
        start_date: "2026-12-01",
        location_id: "loc_…",
        template_id: "t1",
        hours_per_week: 16,
        hourly_wage_cents: 1450,
      },
      options: { return_url: "https://jouwapp.nl/onboarding/klaar" },
    }),
  });
  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(`${res.status} ${error.type}/${error.code}: ${error.message} (${error.request_id})`);
  }
  return (await res.json()) as { id: string; status: string; hosted_url: string; expires_at: string; invitation_sent: boolean };
}
Antwoord 201
{
  "id": "onb_…",
  "object": "onboarding",
  "status": "pending_employee",
  "hosted_url": "https://app.agreli.nl/m/…",
  "expires_at": "2026-10-26T12:00:00.000Z",
  "invitation_sent": false,
  "reference": "sollicitant-4711",
  "metadata": {}
}

4. Stuur de medewerker naar de hosted_url

Stuur de medewerker vanuit je eigen software naar de hosted_url, bijvoorbeeld met een knop of een redirect. De medewerker vraagt daar een eenmalige code per mail of sms aan; de link alleen geeft geen toegang. Liever dat wij de link mailen? Zet dan options.send_invitation op true.

  • De link is standaard 336 uur (14 dagen) geldig. Kies met options.expires_in_hours een waarde van 1 tot 336.
  • Is de link verlopen of kwijt, vraag dan een nieuwe aan met POST /v1/onboardings/{id}/hosted-link. De vorige vervalt direct.
  • Na het versturen toont de statuspagina een knop terug naar je return_url. Dat moet een https-adres zijn op een van je toegestane domeinen; zet die eerst in het developer dashboard.
  • Liever in je eigen site? Toon de onboarding in een iframe met embed.js.

5. Volg de voortgang

Registreer een webhookadres. Het geheim (whsec_…) staat alleen in dit antwoord; bewaar het om handtekeningen te controleren.

Terminal
curl -X POST https://app.agreli.nl/api/public/v1/webhooks \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://jouwapp.nl/webhooks/agreli", "events": ["onboarding.employee_submitted", "onboarding.completed"] }'

Elk bericht bevat alleen id's, je eigen reference, je metadata en de data_version, nooit persoonsgegevens. Details haal je op met de API:

Terminal
curl https://app.agreli.nl/api/public/v1/onboardings/onb_… \
  -H "Authorization: Bearer $AGRELI_API_KEY"

Het veld status zegt waar de onboarding staat en waiting_on wie er aan zet is. Zie Webhooks voor de gebeurtenissen en het controleren van de handtekening.

6. Speel de rest na in de sandbox

In de sandbox hoef je niet zelf als medewerker, controleur en werkgever op te treden. Elke aanroep speelt de volgende stap na: gegevens invullen, goedkeuren met de testgebruikers, contract versturen, beide handtekeningen en de gesimuleerde salarisverwerking.

Terminal
curl -X POST https://app.agreli.nl/api/public/v1/sandbox/onboardings/onb_…/advance \
  -H "Authorization: Bearer $AGRELI_API_KEY"
Antwoord (ingekort)
{ "step": "employee_submitted", "onboarding": { "id": "onb_…", "status": "in_review", "waiting_on": ["manager", "payroll_reviewer"] } }

Herhaal tot step gelijk is aan payroll_completed. Bij elke stap komen de bijbehorende webhooks binnen. Meer in Sandbox en livegang.

Volgende stappen