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 drie hoofdflows:

• Incoming API: opdrachten en contractor-interne berichten naar Taskport schrijven
• Planning API: planvoorstellen ophalen en opdrachten plannen binnen de scope van de bearer-token
• 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

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
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.
• Voor planning moet de token planning-rechten hebben, technisch: can_use_planning_api = 1.
• Dezelfde token mag incoming, planning en outbound combineren als de bijbehorende 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. Vraag daarna, zodra de locatie gereed is, planvoorstellen op via POST /api/contractor_planning_api.php met action = suggest_plan.
4. 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.",
    "job_type": "vervanging_easee",
    "urgency": "normal",
    "sla": "standard_24h"
  }'

{
  "ok": true,
  "action": "job_created",
  "job_id": 60001,
  "my_id": "SRC-90010001",
  "geo_status": "ok",
  "geo_message": "Locatie gecontroleerd. Planvoorstellen zijn beschikbaar.",
  "planning_ready": true
}

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",
    "job_type": "vervanging_easee",
    "urgency": "high"
  }'

{
  "ok": true,
  "action": "job_updated",
  "job_id": 60001,
  "my_id": "SRC-90010001",
  "geo_status": "pending",
  "geo_message": "Locatie wordt verwerkt. Planvoorstellen zijn meestal binnen 1 minuut beschikbaar.",
  "planning_ready": false
}

{
  "ok": true,
  "action": "job_updated",
  "job_id": 60001,
  "my_id": "SRC-90010001",
  "geo_status": "ok",
  "geo_message": "Locatie gecontroleerd. Planvoorstellen zijn beschikbaar.",
  "planning_ready": true,
  "message_action": "message_added",
  "thread_id": 123,
  "message_id": 456
}

Acties

Planvoorstellen ophalen

Gebruik action = suggest_plan om beschikbare vensters op te vragen.

curl -X POST "https://taskport.nl/api/contractor_planning_api.php" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-raw '{
    "action": "suggest_plan",
    "my_id": "SRC-90010001",
    "month": "2026-05"
  }'

{
  "ok": true,
  "action": "suggest_plan",
  "job_id": 60001,
  "my_id": "SRC-90010001",
  "site_id": 981,
  "geo_status": "ok",
  "geo_message": "Locatie gecontroleerd. Planvoorstellen zijn beschikbaar.",
  "planning_ready": true,
  "windows": [
    {
      "date": "2026-05-01",
      "dayname": "vrijdag",
      "window_key": "middag",
      "label": "Middag",
      "technician_id": 12,
      "technician_name": "Patrick",
      "scheduled_start": "2026-05-01 14:00:00",
      "scheduled_end": "2026-05-01 15:30:00"
    }
  ],
  "duration": 90,
  "job_location": {
    "lat": 52.3771,
    "lng": 4.8980
  }
}

{
  "ok": true,
  "action": "suggest_plan",
  "job_id": 60001,
  "my_id": "SRC-90010001",
  "site_id": 981,
  "geo_status": "pending",
  "geo_message": "Locatie wordt verwerkt. Planvoorstellen zijn meestal binnen 1 minuut beschikbaar.",
  "planning_ready": false,
  "windows": [],
  "duration": null,
  "job_location": null
}

Opdracht plannen of verplaatsen

Gebruik action = plan_job of action = move_job om een gekozen venster definitief te maken. Als scheduled_end ontbreekt, berekent Taskport die automatisch op basis van de duur van de opdracht.

curl -X POST "https://taskport.nl/api/contractor_planning_api.php" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-raw '{
    "action": "plan_job",
    "my_id": "SRC-90010001",
    "technician_id": 12,
    "scheduled_start": "2026-05-01 14:00:00"
  }'

{
  "ok": true,
  "action": "job_planned",
  "job_id": 60001,
  "my_id": "SRC-90010001",
  "technician_id": 12,
  "scheduled_start": "2026-05-01 14:00:00",
  "scheduled_end": "2026-05-01 15:30:00",
  "status": "scheduled"
}

Uit planning halen

Gebruik action = remove_from_planning om een opdracht terug te zetten naar ongepland.

{
  "action": "remove_from_planning",
  "my_id": "SRC-90010001"
}

{
  "ok": true,
  "action": "remove_from_planning",
  "job_id": 60001,
  "my_id": "SRC-90010001",
  "status": "created"
}

Veldreference

Planning-fouten

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>