Ga naar hoofdinhoud

REST API Referentie

De Sidefish REST API stelt ontwikkelaars en integratiepartners in staat om programmatisch klanten te beheren, nieuwe dossiers en vragenlijstverzoeken te starten, en ingevulde antwoorden en documenten op te halen.

1. Algemene Specificaties​

  • Basis-URL Productie: https://sidefish.app/api/v1
  • Authenticatie: Header x-api-key: <uw_api_sleutel> of Authorization: Bearer <token>
  • Content-Type: application/json
  • Paginering:
    • page: Paginanummer (standaard: 1)
    • limit: Aantal items per pagina (standaard: 25, maximum: 100)
  • Interactieve Tester: Bekijk de volledige OpenAPI specificatie en test live API-verzoeken in onze Interactieve API Console.

2. Systeem & Gezondheidscontrole​

API Status controleren​

Controleert de status van de API-servers en de databaseverbinding.

GET /health HTTP/1.1
Host: sidefish.app

Voorbeeld Response (200 OK)​

{
  "status": "ok",
  "timestamp": "2026-09-13T14:30:00.000Z",
  "uptime": 86400,
  "database": {
    "mongodb": "connected"
  }
}

3. Klantenbeheer (/customers)​

Klantenlijst ophalen​

Haalt een gepagineerde lijst op van contacten binnen de organisatie.

GET /customers?search=claes&page=1&limit=25 HTTP/1.1
Host: sidefish.app
x-api-key: sf_live_...

Query Parameters​

  • search (optioneel): Zoekterm op voornaam, achternaam of e-mailadres.
  • portfolioId (optioneel): Filter op een specifieke contactgroep.
  • page / limit: Paginering.

Voorbeeld Response (200 OK)​

{
  "customers": [
    {
      "_id": "64e8b1c4e12a9c001f5a9e32",
      "thirdpartyId": "CUST-8812",
      "portfolio": "64e8b1c4e12a9c001f5a9e10",
      "data": {
        "Voornaam": "Pieter",
        "Achternaam": "Claes",
        "Email": "pieter.claes@example.be",
        "Telefoon": "+32470123456"
      },
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  ],
  "total": 1
}

Individueel contact ophalen​

GET /customers/{customerId} HTTP/1.1
Host: sidefish.app
x-api-key: sf_live_...

Nieuw contact aanmaken​

POST /customers HTTP/1.1
Host: sidefish.app
x-api-key: sf_live_...
Content-Type: application/json

{
  "portfolioId": "64e8b1c4e12a9c001f5a9e10",
  "thirdpartyId": "CRM-90021",
  "data": {
    "Voornaam": "Sophie",
    "Achternaam": "Wouters",
    "Email": "sophie.wouters@example.be",
    "Telefoon": "+32471987654",
    "Straat": "Veldstraat",
    "Huisnummer": "42",
    "Postcode": "9000",
    "Gemeente": "Gent"
  }
}

4. Vragenlijsten (/questionlists)​

Beschikbare formulieren opvragen​

Haalt alle actieve vragenlijstsjablonen op van de organisatie.

GET /questionlists HTTP/1.1
Host: sidefish.app
x-api-key: sf_live_...

Voorbeeld Response (200 OK)​

[
  {
    "_id": "64e8b1c4e12a9c001f5a9e20",
    "name": "Aanvraag Woningverzekering",
    "slug": "woningverzekering",
    "description": "Digitale intake voor gebouw- en inboedelverzekering.",
    "supportedLanguages": ["nl", "fr"],
    "hasReportSpec": true
  }
]

5. Acties & Sessieverzoeken (/sessionrequests)​

Nieuwe actie starten​

Maakt een nieuw dossierverzoek aan voor een contactpersoon en verstuurt optioneel direct de uitnodiging.

POST /sessionrequests HTTP/1.1
Host: sidefish.app
x-api-key: sf_live_...
Content-Type: application/json

{
  "customerId": "64e8b1c4e12a9c001f5a9e32",
  "questionListIds": ["64e8b1c4e12a9c001f5a9e20"],
  "type": "qlist",
  "notificationEmail": {
    "send": true
  },
  "notificationSms": {
    "send": false
  },
  "reminderSchedule": {
    "reminder1Days": 3,
    "reminder2Days": 7
  }
}

Mogelijke waarden voor type:​

  • qlist: Standaard vragenlijstverzoek.
  • multisigning: Vragenlijst met gekwalificeerde digitale handtekening.
  • quicksign: Direct document ter ondertekening zonder vragenlijst.
  • campaign: Openbare campagne-link.

Voorbeeld Response (201 Created)​

{
  "_id": "64e8b1c4e12a9c001f5a9e40",
  "code": "WF7K92",
  "url": "https://sidefish.app/action/WF7K92",
  "status": "sent",
  "createdAt": "2026-09-13T14:35:00.000Z"
}

Actie Opnieuw Openstellen (Reopen)​

Heropent een reeds afgeronde actie zodat de klant correcties kan doorvoeren.

POST /sessionrequests/{actionId}/reopen HTTP/1.1
Host: sidefish.app
x-api-key: sf_live_...

Actie Annuleren​

Trekt een openstaand verzoek per direct in.

POST /sessionrequests/{actionId}/deactivate HTTP/1.1
Host: sidefish.app
x-api-key: sf_live_...

6. Sessies & Resultaten (/sessions)​

Sessiedetails & Ingevulde antwoorden opvragen​

GET /sessions/{sessionId} HTTP/1.1
Host: sidefish.app
x-api-key: sf_live_...

Voorbeeld Response (200 OK)​

{
  "_id": "64e8b1c4e12a9c001f5a9e31",
  "sessionRequest": "64e8b1c4e12a9c001f5a9e40",
  "customer": "64e8b1c4e12a9c001f5a9e32",
  "responses": [
    {
      "questionId": "q_woningtype",
      "questionTitle": "Wat is het type van uw woning?",
      "response": "Vrijstaande eengezinswoning"
    },
    {
      "questionId": "q_bouwjaar",
      "questionTitle": "Wat is het bouwjaar?",
      "response": "2018"
    }
  ],
  "documents": [
    {
      "fileName": "Rapport_Woningverzekering.pdf",
      "fileUrl": "/files/downloads/doc_64e8b20a.pdf"
    }
  ],
  "createdAt": "2026-09-13T14:20:00.000Z"
}

7. Foutafhandeling​

Alle API-fouten worden geretourneerd in een consistent JSON-formaat:

{
  "success": false,
  "error": "De opgegeven vragenlijst werd niet gevonden.",
  "status": 404
}
HTTP StatusBetekenis
400 Bad RequestOngeldige invoerparameters of ontbrekende verplichte velden in het JSON-verzoek.
401 UnauthorizedOngeldige, ontbrekende of verlopen API-sleutel of token.
403 ForbiddenOnvoldoende rechten om de gevraagde bewerking uit te voeren.
404 Not FoundDe opgevraagde entiteit (klant, sessie of vragenlijst) bestaat niet.
500 Internal Server ErrorOnverwachte serverfout. Deze fouten worden automatisch gemonitord.