> ## 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.
# List Employees
> Retrieve a paginated, filterable list of all employees in your company.
Returns all employees with their subscription status, plan details, current transit ticket, and HR integration links. Use the filter parameters to narrow results by status, plan type, email, or specific IDs.
```bash cURL theme={null}
curl --request GET \
--url "https://v1-api.ticket-plus.app/employees?page=1&perPage=10" \
--header "Authorization: Basic "
```
```python Python theme={null}
import requests
import base64
credentials = base64.b64encode(b":").decode()
res = requests.get(
"https://v1-api.ticket-plus.app/employees",
params={"page": 1, "perPage": 10},
headers={"Authorization": f"Basic {credentials}"},
)
print(res.json())
```
```javascript Node.js theme={null}
const credentials = Buffer.from(":").toString("base64");
const res = await fetch(
"https://v1-api.ticket-plus.app/employees?page=1&perPage=10",
{ headers: { Authorization: `Basic ${credentials}` } }
);
console.log(await res.json());
```
```json 200 theme={null}
{
"data": {
"data": [
{
"id": 42,
"firstName": "Anna",
"lastName": "Müller",
"email": "anna.mueller@example.com",
"dateOfBirth": "1990-04-15",
"profileImage": null,
"resource": "employee",
"subscription": {
"status": "active",
"startAt": "2024-01-01",
"nextTicketAt": "2024-06-01",
"pausedAt": null,
"cancelledAt": null,
"reactivatedAt": null
},
"plan": {
"type": "fully-subsidized-plan",
"contractSigningStatus": "accepted",
"employeeContributionAmount": null
},
"ticket": {
"ticketId": "tkt_9Xk2mPqL",
"ticketMonth": "2024-05",
"validFrom": "2024-05-01",
"validUntil": "2024-05-31",
"links": {
"apple": "https://wallet.example.com/apple/tkt_9Xk2mPqL",
"google": "https://wallet.example.com/google/tkt_9Xk2mPqL"
}
},
"hrIntergartionLinks": [],
"_links": {
"self": { "href": "https://v1-api.ticket-plus.app/employees/42", "type": "application/json" },
"employeeDocuments": { "href": "https://v1-api.ticket-plus.app/employees/42/documents", "type": "application/json" }
}
}
],
"page": 1,
"perPage": 10,
"totalPages": 5,
"total": 47
}
}
```
## Query Parameters
Full-text search across employee names and email addresses.
Page number to return. Starts at `1`.
Number of results per page. Maximum is `100`.
Sort direction. Allowed values: `asc`, `desc`.
Field to sort results by. Allowed values: `id`, `createdAt`, `updatedAt`.
Filter to a specific set of employee IDs.
Filter to specific employee email addresses.
Filter by subscription status. Allowed values: `no-subscription`, `scheduled`, `active`, `scheduled-pause`, `paused`, `scheduled-cancellation`, `cancelled`.
Filter by plan type. Allowed values: `fully-subsidized-plan`, `deferred-plan`, `split-pay-plan`.
## Response
Array of employee objects.
Unique employee identifier.
Employee's first name.
Employee's last name.
Employee's email address.
Date of birth in ISO 8601 format. `null` if not set.
URL to the employee's profile photo. `null` if not set.
Resource type label. Always `"employee"`.
Current subscription details.
Current subscription state. Allowed values: `no-subscription`, `scheduled`, `active`, `scheduled-pause`, `paused`, `scheduled-cancellation`, `cancelled`.
Date the subscription started. `null` if not yet started.
Date the next transit ticket will be issued. `null` if not applicable.
Date the subscription was paused. `null` if never paused.
Date the subscription was cancelled. `null` if not cancelled.
Date the subscription was reactivated after a pause or cancellation. `null` if never reactivated.
The employee's plan details.
Plan type. Allowed values: `fully-subsidized-plan`, `deferred-plan`, `split-pay-plan`.
Contract state. Allowed values: `pending`, `accepted`, `rejected`. `null` if no contract applies.
Employee's contribution amount. Only present for `split-pay-plan`. `null` for other plan types.
Formatted display string, e.g. `"€29.00"`.
Raw contribution amount, in cents (no decimals).
The employee's current active transit ticket. `null` if no ticket has been issued yet.
Unique ticket identifier.
Month the ticket is valid for, e.g. `"2024-05"`.
Ticket validity start date.
Ticket validity end date.
Digital wallet pass links.
Apple Wallet pass URL.
Google Pay pass URL.
HR system associations for this employee.
Link type. Allowed values: `custom` (manually linked), `hr-integration` (synced via an HR integration).
The employee's ID in the external HR system.
ID of the HR integration this link belongs to. `null` for `custom` links.
ID of the last sync that updated this link. `null` if never synced.
Timestamp of the last sync. `null` if never synced.
HAL hypermedia links.
Link to this employee resource.
URL of this employee.
Media type.
Link to this employee's documents.
URL to list this employee's documents.
Media type.
Current page number returned.
Number of results per page.
Total number of pages available.
Total number of employees matching your filters.
## OpenAPI
````yaml GET /employees
openapi: 3.0.3
info:
title: JobTicket API
description: >-
The JobTicket B2B API lets you read employee data, manage HR integrations,
and access employee documents programmatically. All endpoints use HTTP Basic
Auth — pass your API key credentials from the Developer Portal as the
username and password.
version: 1.0.0
servers:
- url: https://v1-api-staging.ticket-plus.app
description: Staging server
- url: https://v1-api.ticket-plus.app
description: Production Server
security:
- basicAuth: []
externalDocs:
url: https://jobticket-docs.ticket-plus.app
description: View our documentation to get more info
paths:
/employees:
get:
tags:
- Employees
summary: Paginate Employees
description: >-
Returns a paginated, filterable list of all employees in your company.
Each record includes subscription status, plan details, current transit
ticket, and HR integration links. Requires the `view-employees`
permission.
parameters:
- schema:
type: string
nullable: true
in: query
name: search
required: false
description: Full-text search across employee names and email addresses.
- schema:
type: integer
minimum: 0
default: 1
nullable: true
in: query
name: page
required: false
description: Page number to return. Starts at 1.
- schema:
type: integer
minimum: 0
maximum: 100
default: 10
nullable: true
in: query
name: perPage
required: false
description: Number of results per page. Maximum is 100.
- schema:
type: string
enum:
- asc
- desc
default: desc
nullable: true
in: query
name: sortOrder
required: false
description: Sort direction — `asc` for ascending, `desc` for descending.
- schema:
type: string
enum:
- id
- createdAt
- updatedAt
default: id
nullable: true
in: query
name: sortField
required: false
description: Field to sort results by.
- schema:
type: array
items:
type: integer
minimum: 0
nullable: true
in: query
name: ids
required: false
description: Filter to a specific set of employee IDs.
- schema:
type: array
items:
type: string
nullable: true
in: query
name: emails
required: false
description: Filter to specific employee email addresses.
- schema:
type: array
items:
type: string
enum:
- no-subscription
- cancelled
- scheduled-cancellation
- active
- scheduled
- scheduled-pause
- paused
nullable: true
in: query
name: subscriptionStatuses
required: false
description: >-
Filter by subscription status. Accepted values: `no-subscription`,
`cancelled`, `scheduled-cancellation`, `active`, `scheduled`,
`scheduled-pause`, `paused`.
- schema:
type: array
items:
type: string
enum:
- fully-subsidized-plan
- deferred-plan
- split-pay-plan
nullable: true
in: query
name: planTypes
required: false
description: >-
Filter by plan type. Accepted values: `fully-subsidized-plan`,
`deferred-plan`, `split-pay-plan`.
responses:
'200':
description: A paginated list of employees.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
data:
type: array
description: Array of employee objects.
items:
type: object
properties:
id:
type: integer
description: Unique employee identifier.
firstName:
type: string
description: Employee's first name.
lastName:
type: string
description: Employee's last name.
email:
type: string
description: Employee's email address.
dateOfBirth:
type: string
nullable: true
description: Date of birth in ISO 8601 format.
profileImage:
type: string
nullable: true
description: URL to the employee's profile image.
subscription:
type: object
description: Current subscription details.
properties:
status:
type: string
description: >-
Subscription state: `no-subscription`,
`cancelled`, `scheduled-cancellation`,
`active`, `scheduled`, `scheduled-pause`, or
`paused`.
enum:
- no-subscription
- cancelled
- scheduled-cancellation
- active
- scheduled
- scheduled-pause
- paused
startAt:
type: string
nullable: true
description: Date the subscription started.
nextTicketAt:
type: string
nullable: true
description: Date the next ticket will be issued.
pausedAt:
type: string
nullable: true
description: Date the subscription was paused.
cancelledAt:
type: string
nullable: true
description: Date the subscription was cancelled.
reactivatedAt:
type: string
nullable: true
description: Date the subscription was reactivated.
required:
- status
hrIntergartionLinks:
type: array
description: HR system associations for this employee.
items:
type: object
properties:
type:
type: string
enum:
- custom
- hr-integration
description: >-
Link type: `custom` (manually linked) or
`hr-integration` (synced via an HR
integration).
hrId:
type: string
description: The employee's ID in the HR system.
hrIntegrationId:
type: number
nullable: true
description: >-
ID of the HR integration this link belongs
to.
lastSyncId:
type: string
nullable: true
description: >-
ID of the last sync that updated this
link.
lastSynced:
type: string
nullable: true
description: >-
Timestamp of the last sync that updated
this link.
required:
- type
- hrId
plan:
type: object
description: The employee's plan details.
properties:
type:
type: string
description: >-
Plan type: `fully-subsidized-plan`,
`deferred-plan`, or `split-pay-plan`.
contractSigningStatus:
type: string
nullable: true
description: >-
Contract state: `pending`, `accepted`, or
`rejected`.
employeeContributionAmount:
type: object
nullable: true
description: >-
Employee's contribution amount for split-pay
plans.
properties:
label:
type: string
description: Formatted display string, e.g. `€29.00`.
value:
type: integer
description: >-
Raw contribution amount, in cents (no
decimals).
required:
- type
ticket:
type: object
nullable: true
description: >-
The employee's current active transit ticket.
`null` if no ticket has been issued.
properties:
ticketId:
type: string
description: Unique ticket identifier.
ticketMonth:
type: string
description: >-
Month this ticket is valid for, e.g.
`2024-05`.
validFrom:
type: string
description: Ticket validity start date.
validUntil:
type: string
description: Ticket validity end date.
links:
type: object
description: Digital wallet pass links.
properties:
apple:
type: string
description: Apple Wallet pass URL.
google:
type: string
description: Google Pay pass URL.
required:
- apple
- google
required:
- ticketId
- ticketMonth
- validFrom
- validUntil
- links
resource:
type: string
description: Resource type label, always `employee`.
_links:
type: object
description: HAL hypermedia links.
properties:
self:
type: object
description: Link to this employee.
properties:
href:
type: string
type:
type: string
required:
- href
- type
employeeDocuments:
type: object
description: Link to this employee's documents.
properties:
href:
type: string
type:
type: string
required:
- href
- type
required:
- self
- employeeDocuments
required:
- id
- firstName
- lastName
- email
- subscription
- hrIntergartionLinks
- plan
- resource
- _links
page:
type: integer
description: Current page number.
perPage:
type: integer
description: Number of results per page.
totalPages:
type: integer
description: Total number of pages.
total:
type: integer
description: Total number of matching employees.
required:
- data
- page
- perPage
- totalPages
- total
required:
- data
security:
- basicAuth: []
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic Auth using your API key credentials. Use the username and
password issued from the Developer Portal. Encode them as
`Base64(username:password)` and pass in the `Authorization: Basic
` header.
````