Getting Started

This guide takes you from an organization with the API switched off to a working request in a few minutes.

Before you begin

• Your organization is on a paid plan (Pro, Business or Enterprise).
• To switch the API on you need the Executive role. To create a token you need a role your organization allows to create tokens (Administrators and Executives by default).

1. Switch the API on

1. Go to Settings > API and open the Settings tab.
2. Turn on Enable the API.
3. Optionally adjust the other two settings on the same tab:
   • Maximum token lifetime — every token must expire within this many days of being created. It can be between 1 and 365 days and defaults to 90. Lowering it does not shorten tokens that already exist.
   • Who may create tokens — the roles allowed to hold and create tokens. Administrators and Executives by default.

2. Create a token

1. On the Tokens tab, click Create token.
2. Give it a Name that says what uses it, such as "Payroll export" or "HRIS nightly sync".
3. Choose its Owner. It defaults to you. Administrators and Executives can create a token for someone else, but only for a person whose role is below their own; a colleague in the same role creates their own token.
4. Under Access, either pick an API role or choose custom scopes. Grant only what the integration needs. See API Roles & Scopes.
5. Choose when it Expires: a preset (7, 30, 60, 90, 180 or 365 days, limited to your organization's maximum) or a specific date. A date means the end of that day in your timezone.
6. Optionally restrict it to Allowed IP addresses.
7. Click Create token.

The token is shown once. Copy it into your secret store now; it cannot be displayed again. If it is lost, rotate the token to get a new secret.

Team members whose role is allowed to create tokens, but who are not Administrators or Executives, find their own tokens under Settings > Personal API Tokens.

3. Make your first request

Send the token in the Authorization header. Start with GET /token, which needs no particular scope and tells you what the token can do:

curl https://app.bookyourpto.com/api/v1/token \
  -H "Authorization: Bearer $BOOKYOURPTO_TOKEN"

{
  "data": {
    "id": "cm...",
    "name": "Payroll export",
    "prefix": "pat_Xy3kQ9Lm",
    "api_role": { "id": "cm...", "name": "Time and payroll export" },
    "owner": {
      "id": "cm...",
      "first_name": "Dana",
      "last_name": "Okafor",
      "email": "dana@example.com",
      "role": "ADMINISTRATOR"
    },
    "scopes": ["organization:read", "users:read"],
    "expires_at": "2027-01-10T07:59:59.999Z",
    "created_at": "2026-10-12T16:20:41.118Z"
  },
  "meta": { "request_id": "8f2c4b1e-..." }
}

scopes is the token's effective set for this request: what it was granted, limited by its owner's current role and by the endpoints available today.

Then read your organization's settings, which needs the organization:read scope:

curl https://app.bookyourpto.com/api/v1/organization \
  -H "Authorization: Bearer $BOOKYOURPTO_TOKEN"

4. Read the response

Every response is JSON in the same envelope:

• A successful response has data (an object or a list) and meta.
• A failed response has error with a machine-readable code and a human-readable message, plus meta.
• meta.request_id identifies the request. The same value is returned in the X-Request-Id header. Quote it when you contact support.

{
  "error": {
    "code": "SCOPE_MISSING",
    "message": "This token is missing the organization:read scope."
  },
  "meta": { "request_id": "3a91d0c2-..." }
}

Branch on error.code, never on the message text. The full list is on the Errors page.

Next steps

• Follow a guide for the area you are integrating: People, Leave, Time or Expenses & Documents.
• Browse every endpoint in the API Reference, or import the Postman collection.
• Learn how lists are paginated in Requests & Responses.
• Plan for Rate Limits before you run a bulk sync.
• Subscribe to webhooks instead of polling for changes.
• Set a reminder to rotate the token before it expires. The owner is also emailed seven days before expiry.