List Employees

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.

curl --request GET \
  --url "https://v1-api.ticket-plus.app/employees?page=1&perPage=10" \
  --header "Authorization: Basic <base64(clientId:clientSecret)>"

{
  "data": {
    "data": [
      {
        "id": 42,
        "firstName": "Anna",
        "lastName": "Müller",
        "email": "[email protected]",
        "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

string

Full-text search across employee names and email addresses.

page

integer

default:"1"

Page number to return. Starts at 1.

perPage

integer

default:"10"

Number of results per page. Maximum is 100.

sortOrder

string

default:"desc"

Sort direction. Allowed values: asc, desc.

sortField

string

default:"id"

Field to sort results by. Allowed values: id, createdAt, updatedAt.

ids

integer[]

Filter to a specific set of employee IDs.

emails

string[]

Filter to specific employee email addresses.

subscriptionStatuses

string[]

Filter by subscription status. Allowed values: no-subscription, scheduled, active, scheduled-pause, paused, scheduled-cancellation, cancelled.

planTypes

string[]

Filter by plan type. Allowed values: fully-subsidized-plan, deferred-plan, split-pay-plan.

Response

data

object

required

Show properties

data

object[]

required

Array of employee objects.

Show employee object

integer

required

Unique employee identifier.

firstName

string

required

Employee’s first name.

lastName

string

required

Employee’s last name.

string

required

Employee’s email address.

dateOfBirth

string | null

Date of birth in ISO 8601 format. null if not set.

profileImage

string | null

URL to the employee’s profile photo. null if not set.

resource

string

required

Resource type label. Always "employee".

subscription

object

required

Current subscription details.

Show properties

status

string

required

Current subscription state. Allowed values: no-subscription, scheduled, active, scheduled-pause, paused, scheduled-cancellation, cancelled.

startAt

string | null

Date the subscription started. null if not yet started.

nextTicketAt

string | null

Date the next transit ticket will be issued. null if not applicable.

pausedAt

string | null

Date the subscription was paused. null if never paused.

cancelledAt

string | null

Date the subscription was cancelled. null if not cancelled.

reactivatedAt

string | null

Date the subscription was reactivated after a pause or cancellation. null if never reactivated.

plan

object

required

The employee’s plan details.

Show properties

type

string

required

Plan type. Allowed values: fully-subsidized-plan, deferred-plan, split-pay-plan.

contractSigningStatus

string | null

Contract state. Allowed values: pending, accepted, rejected. null if no contract applies.

employeeContributionAmount

object | null

Employee’s contribution amount. Only present for split-pay-plan. null for other plan types.

Show properties

label

string

Formatted display string, e.g. "€29.00".

value

number

Raw numeric value of the contribution.

ticket

object | null

The employee’s current active transit ticket. null if no ticket has been issued yet.

Show properties

ticketId

string

required

Unique ticket identifier.

ticketMonth

string

required

Month the ticket is valid for, e.g. "2024-05".

validFrom

string

required

Ticket validity start date.

validUntil

string

required

Ticket validity end date.

links

object

required

Digital wallet pass links.

Show properties

apple

string

required

Apple Wallet pass URL.

google

string

required

Google Pay pass URL.

hrIntergartionLinks

object[]

required

HR system associations for this employee.

Show hr link object

type

string

required

Link type. Allowed values: custom (manually linked), hr-integration (synced via an HR integration).

hrId

string

required

The employee’s ID in the external HR system.

hrIntegrationId

number | null

ID of the HR integration this link belongs to. null for custom links.

lastSyncId

string | null

ID of the last sync that updated this link. null if never synced.

lastSynced

string | null

Timestamp of the last sync. null if never synced.

_links

object

required

HAL hypermedia links.

Show properties

self

object

required

Link to this employee resource.

Show properties

href

string

required

URL of this employee.

type

string

required

Media type.

employeeDocuments

object

required

Link to this employee’s documents.

Show properties

href

string

required

URL to list this employee’s documents.

type

string

required

Media type.

page

integer

required

Current page number returned.

perPage

integer

required

Number of results per page.

totalPages

integer

required

Total number of pages available.

total

integer

required

Total number of employees matching your filters.

Authorizations

Authorization

string

header

required

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 <token> header.

Query Parameters

string | null

Full-text search across employee names and email addresses.

page

integer | null

default:1

Page number to return. Starts at 1.

Required range: x >= 0

perPage

integer | null

default:10

Number of results per page. Maximum is 100.

Required range: 0 <= x <= 100

sortOrder

enum<string> | null

default:desc

Sort direction — asc for ascending, desc for descending.

Available options:

asc,

desc

sortField

enum<string> | null

default:id

Field to sort results by.

Available options:

id,

createdAt,

updatedAt

ids

integer[] | null

Filter to a specific set of employee IDs.

Required range: x >= 0

emails

string[] | null

Filter to specific employee email addresses.

subscriptionStatuses

enum<string>[] | null

Filter by subscription status. Accepted values: no-subscription, cancelled, scheduled-cancellation, active, scheduled, scheduled-pause, paused.

Available options:

no-subscription,

cancelled,

scheduled-cancellation,

active,

scheduled,

scheduled-pause,

paused

planTypes

enum<string>[] | null

Filter by plan type. Accepted values: fully-subsidized-plan, deferred-plan, split-pay-plan.

Available options:

fully-subsidized-plan,

deferred-plan,

split-pay-plan

Response

200 - application/json

A paginated list of employees.

data

object

required

Show child attributes

Overview

Health

Employees

Employee Documents

HR Integrations

Query Parameters

Response

Authorizations

Query Parameters

Response

Overview

Health

Employees

Employee Documents

HR Integrations

Documentation Index

​Query Parameters

​Response

Authorizations

Query Parameters

Response

Query Parameters

Response