List Employees

Retrieve a paginated, filterable list of all employees in your company.

GET /employees

cURL

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

200

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

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

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

200

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

search · 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

id · integer · required

Unique employee identifier.

firstName · string · required

Employee’s first name.

lastName · string · required

Employee’s last name.

email · 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

search · 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