GET/business/orders
Returns paginated orders belonging to the authenticated organization.
Scope: orders:read
| Query | Type | Description |
|---|---|---|
per_page | integer | 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 |
|---|---|---|
| Business | orders:create, orders:read | drivers:read, tracking:read |
| 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.
Business API
Subscription: Business API access is reserved for a professional plan with the
api integration feature. The base professional plan remains manual and cannot create orders through this API.All Business endpoints are scoped to the organization attached to the credential. A credential can never read another organization’s order.
GET/business/orders/{id}
Returns one organization order with its service category and chosen provider. Returns 404 if the order does not belong to the authenticated organization.
Scope: orders:read
POST/business/orders
Creates a service request for the authenticated professional organization.
Scope: orders:create
curl -X POST https://noukarive.com/api/v1/business/orders \
-H 'Authorization: Bearer nk_YOUR_TOKEN' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"territory": "Martinique",
"transport_type": "delivery",
"pickup_location": "Fort-de-France",
"delivery_location": "Le Lamentin",
"delivery_contact_name": "Marie Exemple",
"delivery_contact_phone": "+596696000000",
"description": "2 cartons",
"is_urgent": false
}'
| Field | Required | Rules |
|---|---|---|
territory | yes | string, max 255 |
transport_type | yes | string, max 100 |
pickup_location | yes | string, max 1000 |
delivery_location | yes | string, max 1000 |
pickup_contact_name | no | string, max 255 |
pickup_contact_phone | no | string, max 100 |
delivery_contact_name | yes | string, max 255 |
delivery_contact_phone | yes | string, max 100 |
description | no | string, max 5000 |
is_urgent | no | boolean |
scheduled_at | no | date / ISO-8601 recommended |
organization_driver_id | no | must belong to the authenticated organization |
Success: HTTP 201. Creating an order emits the Business webhook event order.created when the subscription and endpoint configuration allow webhooks.
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
Lists service requests assigned to the authenticated provider.
Scope: requests:read
Optional query parameters: status, per_page (1–100, default 25).
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.