Skip to main content
POST
/
v3
/
order
/
{order_id}
/
phlebotomy
/
appointment
/
book
curl --request POST \
     --url '{{BASE_URL}}/v3/order/413d7205-f8a9-42ed-aa4a-edb99e481ca0/phlebotomy/appointment/book' \
     --header 'accept: application/json' \
     --header 'x-vital-api-key: {YOUR_KEY}' \
     --data '
{
    "booking_key": "foo123"
}
'

{
    "id": "413d7205-f8a9-42ed-aa4a-edb99e481ca0",
    "user_id": "202b2c2f-fb4c-44dc-a4f8-621186fde227",
    "address": {
        "first_line": "West Lincoln Street",
        "second_line": "",
        "city": "Phoenix",
        "state": "AZ",
        "zip_code": "85004",
        "unit": "14"
    },
    "location": {
        "lng": -112.0772235,
        "lat": 33.4421912
    },
    "start_at": "2023-05-15T16:00:00+00:00",
    "end_at": "2023-05-15T18:00:00+00:00",
    "iana_timezone": "America/Phoenix",
    "type": "phlebotomy",
    "provider": "getlabs",
    "status": "pending",
    "provider_id": "e89eb489-7382-4966-bb14-7ab4763eba6c",
    "can_reschedule":true
}

curl --request POST \
     --url '{{BASE_URL}}/v3/order/413d7205-f8a9-42ed-aa4a-edb99e481ca0/phlebotomy/appointment/book' \
     --header 'accept: application/json' \
     --header 'x-vital-api-key: {YOUR_KEY}' \
     --data '
{
    "booking_key": "foo123"
}
'

{
    "id": "413d7205-f8a9-42ed-aa4a-edb99e481ca0",
    "user_id": "202b2c2f-fb4c-44dc-a4f8-621186fde227",
    "address": {
        "first_line": "West Lincoln Street",
        "second_line": "",
        "city": "Phoenix",
        "state": "AZ",
        "zip_code": "85004",
        "unit": "14"
    },
    "location": {
        "lng": -112.0772235,
        "lat": 33.4421912
    },
    "start_at": "2023-05-15T16:00:00+00:00",
    "end_at": "2023-05-15T18:00:00+00:00",
    "iana_timezone": "America/Phoenix",
    "type": "phlebotomy",
    "provider": "getlabs",
    "status": "pending",
    "provider_id": "e89eb489-7382-4966-bb14-7ab4763eba6c",
    "can_reschedule":true
}

Authorizations

​
x-vital-api-key
string
header
required

Vital Team API Key

Path Parameters

​
order_id
string<uuid>
required

Your Order ID.

Body

application/json
​
booking_key
string
required
​
async_confirmation
boolean
default:false

[!] This feature (Async Confirmation) is under Closed Beta.

If true, when the PSC system fails to confirm the booking within sync_confirmation_timeout_millisecond, this API endpoint would respond with a pending appointment. The booking attempt will continue asynchronously in background, until either:

  1. the appointment moves to the reserved or confirmed state because an acknowledgement from the PSC system has been received; OR
  2. the pending appointment moves to the cancelled state because the async_confirmation_timeout_millisecond timeout is reached.

You will receive labtest.appointment.updated webhooks for all the relevant status changes (pending, confirmed, reserved and cancelled).

If false (default), when the PSC system fails to confirm the booking, this API endpoint would respond with 500 Internal Server Error.

​
sync_confirmation_timeout_millisecond
integer | null

This parameter only takes effect when async_confirmation is true; no-op otherwise.

The maximum amount of time which the Book Appointment endpoint would wait before it responds with a pending appointment. This timeout does not stop the booking attempt — it will continue asynchronously in background.

Defaults to 2.5 seconds. Must be 1-10 seconds.

Required range: 1000 <= x <= 10000
​
async_confirmation_timeout_millisecond
integer | null

This parameter only takes effect when async_confirmation is true; no-op otherwise.

The maximum amount of time which Junction would try to asynchronously book in the pending appointment. If this timeout is reached, the pending appointment would be cancelled.

Defaults to 15 minutes. Must be 1-2880 minutes.

Required range: 60000 <= x <= 172800000

Response

Successful Response

​
id
string<uuid4>
required
​
user_id
string<uuid4>
required
​
order_id
string<uuid4>
required
​
address
USAddress · object
required
​
location
LngLat · object
required
​
start_at
string<date-time> | null
required

Time is in UTC

​
end_at
string<date-time> | null
required

Time is in UTC

​
type
enum<string>
required

ℹ️ This enum is non-exhaustive.

Available options:
phlebotomy,
patient_service_center
​
provider
enum<string>
required

ℹ️ This enum is non-exhaustive.

Available options:
getlabs,
phlebfinders,
quest
​
status
enum<string>
required

ℹ️ This enum is non-exhaustive.

Available options:
confirmed,
pending,
reserved,
in_progress,
completed,
cancelled
​
provider_id
string
required
​
can_reschedule
boolean
required
​
event_status
enum<string>
required

ℹ️ This enum is non-exhaustive.

Available options:
pending,
reserved,
scheduled,
completed,
cancelled,
in_progress
​
events
ClientFacingAppointmentEvent · object[]
required
​
iana_timezone
string | null
​
external_id
string | null
​
event_data
Event Data · object