GET/provider/requests
Lists service requests assigned to the authenticated provider.
Scope: requests:read
Optional query parameters: status, per_page (1–100, default 25).
REST API
Noukarivé API v1
Server-to-server JSON API for professional customers and transport providers.
Basics
Production base URL
https://noukarive.com/api/v1
Requests and responses use JSON unless otherwise specified. Send Accept: application/json and, for POST requests, Content-Type: application/json.
Authentication
API credentials are created in the Business or Provider automation area. Tokens begin with nk_, are shown once, hashed at rest and may be revoked or rotated.
curl https://noukarive.com/api/v1/business/orders \
-H 'Accept: application/json' \
-H 'Authorization: Bearer nk_YOUR_TOKEN'
| Surface | Scopes currently used by routes | Reserved/account scopes |
|---|---|---|
| Provider | requests:read, requests:write, tours:read, drivers:read, drivers:write, tracking:write, proofs:write | tracking:read |
Rate limits
API v1 is limited to 120 requests per minute per bearer token by default. The deployment may change this value through configuration. A rate-limited request returns HTTP 429.
Provider API — TMS / Onfleet-style integrations
The Provider API is bidirectional. A TMS can read assigned work, synchronize drivers and report operational actions back to Noukarivé without bypassing the same lifecycle, proof, customer validation and financial-release rules used by the Provider portal.
Write safety: every Provider write request requires an
Idempotency-Key header. Reusing the same key with the same request replays the original response; reusing it with a different payload returns HTTP 409.GET/provider/requests/{id}
Returns one assigned request including category, driver, payment, shipment and delivery proofs. Requests assigned to another provider return 404.
Scope: requests:read
GET/provider/tours
Returns provider tour occurrences, including vehicle and stops.
Scope: tours:read
Mission lifecycle
| Method | Path | Scope | Purpose |
|---|---|---|---|
| POST | /provider/requests/{id}/accept | requests:write | Accept the mission and trigger the normal Noukarivé acceptance lifecycle. |
| POST | /provider/requests/{id}/reject | requests:write | Reject an unstarted mission and return it to pending allocation. |
| POST | /provider/requests/{id}/pickup | requests:write | Confirm physical pickup. Optional occurred_at. |
| POST | /provider/requests/{id}/delivery | requests:write | Confirm physical delivery. Customer validation remains independent. |
| POST | /provider/requests/{id}/complete | requests:write | Mark carrier-side completion and refresh financial release eligibility. |
| PATCH | /provider/requests/{id}/status | tracking:write | Normalize common TMS states without exposing raw database status mutation. |
curl -X POST https://noukarive.com/api/v1/provider/requests/123/pickup \
-H 'Authorization: Bearer nk_YOUR_TOKEN' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: onfleet-task-987-pickup' \
-d '{"occurred_at":"2026-08-13T18:42:00-04:00"}'
Tracking events
PATCH /provider/requests/{id}/status accepts the normalized statuses picked_up, in_progress, out_for_delivery, arrived, delivery_attempted, delivered and completed. Terminal actions are routed through the same pickup/delivery/completion services instead of directly changing the request status field.
POST /provider/requests/{id}/events accepts safe timeline events departed, arrived, out_for_delivery, delivery_attempted and note, with optional timestamp, title, description, location and visibility.
Drivers
GET/provider/drivers
Lists drivers owned by the authenticated provider.
Scope: drivers:read
POST/provider/drivers/sync
Upserts up to 500 TMS drivers using a stable external_id and source (for example onfleet).
Scope: drivers:write
PATCH/provider/requests/{id}/driver
Assigns or unassigns an active provider driver by Noukarivé ID or by external_driver_id + external_source.
Scope: requests:write
Proofs
POST/provider/requests/{id}/proofs
Uploads a pickup/delivery/other proof as multipart form data. Maximum file size: 10 MB.
Scope: proofs:write
Fields: proof_stage, type, proof_file, optional notes.
Typical TMS flow
Noukarivé request assigned
↓ GET /provider/requests
TMS creates / updates its task
↓ POST /accept
Driver synchronized / assigned
↓ POST /drivers/sync + PATCH /driver
Pickup
↓ POST /pickup
Live operational events
↓ PATCH /status or POST /events
Proof
↓ POST /proofs
Delivery
↓ POST /delivery
Noukarivé customer validation + ledger rules
Errors
| HTTP | Meaning |
|---|---|
| 401 | Missing, invalid or expired bearer credential. |
| 403 | Credential lacks the requested scope, or the account subscription does not include API access. |
| 404 | Resource not found inside the authenticated account boundary. |
| 422 | Laravel validation error. The response includes a field-level errors object when JSON is requested. |
| 429 | Rate limit exceeded. |
Idempotency
Provider writes: Idempotency-Key is mandatory (8–255 characters). Successful non-5xx responses are retained for 30 days. Retry the exact same operation with the exact same key after a timeout.
A replay returns Idempotency-Replayed: true. Reusing the same key with a different method/path/payload returns HTTP 409.
Business API limitation:
POST /business/orders still does not provide the same contractual replay guarantee. Do not blindly retry an ambiguous Business order creation timeout.