API docs by Redocly

Quinable Partner API (1.0.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). List endpoints use cursor pagination (limit, starting_after). Errors use real HTTP status codes plus a typed body.

Clients

The people care is delivered to.

List clients

Authorizations:
ApiKeyAuth
query Parameters
external_ref
string

Return the client with this partner-supplied id.

archived
boolean
Default: false
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 client

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
first_name
required
string
last_name
required
string
email
string
mobile
string
external_ref
string

Your own id for this client. Unique per agency.

required
object

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "mobile": "string",
  • "external_ref": "string",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "id": "client_841",
  • "object": "client",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "mobile": "string",
  • "address": {
    },
  • "timezone": "America/Detroit",
  • "external_ref": "string",
  • "archived": true,
  • "livemode": true,
  • "created_at": "2019-08-24T14:15:22Z"
}

Retrieve a client

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Example: client_841

Responses

Response samples

Content type
application/json
{
  • "id": "client_841",
  • "object": "client",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "mobile": "string",
  • "address": {
    },
  • "timezone": "America/Detroit",
  • "external_ref": "string",
  • "archived": true,
  • "livemode": true,
  • "created_at": "2019-08-24T14:15:22Z"
}

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"
}

Bids

Caregiver offers on a route (read-only).

Retrieve a bid

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Example: bid_9917

Responses

Response samples

Content type
application/json
{
  • "id": "bid_9917",
  • "object": "bid",
  • "route": "route_10312",
  • "status": "pending",
  • "amount": 0,
  • "currency": "usd",
  • "provider": {
    },
  • "placed_at": "2019-08-24T14:15:22Z",
  • "status_changed_at": "2019-08-24T14:15:22Z"
}

Timesheets

Worked-time records (read-only).

List timesheets

Authorizations:
ApiKeyAuth
query Parameters
route
string
Example: route=route_10312
date
string <date>

Filter by clock-in calendar date (UTC).

status
string
Enum: "pending" "approved" "rejected"
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
}

Retrieve a timesheet

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Example: ts_4410

Responses

Response samples

Content type
application/json
{
  • "id": "ts_4410",
  • "object": "timesheet",
  • "route": "string",
  • "visit": "string",
  • "bid": "string",
  • "status": "pending",
  • "pay_status": null,
  • "clock_in_at": "2019-08-24T14:15:22Z",
  • "clock_out_at": "2019-08-24T14:15:22Z",
  • "duration_seconds": 0
}

Events & Webhooks

Lifecycle events and the endpoints they are delivered to.

List events

Poll fallback and post-outage catch-up for webhooks. Requires any read scope.

Authorizations:
ApiKeyAuth
query Parameters
type
string
Example: type=bid.accepted
created_after
string <date-time>
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
}

Retrieve an event

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Example: evt_01J5XV9GJ2M4

Responses

Response samples

Content type
application/json
{
  • "id": "evt_01J5XV9GJ2M4",
  • "object": "event",
  • "type": "route.created",
  • "created_at": "2019-08-24T14:15:22Z",
  • "livemode": true,
  • "data": {
    }
}

List webhook endpoints

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Register a webhook endpoint

The signing secret (qwhsec_…) is returned once, in this response only.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
url
required
string <uri>

An https:// URL. Internal/loopback targets are rejected.

enabled_events
required
Array of strings

Event types to receive, or ["*"] for all.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "we_12",
  • "object": "webhook_endpoint",
  • "url": "http://example.com",
  • "enabled_events": [
    ],
  • "status": "enabled",
  • "created_at": "2019-08-24T14:15:22Z",
  • "secret": "qwhsec_xxx"
}

Delete a webhook endpoint

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Example: we_12

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Reference

Supporting lookups.

List professions

The profession_id values valid for POST /routes.

Authorizations:
ApiKeyAuth

Responses

Response samples

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