API Documentatie

TenderSpotter REST API v1

Integreer Nederlandse aanbestedingsdata direct in je eigen systemen. Doorzoek tenders, beheer je pipeline en automatiseer je workflow.

REST API

JSON responses

Bearer Token Auth

5.000 calls/dag

Base URL

https://app.tenderspotter.nl/api/v1

Authenticatie

Alle API endpoints vereisen authenticatie via een Bearer token in de Authorization header.

Stap 1: API key aanmaken

Ga naar Dashboard → API en maak een nieuwe API key aan. De key begint met ts_ en wordt slechts één keer getoond.

Stap 2: Bearer token meesturen

curl -H "Authorization: Bearer ts_jouw_api_key_hier" \
  https://app.tenderspotter.nl/api/v1/tenders

Let op: de API hoort bij TenderSpotter Pro (€5 per maand), onbeperkt binnen redelijk gebruik (60 aanroepen per minuut en 5.000 per dag). De API-sleutel is gekoppeld aan je account.

Rate Limiting

Redelijk gebruik: maximaal 60 aanroepen per minuut en 5.000 per dag, voor de REST-API en de MCP-server samen. De teller per API-sleutel in de headers begint elke nacht om 00:00 UTC opnieuw.

Response headers

Elke response bevat rate limit informatie in de headers:

Header	Beschrijving
X-RateLimit-Limit	Maximaal aantal calls per dag (5000)
X-RateLimit-Remaining	Resterende calls voor vandaag
X-RateLimit-Reset	Unix timestamp wanneer het limiet reset (middernacht UTC)

Limiet overschreden

Bij overschrijding retourneert de API een 429 Too Many Requests response.

Foutafhandeling

Foutresponses bevatten altijd een error veld met een beschrijving in het Nederlands.

Status	Betekenis
200	Succes
201	Succesvol aangemaakt
400	Ongeldige aanvraag (ontbrekende of foute parameters)
401	Niet geautoriseerd (ongeldige of missende API key)
403	Geen toegang (geen Enterprise abonnement)
404	Niet gevonden
429	Rate limit overschreden
500	Interne serverfout

Endpoints

Aanbestedingen

GET/api/v1/tenders

Doorzoek en filter aanbestedingen. Retourneert een gepagineerde lijst.

Parameters

Naam	Type	Verplicht	Beschrijving
search	string	Nee	Zoekterm (titel, opdrachtgever, beschrijving)
cpvCode	string	Nee	Filter op CPV-code (exact)
procedure	string	Nee	Filter op aanbestedingsprocedure
status	string	Nee	Filter op status (open, gesloten, etc.)
town	string	Nee	Filter op plaats van opdrachtgever
minValue	number	Nee	Minimale geschatte waarde
maxValue	number	Nee	Maximale geschatte waarde
deadlineFrom	date	Nee	Deadline vanaf (YYYY-MM-DD)
deadlineTo	date	Nee	Deadline tot (YYYY-MM-DD)
page	number	Nee	Paginanummer (standaard: 1)
limit	number	Nee	Resultaten per pagina (max: 100, standaard: 20)

Voorbeeld request

curl -H "Authorization: Bearer ts_abc123..." \
  "https://app.tenderspotter.nl/api/v1/tenders?search=ICT&status=open&limit=2"

Voorbeeld response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "publicationId": "TN-2024-12345",
      "title": "ICT dienstverlening Gemeente Amsterdam",
      "buyerName": "Gemeente Amsterdam",
      "buyerTown": "Amsterdam",
      "procedure": "Openbare procedure",
      "estimatedValue": "500000.00",
      "publicationDate": "2024-01-15T00:00:00.000Z",
      "deadline": "2024-02-28T12:00:00.000Z",
      "status": "open",
      "cpvCodes": ["72000000"],
      "url": "https://www.tenderned.nl/aankondigingen/12345"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 2,
    "total": 42,
    "totalPages": 21,
    "hasNext": true,
    "hasPrev": false
  },
  "meta": {
    "rateLimitDaily": 5000,
    "rateLimitRemaining": 4998
  }
}

GET/api/v1/tenders/:id

Haal de volledige details van een specifieke aanbesteding op.

Parameters

Naam	Type	Verplicht	Beschrijving
id	uuid	Ja	Tender ID

Voorbeeld request

curl -H "Authorization: Bearer ts_abc123..." \
  "https://app.tenderspotter.nl/api/v1/tenders/550e8400-e29b-41d4-a716-446655440000"

