Agreli
Probeer gratis
Docs / API-referentie

API-referentie

Alle endpoints van de Agreli API, met het benodigde recht, de parameters en voorbeelden. Deze pagina wordt gegenereerd uit de OpenAPI-specificatie; de omschrijvingen komen daar letterlijk uit.

MarkdownOpenAPI

Agreli API 1.0.0. Basis-URL: https://app.agreli.nl/api/public. OpenAPI 3.1: https://app.agreli.nl/api/public/v1/openapi.json.

Overzicht

MethodePadRechtWat
GET/v1/organizationsorganization:readOrganisaties die deze sleutel mag gebruiken
GET/v1/organizationorganization:readOrganisatie, vestigingen, templates en toegestane domeinen
GET/v1/onboardingsonboardings:readOnboardings
POST/v1/onboardingsonboardings:writeHosted onboarding aanmaken
GET/v1/onboardings/{id}onboardings:readEén onboarding met stappen en documenten
PATCH/v1/onboardings/{id}onboardings:writeReferentie en metadata bijwerken
POST/v1/onboardings/{id}/hosted-linkonboardings:writeNieuwe hosted link (de vorige vervalt)
POST/v1/onboardings/{id}/cancelonboardings:writeAnnuleren
POST/v1/onboardings/{id}/identity-verificationapprovals:writeID-controle bevestigen (als manager)
POST/v1/onboardings/{id}/approvalsapprovals:writeGoedkeuren als de eigenaar van de sleutel
POST/v1/onboardings/{id}/contractcontracts:writeContract maken en ter ondertekening versturen
GET/v1/onboardings/{id}/documentsdocuments:readDocumenten
GET/v1/onboardings/{id}/documents/{documentId}documents:readDocument downloaden
GET/v1/employeesemployees:readMedewerkers
GET/v1/approvalsapprovals:readWat jij nu kunt goedkeuren
GET/v1/integrationsintegrations:readKoppelingen en synchronisatiestatus
GET/v1/webhookswebhooks:manageWebhookadressen
POST/v1/webhookswebhooks:manageWebhookadres toevoegen
GET/v1/webhooks/{id}webhooks:manageEén webhookadres met recente afleveringen
DELETE/v1/webhooks/{id}webhooks:manageVerwijderen
POST/v1/webhooks/{id}/testwebhooks:manageTestbericht (ping) sturen
POST/v1/webhooks/{id}/rotate-secretwebhooks:manageGeheim vernieuwen
GET/v1/webhooks/{id}/deliverieswebhooks:manageAfleverlog van één adres
POST/v1/webhooks/{id}/deliveries/{deliveryId}/retrywebhooks:manageAflevering opnieuw versturen
GET/v1/eventsonboardings:readGebeurtenissen (om gemiste webhooks na te lopen)
POST/v1/sandbox/onboardings/{id}/advanceonboardings:writeSandbox: volgende stap naspelen

Het onboarding-object

GET /v1/onboardings/{id} en de schrijfacties op een onboarding geven dit object terug. In lijsten ontbreken steps, documents, email, phone en de arbeidsvoorwaarden. Bij één onboarding staan email, phone en de arbeidsvoorwaarden er alleen in als de sleutel het dossier mag openen.

JSON
{
  "id": "onb_…",
  "object": "onboarding",
  "status": "in_review",
  "waiting_on": ["payroll_reviewer"],
  "returned": false,
  "employee": { "id": "emp_…", "first_name": "Sam", "last_name": "Jansen", "email": "sam@example.com", "phone": null },
  "employment": { "position": "Bediening", "location_id": "loc_…", "start_date": "2026-12-01", "contract_type": "on_call", "hours_per_week": 16, "hourly_wage_cents": 1450 },
  "workflow": { "template_id": "t1", "version": 1 },
  "data_version": 2,
  "approvals": {
    "required": ["manager", "payroll_reviewer"],
    "given": [{ "role": "manager", "valid": true, "data_version": 2, "at": "2026-11-20T10:15:00.000Z" }]
  },
  "contract": { "status": "none" },
  "payroll": null,
  "hosted_link": { "status": "activated", "expires_at": "2026-10-26T12:00:00.000Z", "activated": true },
  "reference": "sollicitant-4711",
  "metadata": { "vacature_id": "vac-311" },
  "return_url": "https://jouwapp.nl/onboarding/klaar",
  "source": "api",
  "created_at": "2026-10-12T12:00:00.000Z",
  "updated_at": "2026-11-20T10:15:00.000Z",
  "steps": [{ "id": "…", "phase": "gegevens", "kind": "document", "title": "…", "applies": true, "done": true }],
  "documents": [{ "id": "doc_…", "kind": "passport", "title": null, "uploaded_at": "2026-11-20T09:58:00.000Z", "downloadable": false }]
}
  • contract.status: none, sent, signed_by_employee of signed.
  • hosted_link.status: open, activated of revoked.
  • payroll: null tot de verwerking begint; daarna status, external_id en error_code.
  • data_version gaat omhoog als gegevens of voorwaarden veranderen. Een goedkeuring geldt voor één versie.

Dit object is breder dan het schema Onboarding in de OpenAPI-spec; de velden hierboven komen uit de API zelf.

