Quinable Partner APIv1.1.0Guide Clients Routes Bids Timesheets Events & Webhooks Lookups
API docs by Redocly

Quinable Partner API — Routes (1.1.0)

Download OpenAPI specification:

Quinable Integrations: [email protected]

The Quinable Partner API lets an agency's external systems (e.g. a scheduling tool) create clients and routes/visits in Quinable and receive lifecycle status by signed webhooks.

Authentication. Every request carries a per-agency secret key in the Authorization header (Bearer qk_live_…). The key's prefix is its mode: qk_live_ acts on real data; qk_test_ is a sandbox — test routes never reach caregivers and move no money.

Conventions. JSON bodies; money is integer cents; ids are opaque prefixed strings (route_123); times of day are HH:MM in the route's local timezone. POST endpoints accept an Idempotency-Key header (replayed for 24h, then pruned). List endpoints use cursor pagination (limit, starting_after). Errors use real HTTP status codes plus a typed body.

Operations. Default rate limit 120 requests/min per key; a 429 carries the typed error body and a Retry-After header. Every response includes an X-Request-Id — quote it in support requests. To rotate an API key with zero downtime, issue a second key, switch, then revoke the old one; to rotate a webhook signing secret, register a second endpoint (new secret), verify deliveries, then delete the old endpoint.

Routes

A day of scheduled care (a route with one or more visits).

List routes

Authorizations:
ApiKeyAuth
query Parameters
status
string
Enum: "open" "filled" "canceled"
date
string <date>
date_from
string <date>
date_to
string <date>
external_ref
string
limit
integer [ 1 .. 100 ]
Default: 25
starting_after
string

A cursor — the id of the last object from the previous page.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "has_more": true
}

Create a route

Creates a route with its visits in one call and posts it to the caregiver marketplace. Recurrence is the caller's responsibility — post one route per date, each with its own Idempotency-Key.

Authorizations:
ApiKeyAuth
header Parameters
Idempotency-Key
string <= 191 characters

Retrying with the same key replays the original response (24h) and creates nothing.

Request Body schema: application/json
required
name
required
string
date
required
string <date>
confirmation_type
required
string
Enum: "agency_confirm" "instant_confirm"
profession_id
required
integer

A value from GET /professions.

description
string
external_ref
string

Your own id for this route. Unique per agency.

required
Array of objects (VisitCreate) non-empty

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "date": "2019-08-24",
  • "confirmation_type": "agency_confirm",
  • "profession_id": 0,
  • "description": "string",
  • "external_ref": "string",
  • "visits": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "route_10312",
  • "object": "route",
  • "status": "open",
  • "name": "string",
  • "description": "string",
  • "date": "2019-08-24",
  • "timezone": "America/Detroit",
  • "start_time": "08:00",
  • "end_time": "12:30",
  • "confirmation_type": "agency_confirm",
  • "profession_id": 0,
  • "total_pay": 0,
  • "currency": "usd",
  • "external_ref": "string",
  • "visits": [
    ],
  • "bids": {
    },
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "livemode": true,
  • "created_at": "2019-08-24T14:15:22Z"
}

Retrieve a route

Returns the route with its visits and the full bid list (bids.data) including provider decision info.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Example: route_10312

Responses

Response samples

Content type
application/json
{
  • "id": "route_10312",
  • "object": "route",
  • "status": "open",
  • "name": "string",
  • "description": "string",
  • "date": "2019-08-24",
  • "timezone": "America/Detroit",
  • "start_time": "08:00",
  • "end_time": "12:30",
  • "confirmation_type": "agency_confirm",
  • "profession_id": 0,
  • "total_pay": 0,
  • "currency": "usd",
  • "external_ref": "string",
  • "visits": [
    ],
  • "bids": {
    },
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "livemode": true,
  • "created_at": "2019-08-24T14:15:22Z"
}

Cancel a route

Idempotent. A route with an accepted caregiver or recorded work returns 422 route_not_cancelable — unwind it in the Quinable portal.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Example: route_10312
header Parameters
Idempotency-Key
string <= 191 characters

Retrying with the same key replays the original response (24h) and creates nothing.

Request Body schema: application/json
optional
reason
string

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "id": "route_10312",
  • "object": "route",
  • "status": "open",
  • "name": "string",
  • "description": "string",
  • "date": "2019-08-24",
  • "timezone": "America/Detroit",
  • "start_time": "08:00",
  • "end_time": "12:30",
  • "confirmation_type": "agency_confirm",
  • "profession_id": 0,
  • "total_pay": 0,
  • "currency": "usd",
  • "external_ref": "string",
  • "visits": [
    ],
  • "bids": {
    },
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "livemode": true,
  • "created_at": "2019-08-24T14:15:22Z"
}

Simulate a route's lifecycle (test mode only)

Test keys only. Drives a sandbox route through bid → accept → clock in/out → timesheet approved/paid, creating synthetic bids and timesheets and firing the bid.* / visit.* / timesheet.* webhooks — so you can exercise your receiver without a real caregiver or any money movement. A live key returns 400 not_in_test_mode.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Example: route_10312
Request Body schema: application/json
optional
until
string
Default: "paid"
Enum: "placed" "accepted" "clocked_in" "clocked_out" "approved" "paid"

Responses

Request samples

Content type
application/json
{
  • "until": "placed"
}

Response samples

Content type
application/json
{
  • "id": "route_10312",
  • "object": "route",
  • "status": "open",
  • "name": "string",
  • "description": "string",
  • "date": "2019-08-24",
  • "timezone": "America/Detroit",
  • "start_time": "08:00",
  • "end_time": "12:30",
  • "confirmation_type": "agency_confirm",
  • "profession_id": 0,
  • "total_pay": 0,
  • "currency": "usd",
  • "external_ref": "string",
  • "visits": [
    ],
  • "bids": {
    },
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "livemode": true,
  • "created_at": "2019-08-24T14:15:22Z"
}