Voorbeeld response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "publicationId": "TN-2024-12345",
    "title": "ICT dienstverlening Gemeente Amsterdam",
    "buyerName": "Gemeente Amsterdam",
    "buyerTown": "Amsterdam",
    "buyerEmail": "inkoop@amsterdam.nl",
    "buyerNuts": "NL329",
    "description": "Europese aanbesteding voor ICT dienstverlening...",
    "procedure": "Openbare procedure",
    "estimatedValue": "500000.00",
    "publicationDate": "2024-01-15T00:00:00.000Z",
    "deadline": "2024-02-28T12:00:00.000Z",
    "status": "open",
    "cpvCodes": ["72000000", "72200000"],
    "lotsCount": 3,
    "url": "https://www.tenderned.nl/aankondigingen/12345",
    "createdAt": "2024-01-15T08:30:00.000Z"
  }
}

Pipeline

GET/api/v1/pipeline

Haal alle pipeline items op voor je team. Optioneel te filteren op fase.

Parameters

Naam	Type	Verplicht	Beschrijving
stage	string	Nee	Filter op fase (gesignaleerd, kwalificatie, go_no_go, offerte, ingediend, gewonnen, verloren, no_go)

Voorbeeld request

curl -H "Authorization: Bearer ts_abc123..." \
  "https://app.tenderspotter.nl/api/v1/pipeline?stage=kwalificatie"

Voorbeeld response

{
  "data": [
    {
      "id": "...",
      "tenderId": "...",
      "stage": "kwalificatie",
      "notes": "Interessant voor onze IT afdeling",
      "estimatedValue": "500000.00",
      "winChance": 60,
      "tenderTitle": "ICT dienstverlening Gemeente Amsterdam",
      "tenderBuyerName": "Gemeente Amsterdam",
      "tenderDeadline": "2024-02-28T12:00:00.000Z",
      "assigneeName": "Jan Janssen",
      "createdAt": "2024-01-16T10:00:00.000Z"
    }
  ],
  "meta": {
    "rateLimitDaily": 5000,
    "rateLimitRemaining": 4995
  }
}

POST/api/v1/pipeline

Voeg een aanbesteding toe aan je pipeline.

Parameters

Naam	Type	Verplicht	Beschrijving
tenderId	uuid	Ja	ID van de aanbesteding
stage	string	Nee	Pipeline fase (standaard: gesignaleerd)
notes	string	Nee	Notities
estimatedValue	number	Nee	Geschatte waarde
winChance	number	Nee	Winkans percentage (0-100)

Voorbeeld request

curl -X POST \
  -H "Authorization: Bearer ts_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"tenderId": "550e8400-...", "stage": "kwalificatie", "winChance": 60}' \
  "https://app.tenderspotter.nl/api/v1/pipeline"

Voorbeeld response

{
  "data": {
    "id": "...",
    "teamId": "...",
    "tenderId": "550e8400-...",
    "stage": "kwalificatie",
    "winChance": 60,
    "createdAt": "2024-01-16T10:00:00.000Z"
  }
}

PATCH/api/v1/pipeline/:id

Werk een pipeline item bij (fase, notities, winkans, etc.).

Parameters

Naam	Type	Verplicht	Beschrijving
id	uuid	Ja	Pipeline item ID
stage	string	Nee	Nieuwe fase
notes	string	Nee	Notities
noGoReason	string	Nee	Reden voor No-Go
estimatedValue	number	Nee	Geschatte waarde
winChance	number	Nee	Winkans percentage (0-100)

Voorbeeld request

curl -X PATCH \
  -H "Authorization: Bearer ts_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"stage": "offerte", "winChance": 75}' \
  "https://app.tenderspotter.nl/api/v1/pipeline/ITEM_ID"

Voorbeeld response

{
  "data": {
    "id": "...",
    "stage": "offerte",
    "winChance": 75,
    "updatedAt": "2024-01-17T14:30:00.000Z"
  }
}

DELETE/api/v1/pipeline/:id

Verwijder een aanbesteding uit je pipeline.

Parameters

Naam	Type	Verplicht	Beschrijving
id	uuid	Ja	Pipeline item ID

Voorbeeld request

curl -X DELETE \
  -H "Authorization: Bearer ts_abc123..." \
  "https://app.tenderspotter.nl/api/v1/pipeline/ITEM_ID"

Voorbeeld response

{
  "success": true
}

Gebruik

GET/api/v1/usage

Bekijk je API gebruiksstatistieken: calls vandaag, deze maand, per endpoint, en dagelijks overzicht.

Voorbeeld request

curl -H "Authorization: Bearer ts_abc123..." \
  "https://app.tenderspotter.nl/api/v1/usage"

Voorbeeld response

{
  "data": {
    "callsToday": 142,
    "callsThisMonth": 3847,
    "dailyUsage": [
      { "date": "2024-01-10", "count": 523 },
      { "date": "2024-01-11", "count": 481 }
    ],
    "byEndpoint": [
      {
        "endpoint": "/api/v1/tenders",
        "method": "GET",
        "count": 3200,
        "avgResponseTimeMs": 45
      }
    ]
  },
  "meta": {
    "rateLimitDaily": 5000,
    "rateLimitRemaining": 4858
  }
}

Vragen over de API? Neem contact op · Prijzen bekijken · API Keys beheren