Skip to content
digizeDocs

Book an appointment

POST
/api/v1/appointments
curl --request POST \
  --url https://digize.com/api/v1/appointments \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 5f1c2a8e-3b7d-4c55-9a0e-1f2d3c4b5a69' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "calendarId": "example", "contactId": "example", "customer": { "firstName": "example", "lastName": "example", "email": "example", "phone": "example" }, "staffId": "example", "partySize": 1, "startsAt": "2026-04-15T12:00:00Z", "notes": "example" }'

Books a customer on a calendar from the team’s side: an existing contact by contactId, or customer to find or add one. Left out, staffId goes to whoever on the team is free and least booked. Nobody is booked twice at once. A calendar with a deposit leaves it due and emails the customer a link to pay it.

Needs the crm:write permission.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
>= 1 characters <= 255 characters

Makes the request safe to send again: for 24 hours the same key and request answer the first response without repeating the change.

Example 

5f1c2a8e-3b7d-4c55-9a0e-1f2d3c4b5a69

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
calendarId
required
string
>= 1 characters <= 64 characters
contactId
Any of:
string
>= 1 characters <= 64 characters
customer
object
firstName
required
string
<= 80 characters
lastName
string
<= 80 characters
email
Any of:
string
<= 254 characters
phone
Any of:
string
<= 40 characters
staffId
Any of:
string
>= 1 characters <= 64 characters
partySize
integer
>= 1 <= 50
startsAt
required
string format: date-time
notes
Any of:
string
<= 2000 characters

Example generated

{
  "calendarId": "example",
  "contactId": "example",
  "customer": {
    "firstName": "example",
    "lastName": "example",
    "email": "example",
    "phone": "example"
  },
  "staffId": "example",
  "partySize": 1,
  "startsAt": "2026-04-15T12:00:00Z",
  "notes": "example"
}

Responses

Section titled “Responses”

201

Section titled “201”

Done

Media typeapplication/json
object
id
required
string
calendarId
required
string
service
required

The calendar’s name when it was booked.

string
customer
required
object
id
required

The contact’s id.

string
name
required
string
email
required
string
phone
required
string
staff
required
object
id
required

The team member’s user id.

string
name
required
string
partySize
required
number
startsAt
required
string format: date-time
endsAt
required
string format: date-time
status
required
string
Allowed values: confirmed deposit_due completed cancelled no_show
total
required

The price for the whole party.

integer
<= 100000000
deposit
required

The deposit for the whole party.

integer
<= 100000000
depositPaidAt
required
Any of:
string format: date-time
depositRefunded
required
boolean
paymentId
required

The Stripe PaymentIntent that took the deposit.

string | null
notes
required
string | null
bookedVia
required
string
Allowed values: site staff
bookedAt
required
string format: date-time

Example 

{
  "status": "confirmed",
  "bookedVia": "site"
}

400

Section titled “400”

What was sent isn’t valid (invalid).

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: invalid unauthorized forbidden not_found conflict too_large rate_limited unavailable internal
message
required
string
details
object
key
additional properties
any

Example 

{
  "error": {
    "code": "invalid"
  }
}

401

Section titled “401”

No key, or one that’s unknown, off or expired.

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: invalid unauthorized forbidden not_found conflict too_large rate_limited unavailable internal
message
required
string
details
object
key
additional properties
any

Example 

{
  "error": {
    "code": "invalid"
  }
}

403

Section titled “403”

The key doesn’t have the permission this needs.

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: invalid unauthorized forbidden not_found conflict too_large rate_limited unavailable internal
message
required
string
details
object
key
additional properties
any

Example 

{
  "error": {
    "code": "invalid"
  }
}

404

Section titled “404”

Nothing has that id (not_found).

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: invalid unauthorized forbidden not_found conflict too_large rate_limited unavailable internal
message
required
string
details
object
key
additional properties
any

Example 

{
  "error": {
    "code": "invalid"
  }
}

409

Section titled “409”

A request with the same Idempotency-Key is still running (conflict).

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: invalid unauthorized forbidden not_found conflict too_large rate_limited unavailable internal
message
required
string
details
object
key
additional properties
any

Example 

{
  "error": {
    "code": "invalid"
  }
}

422

Section titled “422”

The Idempotency-Key was used with a different request.

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: invalid unauthorized forbidden not_found conflict too_large rate_limited unavailable internal
message
required
string
details
object
key
additional properties
any

Example 

{
  "error": {
    "code": "invalid"
  }
}

429

Section titled “429”

Over the rate limit; see retry-after.

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: invalid unauthorized forbidden not_found conflict too_large rate_limited unavailable internal
message
required
string
details
object
key
additional properties
any

Example 

{
  "error": {
    "code": "invalid"
  }
}