Skip to main content
POST
Create approval delegation

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Approval delegation creation payload.

starts_at
string<date-time>
required

UTC timestamp when the delegation starts.

Example:

"2026-12-21T00:00:00Z"

ends_at
string<date-time>
required

UTC timestamp when the delegation ends. Must be in the future.

Example:

"2027-01-04T00:00:00Z"

delegator_id
string

ID of the account member whose approvals are delegated. Supply exactly one of delegator_id or delegator_email.

Minimum string length: 1
Example:

"usr_4sYw1nB8xKe0Qm"

delegator_email
string<email>

Email of the account member whose approvals are delegated, matched case-insensitively. Supply exactly one of delegator_id or delegator_email.

Example:

"jane@acme.com"

delegate_id
string

ID of the account member who approves on behalf of the delegator. Supply exactly one of delegate_id or delegate_email.

Minimum string length: 1
Example:

"usr_7GhT2pLq9ZcV3r"

delegate_email
string<email>

Email of the account member who approves on behalf of the delegator, matched case-insensitively. Supply exactly one of delegate_id or delegate_email.

Example:

"john@acme.com"

reason
string | null

Free-text reason, such as an out-of-office period. Maximum 500 characters.

Maximum string length: 500
Example:

"Christmas holidays"

acting_user_id
string

ID of the account member performing the action, recorded as its author. Supply at most one of acting_user_id or acting_user_email. With an API key and no acting user, the action is attributed to the API key. With a user token, it must be the authenticated user.

Minimum string length: 1
acting_user_email
string<email>

Email of the account member performing the action, matched case-insensitively. Supply at most one of acting_user_id or acting_user_email. With an API key and no acting user, the action is attributed to the API key. With a user token, it must be the authenticated user.

Response

id
string
required

Approval delegation ID.

Example:

"apd_9dKs02LmPq1a3Z"

status
enum<string>
required

Lifecycle status: scheduled before starts_at, active between starts_at and ends_at, expired after ends_at, revoked once revoked.

Available options:
scheduled,
active,
expired,
revoked
Example:

"active"

delegator_id
string
required

ID of the user whose approvals are delegated, typically the one out of office.

Example:

"usr_4sYw1nB8xKe0Qm"

delegate_id
string
required

ID of the user who approves on behalf of the delegator.

Example:

"usr_7GhT2pLq9ZcV3r"

starts_at
string<date-time>
required

UTC timestamp when the delegation starts.

Example:

"2026-12-21T00:00:00Z"

ends_at
string<date-time>
required

UTC timestamp when the delegation ends. Must be in the future.

Example:

"2027-01-04T00:00:00Z"

reason
string | null
required

Free-text reason, such as an out-of-office period.

Example:

"Christmas holidays"

created_at
string<date-time>
required

UTC timestamp when the delegation was created.

Example:

"2024-12-20T16:04:11Z"

revoked_at
string<date-time> | null
required

UTC timestamp when the delegation was revoked, or null.

Example:

"2024-12-20T16:04:11Z"