Taskport API Reference

Introductie

Taskport biedt een JSON API voor integraties met externe systemen zoals CRM-, planning-, ticketing-, backoffice- of partnerplatformen. De publieke API bestaat uit twee hoofdflows:

• Incoming API: opdrachten en contractor-interne berichten naar Taskport schrijven
• Outbound Sync API: wijzigingen vanuit Taskport ophalen via een cursor-based event feed

Basis-URL

https://taskport.nl

Dataformaat

Taskport gebruikt JSON voor request payloads en responses.

HTTP-methodes

Authenticatie

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Accept: application/json

Authorization: Bearer YOUR_API_TOKEN
Accept: application/json

Rechten

• Voor outbound moet de token outbound-rechten hebben, technisch: can_use_outbound_api = 1.
• Voor incoming is een actieve token voldoende, tenzij incoming-scopes actief zijn; dan moet can_use_incoming_api = 1 op de token staan.
• Dezelfde token mag incoming en outbound combineren als beide rechten op die token aanwezig zijn.

Rate limits

Fouten

Quick start

1. Gebruik een actieve integration bearer-token. Voor outbound moet die token outbound-rechten hebben.
2. Maak of update opdrachten via POST /api/contractor_incoming_api.php. Klantgegevens en opdrachtgegevens gaan samen in dezelfde request.
3. Lees wijzigingen terug via GET /api/outbound_sync_api.php en bewaar steeds de nieuwste next_cursor.

Opdracht aanmaken / bijwerken

Deze route wordt gebruikt om nieuwe opdrachten aan te maken of bestaande opdrachten bij te werken. Taskport gebruikt hiervoor my_id als externe sleutel.

Velden bij aanmaken

Verplicht bij aanmaken:

• name
• street
• house_number
• zipcode
• city
• mobile
• email
• serial_number
• title
• problem_description
• urgency
• sla
• my_id of idempotency_key

Velden bij bijwerken

Verplicht bij bijwerken:

• my_id

Interne notitie toevoegen

Gebruik hetzelfde endpoint om contractor-interne notities aan een bestaande opdracht toe te voegen.

Verplicht voor een bericht:

• my_id
• messaging.message
• messaging.external_message_id

Optioneel:

• messaging.message_type
• messaging.created_at

Veldreference

Voorbeeld: opdracht aanmaken

curl -X POST "https://taskport.nl/api/contractor_incoming_api.php" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-raw '{
    "name": "Jane Example",
    "street": "Harbor Lane",
    "house_number": "14A",
    "zipcode": "1012AB",
    "city": "Amsterdam",
    "mobile": "+31612345678",
    "email": "jane.example@example.test",
    "my_id": "SRC-90010001",
    "serial_number": "SRC_009001",
    "title": "kWh meter defect",
    "problem_description": "Customer reports that the charger no longer registers meter values.",
    "urgency": "normal",
    "sla": "standard_24h"
  }'

{
  "ok": true,
  "action": "job_created",
  "job_id": 60001,
  "my_id": "SRC-90010001"
}

Voorbeeld: opdracht bijwerken

curl -X POST "https://taskport.nl/api/contractor_incoming_api.php" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-raw '{
    "my_id": "SRC-90010001",
    "title": "kWh meter defect - revisie 2",
    "urgency": "high"
  }'

{
  "ok": true,
  "action": "job_updated",
  "job_id": 60001,
  "my_id": "SRC-90010001"
}

{
  "ok": true,
  "action": "job_updated",
  "job_id": 60001,
  "my_id": "SRC-90010001",
  "message_action": "message_added",
  "thread_id": 123,
  "message_id": 456
}

Sync-events ophalen

Gebruik deze route om wijzigingen uit Taskport op te halen.

1. haal events op vanaf een cursor
2. verwerk ze in het eigen systeem
3. bewaar next_cursor
4. gebruik die cursor bij de volgende run

Queryparameters

Event-object

Event types

Voorbeeldresponse

curl -X GET "https://taskport.nl/api/outbound_sync_api.php?cursor=evt_0000000123&limit=100" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

{
  "ok": true,
  "items": [
    {
      "event_id": "evt_0000001024",
      "event_type": "job_created",
      "entity_type": "job",
      "occurred_at": "2026-03-18T12:41:30+00:00",
      "integration_id": 17,
      "contractor_id": 4,
      "company_id": 1,
      "taskport_id": 51425,
      "external_id": "EXT-1001",
      "payload": {
        "customer_name": "Demo Klant",
        "serial_number": "EXT_1001",
        "title": "kWh meter defect",
        "status": "created"
      }
    }
  ],
  "next_cursor": "evt_0000001024",
  "has_more": false,
  "count": 1
}

Request IDs

Gebruik bij support of troubleshooting altijd de request-id uit de response headers.

X-Taskport-Request-Id: <request-id>