Statussen

StatusBetekenisAan zet (waiting_on)
pending_employeeUitgenodigd of bezig met invullen.employee
in_reviewGegevens verstuurd; de controle (vierogen) loopt.de rollen die nog moeten goedkeuren, of manager na terugsturen
contract_readyGoedgekeurd; het contract kan worden gemaakt en verstuurd.manager
awaiting_employee_signatureContract verstuurd; wacht op de handtekening van de medewerker.employee
awaiting_employer_signatureDe medewerker heeft getekend; wacht op de werkgever.manager
processingGetekend; de verwerking in de salarisadministratie loopt.system
action_requiredDe verwerking in de salarisadministratie vraagt om een handeling.manager, payroll_reviewer
completedAfgerond.niemand
cancelledGeannuleerd.niemand

Endpoints

GET/v1/organizations

Organisaties die deze sleutel mag gebruiken.

Een werkgeverssleutel: de eigen organisatie. Een sleutel van een API-partner: alle werkgevers die de partner hebben toegelaten, met de rechten die ze gaven. Gebruik het id in de kop Agreli-Organization.

Recht: organization:read

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

Antwoord 200 (OK):

JSON
{
  "object": "list",
  "data": [
    {
      "id": "org_…",
      "object": "organization",
      "name": "…",
      "permissions": [
        "…"
      ]
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

GET/v1/organization

Organisatie, vestigingen, templates en toegestane domeinen.

Recht: organization:read

ParameterInTypeVerplichtOmschrijving
Agreli-OrganizationheaderstringneeAlleen voor sleutels van een API-partner: de werkgever namens wie je werkt. Verplicht als de partner meer dan één werkgever heeft.
Terminal
curl https://app.agreli.nl/api/public/v1/organization \
  -H "Authorization: Bearer $AGRELI_API_KEY"

Antwoord 200 (OK):

JSON
{
  "id": "org_…",
  "name": "Brasserie De Haven",
  "locations": [
    {
      "id": "loc_…",
      "name": "De Haven Centrum",
      "city": "Amsterdam"
    }
  ],
  "templates": [
    {
      "id": "t1",
      "name": "Oproepkracht bediening",
      "contract_type": "on_call",
      "cao": "Cao Horeca"
    }
  ],
  "branding": {
    "color": "#0f5132",
    "logo_url": null
  },
  "allowed_origins": [
    "https://jouwapp.nl"
  ]
}

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

GET/v1/onboardings

Onboardings.

Nieuwste eerst, ook geannuleerde (filter met status). Een API-partner ziet alleen de onboardings die via zijn eigen sleutels liepen.

Recht: onboardings:read

ParameterInTypeVerplichtOmschrijving
statusquerypending_employee, in_review, contract_ready, awaiting_employee_signature, awaiting_employer_signature, processing, action_required, completed, cancellednee—
referencequerystringnee—
updated_sincequerystring (date-time)nee—
limitqueryintegernee1 tot 100. Standaard 25.
starting_afterquerystringnee—
Terminal
curl https://app.agreli.nl/api/public/v1/onboardings \
  -H "Authorization: Bearer $AGRELI_API_KEY"

Antwoord 200 (OK):

JSON
{
  "object": "list",
  "data": [
    {
      "id": "onb_…",
      "status": "pending_employee",
      "waiting_on": [
        "employee"
      ],
      "employee": {},
      "employment": {},
      "data_version": 1,
      "approvals": {},
      "contract": {},
      "payroll": null,
      "hosted_link": null,
      "reference": "sollicitant-4711",
      "metadata": {
        "vacature_id": "vac-311"
      },
      "return_url": "https://jouwapp.nl/onboarding/klaar",
      "source": "api",
      "created_at": "2026-10-12T12:00:00.000Z",
      "updated_at": "2026-10-12T12:00:00.000Z",
      "steps": [],
      "documents": [
        {
          "id": "doc_…",
          "kind": "contract_signed",
          "title": "Arbeidsovereenkomst",
          "uploaded_at": "2026-10-12T12:00:00.000Z",
          "downloadable": true
        }
      ]
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Een {} in dit voorbeeld is een object waarvan de spec de velden niet vastlegt.

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

POST/v1/onboardings

Hosted onboarding aanmaken.

Alleen met een lopende proef of een abonnement van wie betaalt (anders 403 subscription_required).

Recht: onboardings:write

ParameterInTypeVerplichtOmschrijving
Idempotency-KeyheaderstringneeZelfde sleutel en inhoud binnen 24 uur geeft hetzelfde antwoord. Loopt het eerste verzoek nog, dan 409 idempotency_in_progress: probeer het zo opnieuw. Hooguit 200 tekens.

Request body (JSON):

VeldTypeVerplichtOmschrijving
referencestringneeJe eigen kenmerk; komt terug in de API en in webhooks. Hooguit 200 tekens.
metadataobject (sleutel → string | number | boolean)neeJe eigen kenmerken, bijvoorbeeld een vacature-id (sleutels: letters, cijfers, _ . -, hooguit 40 tekens; tekst hooguit 500). Komt terug in de API en in webhooks. Geen persoonsgegevens: e-mail, IBAN, BSN en telefoonnummers worden geweigerd (metadata_personal_data). Hooguit 20 sleutels.
employeeobjectja—
employee.first_namestringja—
employee.last_namestringja—
employee.emailstring (email)ja—
employee.phonestringnee—
employmentobjectja—
employment.positionstringja—
employment.start_datestring (date)ja—
employment.location_idstringja—
employment.template_idstringja—
employment.contract_typeon_call, fixed_term, permanentneeStandaard die van de template.
employment.hours_per_weeknumberja0 tot 60.
employment.hourly_wage_centsintegerjaMinimaal 1.
optionsobjectnee—
options.send_invitationbooleanneetrue: wij mailen de medewerker de link. false: jij stuurt de medewerker naar hosted_url. Standaard false.
options.expires_in_hoursintegernee1 tot 336. Standaard 336.
options.return_urlstring (uri)neeNa afronden kan de medewerker hierheen terug. Alleen https, op een domein uit allowed_origins (van de werkgever, of van de API-partner); anders 422 return_url_not_allowed.
Terminal
curl -X POST https://app.agreli.nl/api/public/v1/onboardings \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "sollicitant-4711",
    "metadata": {
      "vacature_id": "vac-311"
    },
    "employee": {
      "first_name": "Sam",
      "last_name": "Jansen",
      "email": "sam@example.com",
      "phone": "+31 6 12345678"
    },
    "employment": {
      "position": "Bediening",
      "start_date": "2026-12-01",
      "location_id": "loc_…",
      "template_id": "t1",
      "contract_type": "on_call",
      "hours_per_week": 16,
      "hourly_wage_cents": 1450
    },
    "options": {
      "send_invitation": false,
      "expires_in_hours": 336,
      "return_url": "https://jouwapp.nl/onboarding/klaar"
    }
  }'

Antwoord 201 (Aangemaakt):

JSON
{
  "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": {
    "vacature_id": "vac-311"
  }
}

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

GET/v1/onboardings/{id}

Eén onboarding met stappen en documenten.

Recht: onboardings:read

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

Antwoord 200 (OK):

JSON
{
  "id": "onb_…",
  "status": "pending_employee",
  "waiting_on": [
    "employee"
  ],
  "employee": {},
  "employment": {},
  "data_version": 1,
  "approvals": {},
  "contract": {},
  "payroll": null,
  "hosted_link": null,
  "reference": "sollicitant-4711",
  "metadata": {
    "vacature_id": "vac-311"
  },
  "return_url": "https://jouwapp.nl/onboarding/klaar",
  "source": "api",
  "created_at": "2026-10-12T12:00:00.000Z",
  "updated_at": "2026-10-12T12:00:00.000Z",
  "steps": [],
  "documents": [
    {
      "id": "doc_…",
      "kind": "contract_signed",
      "title": "Arbeidsovereenkomst",
      "uploaded_at": "2026-10-12T12:00:00.000Z",
      "downloadable": true
    }
  ]
}

Een {} in dit voorbeeld is een object waarvan de spec de velden niet vastlegt.

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

PATCH/v1/onboardings/{id}

Referentie en metadata bijwerken.

Voegt metadata samen; null verwijdert een sleutel. Gegevens van de medewerker wijzig je niet via de API (field_not_updatable). De data_version blijft gelijk, dus goedkeuringen blijven geldig.

Recht: onboardings:write

ParameterInTypeVerplichtOmschrijving
idpathstringja—
Idempotency-KeyheaderstringneeZelfde sleutel en inhoud binnen 24 uur geeft hetzelfde antwoord. Loopt het eerste verzoek nog, dan 409 idempotency_in_progress: probeer het zo opnieuw. Hooguit 200 tekens.

Request body (JSON):

VeldTypeVerplichtOmschrijving
referencestring | nullneeHooguit 200 tekens.
metadataobject (sleutel → string | number | boolean | null)neeJe eigen kenmerken, bijvoorbeeld een vacature-id (sleutels: letters, cijfers, _ . -, hooguit 40 tekens; tekst hooguit 500). Komt terug in de API en in webhooks. Geen persoonsgegevens: e-mail, IBAN, BSN en telefoonnummers worden geweigerd (metadata_personal_data). Hooguit 20 sleutels.
Terminal
curl -X PATCH https://app.agreli.nl/api/public/v1/onboardings/onb_… \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "sollicitant-4711",
    "metadata": {
      "vacature_id": "vac-311"
    }
  }'

Antwoord 200 (OK):

JSON
{
  "id": "onb_…",
  "status": "pending_employee",
  "waiting_on": [
    "employee"
  ],
  "employee": {},
  "employment": {},
  "data_version": 1,
  "approvals": {},
  "contract": {},
  "payroll": null,
  "hosted_link": null,
  "reference": "sollicitant-4711",
  "metadata": {
    "vacature_id": "vac-311"
  },
  "return_url": "https://jouwapp.nl/onboarding/klaar",
  "source": "api",
  "created_at": "2026-10-12T12:00:00.000Z",
  "updated_at": "2026-10-12T12:00:00.000Z",
  "steps": [],
  "documents": [
    {
      "id": "doc_…",
      "kind": "contract_signed",
      "title": "Arbeidsovereenkomst",
      "uploaded_at": "2026-10-12T12:00:00.000Z",
      "downloadable": true
    }
  ]
}

Een {} in dit voorbeeld is een object waarvan de spec de velden niet vastlegt.

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

POST/v1/onboardings/{id}/hosted-link

Nieuwe hosted link (de vorige vervalt).

Recht: onboardings:write

ParameterInTypeVerplichtOmschrijving
idpathstringja—
Idempotency-KeyheaderstringneeZelfde sleutel en inhoud binnen 24 uur geeft hetzelfde antwoord. Loopt het eerste verzoek nog, dan 409 idempotency_in_progress: probeer het zo opnieuw. Hooguit 200 tekens.

Request body (JSON, optioneel):

VeldTypeVerplichtOmschrijving
expires_in_hoursintegernee1 tot 336.
send_invitationbooleanneeStandaard false.
Terminal
curl -X POST https://app.agreli.nl/api/public/v1/onboardings/onb_…/hosted-link \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_in_hours": 336,
    "send_invitation": false
  }'

Antwoord 201 (OK):

JSON
{
  "onboarding_id": "onb_…",
  "hosted_url": "https://app.agreli.nl/m/…",
  "expires_at": "2026-10-26T12:00:00.000Z",
  "invitation_sent": false
}

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

POST/v1/onboardings/{id}/cancel

Annuleren.

Recht: onboardings:write

ParameterInTypeVerplichtOmschrijving
idpathstringja—
Idempotency-KeyheaderstringneeZelfde sleutel en inhoud binnen 24 uur geeft hetzelfde antwoord. Loopt het eerste verzoek nog, dan 409 idempotency_in_progress: probeer het zo opnieuw. Hooguit 200 tekens.
Terminal
curl -X POST https://app.agreli.nl/api/public/v1/onboardings/onb_…/cancel \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Antwoord 200 (OK):

JSON
{
  "id": "onb_…",
  "status": "pending_employee",
  "waiting_on": [
    "employee"
  ],
  "employee": {},
  "employment": {},
  "data_version": 1,
  "approvals": {},
  "contract": {},
  "payroll": null,
  "hosted_link": null,
  "reference": "sollicitant-4711",
  "metadata": {
    "vacature_id": "vac-311"
  },
  "return_url": "https://jouwapp.nl/onboarding/klaar",
  "source": "api",
  "created_at": "2026-10-12T12:00:00.000Z",
  "updated_at": "2026-10-12T12:00:00.000Z",
  "steps": [],
  "documents": [
    {
      "id": "doc_…",
      "kind": "contract_signed",
      "title": "Arbeidsovereenkomst",
      "uploaded_at": "2026-10-12T12:00:00.000Z",
      "downloadable": true
    }
  ]
}

Een {} in dit voorbeeld is een object waarvan de spec de velden niet vastlegt.

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

POST/v1/onboardings/{id}/identity-verification

ID-controle bevestigen (als manager).

Staat standaard uit: een eigenaar zet goedkeuren via de API aan bij Instellingen, API en webhooks (anders 403 api_approvals_disabled).

Recht: approvals:write

ParameterInTypeVerplichtOmschrijving
idpathstringja—
Idempotency-KeyheaderstringneeZelfde sleutel en inhoud binnen 24 uur geeft hetzelfde antwoord. Loopt het eerste verzoek nog, dan 409 idempotency_in_progress: probeer het zo opnieuw. Hooguit 200 tekens.
Terminal
curl -X POST https://app.agreli.nl/api/public/v1/onboardings/onb_…/identity-verification \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Antwoord 200 (OK):

JSON
{
  "id": "onb_…",
  "status": "pending_employee",
  "waiting_on": [
    "employee"
  ],
  "employee": {},
  "employment": {},
  "data_version": 1,
  "approvals": {},
  "contract": {},
  "payroll": null,
  "hosted_link": null,
  "reference": "sollicitant-4711",
  "metadata": {
    "vacature_id": "vac-311"
  },
  "return_url": "https://jouwapp.nl/onboarding/klaar",
  "source": "api",
  "created_at": "2026-10-12T12:00:00.000Z",
  "updated_at": "2026-10-12T12:00:00.000Z",
  "steps": [],
  "documents": [
    {
      "id": "doc_…",
      "kind": "contract_signed",
      "title": "Arbeidsovereenkomst",
      "uploaded_at": "2026-10-12T12:00:00.000Z",
      "downloadable": true
    }
  ]
}

Een {} in dit voorbeeld is een object waarvan de spec de velden niet vastlegt.

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

POST/v1/onboardings/{id}/approvals

Goedkeuren als de eigenaar van de sleutel.

Vierogen: één persoon kan niet twee rollen vervullen. data_version moet gelijk zijn aan de gecontroleerde versie. Staat standaard uit: een eigenaar zet goedkeuren via de API aan bij Instellingen, API en webhooks (anders 403 api_approvals_disabled).

Recht: approvals:write

ParameterInTypeVerplichtOmschrijving
idpathstringja—
Idempotency-KeyheaderstringneeZelfde sleutel en inhoud binnen 24 uur geeft hetzelfde antwoord. Loopt het eerste verzoek nog, dan 409 idempotency_in_progress: probeer het zo opnieuw. Hooguit 200 tekens.

Request body (JSON):

VeldTypeVerplichtOmschrijving
rolemanager, payroll_reviewer, ownerja—
data_versionintegerja—
Terminal
curl -X POST https://app.agreli.nl/api/public/v1/onboardings/onb_…/approvals \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "manager",
    "data_version": 1
  }'

Antwoord 200 (OK):

JSON
{
  "id": "onb_…",
  "status": "pending_employee",
  "waiting_on": [
    "employee"
  ],
  "employee": {},
  "employment": {},
  "data_version": 1,
  "approvals": {},
  "contract": {},
  "payroll": null,
  "hosted_link": null,
  "reference": "sollicitant-4711",
  "metadata": {
    "vacature_id": "vac-311"
  },
  "return_url": "https://jouwapp.nl/onboarding/klaar",
  "source": "api",
  "created_at": "2026-10-12T12:00:00.000Z",
  "updated_at": "2026-10-12T12:00:00.000Z",
  "steps": [],
  "documents": [
    {
      "id": "doc_…",
      "kind": "contract_signed",
      "title": "Arbeidsovereenkomst",
      "uploaded_at": "2026-10-12T12:00:00.000Z",
      "downloadable": true
    }
  ]
}

Een {} in dit voorbeeld is een object waarvan de spec de velden niet vastlegt.

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

POST/v1/onboardings/{id}/contract

Contract maken en ter ondertekening versturen.

Recht: contracts:write

ParameterInTypeVerplichtOmschrijving
idpathstringja—
Idempotency-KeyheaderstringneeZelfde sleutel en inhoud binnen 24 uur geeft hetzelfde antwoord. Loopt het eerste verzoek nog, dan 409 idempotency_in_progress: probeer het zo opnieuw. Hooguit 200 tekens.
Terminal
curl -X POST https://app.agreli.nl/api/public/v1/onboardings/onb_…/contract \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Antwoord 200 (OK):

JSON
{
  "id": "onb_…",
  "status": "pending_employee",
  "waiting_on": [
    "employee"
  ],
  "employee": {},
  "employment": {},
  "data_version": 1,
  "approvals": {},
  "contract": {},
  "payroll": null,
  "hosted_link": null,
  "reference": "sollicitant-4711",
  "metadata": {
    "vacature_id": "vac-311"
  },
  "return_url": "https://jouwapp.nl/onboarding/klaar",
  "source": "api",
  "created_at": "2026-10-12T12:00:00.000Z",
  "updated_at": "2026-10-12T12:00:00.000Z",
  "steps": [],
  "documents": [
    {
      "id": "doc_…",
      "kind": "contract_signed",
      "title": "Arbeidsovereenkomst",
      "uploaded_at": "2026-10-12T12:00:00.000Z",
      "downloadable": true
    }
  ]
}

Een {} in dit voorbeeld is een object waarvan de spec de velden niet vastlegt.

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

GET/v1/onboardings/{id}/documents

Documenten.

Recht: documents:read

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

Antwoord 200 (OK):

JSON
{
  "object": "list",
  "data": [
    {
      "id": "doc_…",
      "kind": "contract_signed",
      "title": "Arbeidsovereenkomst",
      "uploaded_at": "2026-10-12T12:00:00.000Z",
      "downloadable": true
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

GET/v1/onboardings/{id}/documents/{documentId}

Document downloaden.

Kopieën van identiteitsbewijzen alleen voor de salarisadministratie. Elke download staat in de audit.

Recht: documents:read

ParameterInTypeVerplichtOmschrijving
idpathstringja—
documentIdpathstringja—
Terminal
curl https://app.agreli.nl/api/public/v1/onboardings/onb_…/documents/doc_… \
  -H "Authorization: Bearer $AGRELI_API_KEY"

Antwoord 200: Het bestand (application/pdf, image/png, image/jpeg).

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

GET/v1/employees

Medewerkers.

Recht: employees:read

ParameterInTypeVerplichtOmschrijving
limitqueryintegernee1 tot 100.
starting_afterquerystringnee—
Terminal
curl https://app.agreli.nl/api/public/v1/employees \
  -H "Authorization: Bearer $AGRELI_API_KEY"

Antwoord 200 (OK):

JSON
{
  "object": "list",
  "data": [
    {
      "id": "emp_…",
      "first_name": "Sam",
      "last_name": "Jansen",
      "position": "Bediening",
      "location_id": "loc_…",
      "start_date": "2026-12-01",
      "onboarding": {}
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Een {} in dit voorbeeld is een object waarvan de spec de velden niet vastlegt.

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

GET/v1/approvals

Wat jij nu kunt goedkeuren.

Recht: approvals:read

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

Antwoord 200 (OK):

JSON
{
  "object": "list",
  "data": [
    {
      "onboarding_id": "onb_…",
      "data_version": 1,
      "can_approve_as": [
        "payroll_reviewer"
      ],
      "blocked_by": []
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

GET/v1/integrations

Koppelingen en synchronisatiestatus.

Recht: integrations:read

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

Antwoord 200 (OK): een JSON-object; de velden staan niet in de spec.

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

GET/v1/webhooks

Webhookadressen.

Recht: webhooks:manage

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

Antwoord 200 (OK):

JSON
{
  "object": "list",
  "data": [
    {
      "id": "wh_…",
      "url": "https://jouwapp.nl/webhooks/agreli",
      "events": [
        "onboarding.approval_required",
        "onboarding.completed"
      ],
      "status": "enabled",
      "api_version": "…",
      "previous_secret_expires_at": "2026-10-12T12:00:00.000Z",
      "secret": "whsec_…",
      "recent_deliveries": [
        {
          "id": "whd_…",
          "object": "webhook_delivery",
          "event_id": "evt_…",
          "event_type": "…",
          "status": "pending",
          "attempts": 1,
          "last_status_code": 1,
          "last_error": "…",
          "created_at": "2026-10-12T12:00:00.000Z",
          "delivered_at": "2026-10-12T12:00:00.000Z",
          "next_attempt_at": "2026-10-12T12:00:00.000Z"
        }
      ]
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

POST/v1/webhooks

Webhookadres toevoegen.

Het geheim (whsec_…) staat alleen in dit antwoord.

Recht: webhooks:manage

ParameterInTypeVerplichtOmschrijving
Idempotency-KeyheaderstringneeZelfde sleutel en inhoud binnen 24 uur geeft hetzelfde antwoord. Loopt het eerste verzoek nog, dan 409 idempotency_in_progress: probeer het zo opnieuw. Hooguit 200 tekens.

Request body (JSON):

VeldTypeVerplichtOmschrijving
urlstring (uri)ja—
descriptionstringnee—
eventsarray van contract.sent, contract.signed, contract.signed_by_employee, integration.sync_failed, integration.sync_succeeded, onboarding.approval_given, onboarding.approval_required, onboarding.approved, onboarding.cancelled, onboarding.completed, onboarding.contract_signed, onboarding.created, onboarding.employee_submitted, onboarding.failed, onboarding.invitation_sent, onboarding.returned, onboarding.started, onboarding.submitted, onboarding.terms_changed, payroll.completedneeLeeg = alle gebeurtenissen.
Terminal
curl -X POST https://app.agreli.nl/api/public/v1/webhooks \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://jouwapp.nl/webhooks/agreli",
    "description": "Productie",
    "events": [
      "onboarding.approval_required",
      "onboarding.completed"
    ]
  }'

Antwoord 201 (OK):

JSON
{
  "id": "wh_…",
  "url": "https://jouwapp.nl/webhooks/agreli",
  "events": [
    "onboarding.approval_required",
    "onboarding.completed"
  ],
  "status": "enabled",
  "api_version": "…",
  "previous_secret_expires_at": "2026-10-12T12:00:00.000Z",
  "secret": "whsec_…",
  "recent_deliveries": [
    {
      "id": "whd_…",
      "object": "webhook_delivery",
      "event_id": "evt_…",
      "event_type": "…",
      "status": "pending",
      "attempts": 1,
      "last_status_code": 1,
      "last_error": "…",
      "created_at": "2026-10-12T12:00:00.000Z",
      "delivered_at": "2026-10-12T12:00:00.000Z",
      "next_attempt_at": "2026-10-12T12:00:00.000Z"
    }
  ]
}

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

GET/v1/webhooks/{id}

Eén webhookadres met recente afleveringen.

Recht: webhooks:manage

ParameterInTypeVerplichtOmschrijving
idpathstringja—
Terminal
curl https://app.agreli.nl/api/public/v1/webhooks/wh_… \
  -H "Authorization: Bearer $AGRELI_API_KEY"

Antwoord 200 (OK):

JSON
{
  "id": "wh_…",
  "url": "https://jouwapp.nl/webhooks/agreli",
  "events": [
    "onboarding.approval_required",
    "onboarding.completed"
  ],
  "status": "enabled",
  "api_version": "…",
  "previous_secret_expires_at": "2026-10-12T12:00:00.000Z",
  "secret": "whsec_…",
  "recent_deliveries": [
    {
      "id": "whd_…",
      "object": "webhook_delivery",
      "event_id": "evt_…",
      "event_type": "…",
      "status": "pending",
      "attempts": 1,
      "last_status_code": 1,
      "last_error": "…",
      "created_at": "2026-10-12T12:00:00.000Z",
      "delivered_at": "2026-10-12T12:00:00.000Z",
      "next_attempt_at": "2026-10-12T12:00:00.000Z"
    }
  ]
}

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

DELETE/v1/webhooks/{id}

Verwijderen.

Recht: webhooks:manage

ParameterInTypeVerplichtOmschrijving
idpathstringja—
Idempotency-KeyheaderstringneeZelfde sleutel en inhoud binnen 24 uur geeft hetzelfde antwoord. Loopt het eerste verzoek nog, dan 409 idempotency_in_progress: probeer het zo opnieuw. Hooguit 200 tekens.
Terminal
curl -X DELETE https://app.agreli.nl/api/public/v1/webhooks/wh_… \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Antwoord 200 (OK): een JSON-object; de velden staan niet in de spec.

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

POST/v1/webhooks/{id}/test

Testbericht (ping) sturen.

Recht: webhooks:manage

ParameterInTypeVerplichtOmschrijving
idpathstringja—
Idempotency-KeyheaderstringneeZelfde sleutel en inhoud binnen 24 uur geeft hetzelfde antwoord. Loopt het eerste verzoek nog, dan 409 idempotency_in_progress: probeer het zo opnieuw. Hooguit 200 tekens.
Terminal
curl -X POST https://app.agreli.nl/api/public/v1/webhooks/wh_…/test \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Antwoord 200 (OK): een JSON-object; de velden staan niet in de spec.

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

POST/v1/webhooks/{id}/rotate-secret

Geheim vernieuwen.

Het nieuwe geheim (alleen in dit antwoord) ondertekent direct. Het vorige ondertekent nog overlap_hours mee als tweede v1 in Agreli-Signature, zodat je zonder gemiste webhooks overstapt. 0 = het vorige is direct ongeldig.

Recht: webhooks:manage

ParameterInTypeVerplichtOmschrijving
idpathstringja—
Idempotency-KeyheaderstringneeZelfde sleutel en inhoud binnen 24 uur geeft hetzelfde antwoord. Loopt het eerste verzoek nog, dan 409 idempotency_in_progress: probeer het zo opnieuw. Hooguit 200 tekens.

Request body (JSON, optioneel):

VeldTypeVerplichtOmschrijving
overlap_hoursintegernee0 tot 168. Standaard 24.
Terminal
curl -X POST https://app.agreli.nl/api/public/v1/webhooks/wh_…/rotate-secret \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "overlap_hours": 24
  }'

Antwoord 200 (OK):

JSON
{
  "id": "wh_…",
  "url": "https://jouwapp.nl/webhooks/agreli",
  "events": [
    "onboarding.approval_required",
    "onboarding.completed"
  ],
  "status": "enabled",
  "api_version": "…",
  "previous_secret_expires_at": "2026-10-12T12:00:00.000Z",
  "secret": "whsec_…",
  "recent_deliveries": [
    {
      "id": "whd_…",
      "object": "webhook_delivery",
      "event_id": "evt_…",
      "event_type": "…",
      "status": "pending",
      "attempts": 1,
      "last_status_code": 1,
      "last_error": "…",
      "created_at": "2026-10-12T12:00:00.000Z",
      "delivered_at": "2026-10-12T12:00:00.000Z",
      "next_attempt_at": "2026-10-12T12:00:00.000Z"
    }
  ]
}

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

GET/v1/webhooks/{id}/deliveries

Afleverlog van één adres.

Nieuwste eerst. Afleveringen blijven 30 dagen zichtbaar.

Recht: webhooks:manage

ParameterInTypeVerplichtOmschrijving
idpathstringja—
statusquerypending, in_progress, succeeded, failed, deadnee—
limitqueryintegernee1 tot 100. Standaard 25.
starting_afterquerystringneenext_cursor van de vorige pagina.
Terminal
curl https://app.agreli.nl/api/public/v1/webhooks/wh_…/deliveries \
  -H "Authorization: Bearer $AGRELI_API_KEY"

Antwoord 200 (OK):

JSON
{
  "object": "list",
  "data": [
    {
      "id": "whd_…",
      "object": "webhook_delivery",
      "event_id": "evt_…",
      "event_type": "…",
      "status": "pending",
      "attempts": 1,
      "last_status_code": 1,
      "last_error": "…",
      "created_at": "2026-10-12T12:00:00.000Z",
      "delivered_at": "2026-10-12T12:00:00.000Z",
      "next_attempt_at": "2026-10-12T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

POST/v1/webhooks/{id}/deliveries/{deliveryId}/retry

Aflevering opnieuw versturen.

Met hetzelfde event-id en dezelfde inhoud, dus je kunt ontdubbelen. Kan bij geslaagde, mislukte en definitief mislukte afleveringen.

Recht: webhooks:manage

ParameterInTypeVerplichtOmschrijving
idpathstringja—
deliveryIdpathstringja—
Idempotency-KeyheaderstringneeZelfde sleutel en inhoud binnen 24 uur geeft hetzelfde antwoord. Loopt het eerste verzoek nog, dan 409 idempotency_in_progress: probeer het zo opnieuw. Hooguit 200 tekens.
Terminal
curl -X POST https://app.agreli.nl/api/public/v1/webhooks/wh_…/deliveries/{deliveryId}/retry \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Antwoord 200 (OK):

JSON
{
  "id": "whd_…",
  "object": "webhook_delivery",
  "event_id": "evt_…",
  "event_type": "…",
  "status": "pending",
  "attempts": 1,
  "last_status_code": 1,
  "last_error": "…",
  "created_at": "2026-10-12T12:00:00.000Z",
  "delivered_at": "2026-10-12T12:00:00.000Z",
  "next_attempt_at": "2026-10-12T12:00:00.000Z"
}

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

GET/v1/events

Gebeurtenissen (om gemiste webhooks na te lopen).

Dezelfde gebeurtenissen als de webhooks, met hetzelfde id en dezelfde inhoud, ook als je geen webhookadres hebt. Oudste eerst; bewaard 30 dagen. Bewaar het laatste id en vraag daarna op met starting_after.

Recht: onboardings:read

ParameterInTypeVerplichtOmschrijving
Agreli-OrganizationheaderstringneeAlleen voor sleutels van een API-partner: de werkgever namens wie je werkt. Verplicht als de partner meer dan één werkgever heeft.
sincequerystring (date-time)nee—
typequerycontract.sent, contract.signed, contract.signed_by_employee, integration.sync_failed, integration.sync_succeeded, onboarding.approval_given, onboarding.approval_required, onboarding.approved, onboarding.cancelled, onboarding.completed, onboarding.contract_signed, onboarding.created, onboarding.employee_submitted, onboarding.failed, onboarding.invitation_sent, onboarding.returned, onboarding.started, onboarding.submitted, onboarding.terms_changed, payroll.completednee—
limitqueryintegernee1 tot 100. Standaard 50.
starting_afterquerystringneenext_cursor van de vorige pagina.
Terminal
curl https://app.agreli.nl/api/public/v1/events \
  -H "Authorization: Bearer $AGRELI_API_KEY"

Antwoord 200 (OK):

JSON
{
  "object": "list",
  "data": [
    {
      "id": "evt_…",
      "object": "event",
      "type": "contract.sent",
      "api_version": "…",
      "created_at": "2026-10-12T12:00:00.000Z",
      "organization_id": "org_…",
      "data": {
        "onboarding_id": "onb_…",
        "reference": "sollicitant-4711",
        "metadata": {
          "vacature_id": "vac-311"
        },
        "data_version": 1,
        "role": "…",
        "returned_to": "…",
        "kind": "invitation",
        "connector": "…",
        "error_code": "…"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

POST/v1/sandbox/onboardings/{id}/advance

Sandbox: volgende stap naspelen.

Alleen met een testsleutel. Vult de gegevens in, keurt goed met testgebruikers, tekent en rondt de gesimuleerde salarisverwerking af.

Recht: onboardings:write

ParameterInTypeVerplichtOmschrijving
idpathstringja—
Idempotency-KeyheaderstringneeZelfde sleutel en inhoud binnen 24 uur geeft hetzelfde antwoord. Loopt het eerste verzoek nog, dan 409 idempotency_in_progress: probeer het zo opnieuw. Hooguit 200 tekens.
Terminal
curl -X POST https://app.agreli.nl/api/public/v1/sandbox/onboardings/onb_…/advance \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Antwoord 200 (OK):

JSON
{
  "step": "employee_submitted",
  "onboarding": {
    "id": "onb_…",
    "status": "pending_employee",
    "waiting_on": [
      "employee"
    ],
    "employee": {},
    "employment": {},
    "data_version": 1,
    "approvals": {},
    "contract": {},
    "payroll": null,
    "hosted_link": null,
    "reference": "sollicitant-4711",
    "metadata": {
      "vacature_id": "vac-311"
    },
    "return_url": "https://jouwapp.nl/onboarding/klaar",
    "source": "api",
    "created_at": "2026-10-12T12:00:00.000Z",
    "updated_at": "2026-10-12T12:00:00.000Z",
    "steps": [],
    "documents": [
      {
        "id": "doc_…",
        "kind": "contract_signed",
        "title": "Arbeidsovereenkomst",
        "uploaded_at": "2026-10-12T12:00:00.000Z",
        "downloadable": true
      }
    ]
  }
}

Een {} in dit voorbeeld is een object waarvan de spec de velden niet vastlegt.

Fouten: 401, 403, 404, 409, 422, 429, in de vaste foutvorm.

Rechten

RechtWat het toestaatEndpoints
approvals:readOpenstaande controles lezenGET /v1/approvals
approvals:writeGoedkeuren en de ID-controle bevestigen, als jijzelfPOST /v1/onboardings/{id}/identity-verification, POST /v1/onboardings/{id}/approvals
contracts:writeContract maken en ter ondertekening versturenPOST /v1/onboardings/{id}/contract
documents:readDocumenten en toegestane downloadsGET /v1/onboardings/{id}/documents, GET /v1/onboardings/{id}/documents/{documentId}
employees:readMedewerkers en dienstverbanden lezenGET /v1/employees
integrations:readKoppelingen en synchronisatiestatus lezenGET /v1/integrations
onboardings:readOnboardings en hun status lezenGET /v1/onboardings, GET /v1/onboardings/{id}, GET /v1/events
onboardings:writeOnboardings starten, links maken en annulerenPOST /v1/onboardings, PATCH /v1/onboardings/{id}, POST /v1/onboardings/{id}/hosted-link, POST /v1/onboardings/{id}/cancel, POST /v1/sandbox/onboardings/{id}/advance
organization:readOrganisatie en vestigingen lezenGET /v1/organizations, GET /v1/organization
webhooks:manageWebhooks beherenGET /v1/webhooks, POST /v1/webhooks, GET /v1/webhooks/{id}, DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}/test, POST /v1/webhooks/{id}/rotate-secret, GET /v1/webhooks/{id}/deliveries, POST /v1/webhooks/{id}/deliveries/{deliveryId}/retry