> ## Documentation Index
> Fetch the complete documentation index at: https://jobticket-docs.ticket-plus.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Integrate your HR systems with the JobTicket+ JobTicket platform

## Overview

The JobTicket B2B API lets employers and HR platforms manage employee transit subscriptions programmatically — retrieve employee records, manage documents, trigger HR syncs, and receive real-time events via webhooks.

<Info>
  **API access is disabled by default.** To get started, contact JobTicket+ support at [support@jobticket-plus.app](mailto:support@jobticket-plus.app) to request that API access is enabled for your company account. Once enabled, you can manage your API keys and webhooks from the [Developer Portal](/v1/developer-portal).
</Info>

***

## Base URLs

| Environment | Base URL                                 |
| ----------- | ---------------------------------------- |
| Staging     | `https://v1-api-staging.ticket-plus.app` |
| Production  | `https://v1-api.ticket-plus.app`         |

<Warning>
  Always develop and test against **staging** before switching to production.
</Warning>

***

## Authentication

All endpoints use **HTTP Basic Auth** — Base64-encode your `username:password` and pass it in the `Authorization` header.

```http theme={null}
Authorization: Basic <base64(username:password)>
```

Invalid or missing credentials return `401 Unauthorized`. Manage your API keys in the [Developer Portal](/v1/developer-portal).

***

## Key Concepts

<AccordionGroup>
  <Accordion title="Pagination" icon="list">
    All list endpoints use page-based pagination via `page` (default `1`) and
    `perPage` (default `10`, max `100`) query parameters. Responses wrap results
    in a `data` envelope with `page`, `perPage`, `totalPages`, and `total` fields.
  </Accordion>

  <Accordion title="Sorting" icon="arrow-up-arrow-down">
    Pass `sortField` and `sortOrder` (`asc` / `desc`) on any list endpoint.
    Allowed sort fields vary per endpoint — see the individual endpoint reference.
  </Accordion>

  <Accordion title="HAL Links (_links)" icon="link">
    Every resource includes a `_links` object with pre-built `href` + `type` pairs
    for related resources (e.g. `self`, `employeeDocuments`). Use these instead of
    constructing URLs manually.
  </Accordion>
</AccordionGroup>

***

## Rate Limiting

**100 requests per minute** per API credential (60-second rolling window). Exceeding the limit returns `429 Too Many Requests` and blocks your credentials for **5 minutes**.

<Tip>
  Prefer paginated list calls (up to 100 results per page) over many
  single-record fetches to stay within limits.
</Tip>

***

## Error Codes

| Code                  | Meaning                                                                                                    |
| --------------------- | ---------------------------------------------------------------------------------------------------------- |
| `200`                 | Success                                                                                                    |
| `204`                 | Success, no body                                                                                           |
| `400`                 | Malformed request — fix before retrying                                                                    |
| `401`                 | Invalid or missing credentials                                                                             |
| `403`                 | Valid credentials but insufficient permissions                                                             |
| `404`                 | Resource not found — check the `id` in the path                                                            |
| `409`                 | Conflict with current resource state                                                                       |
| `422`                 | Business-logic validation failed — response body has field-level details                                   |
| `429`                 | Rate limit exceeded — wait for `retry-after` seconds                                                       |
| `500`                 | Server error — contact [developer-support@jobticket-plus.app](mailto:developer-support@jobticket-plus.app) |
| `502` / `503` / `504` | Gateway/upstream issues — retry with exponential back-off                                                  |

***

## Support

For integration questions or credential requests, contact your JobTicket+ account manager or email [developer-support@jobticket-plus.app](mailto:developer-support@jobticket-plus.app).