List Employees

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

import requests
import base64

credentials = base64.b64encode(b"<clientId>:<clientSecret>").decode()

res = requests.get(
    "https://v1-api.ticket-plus.app/employees",
    params={"page": 1, "perPage": 10},
    headers={"Authorization": f"Basic {credentials}"},
)
print(res.json())

const credentials = Buffer.from("<clientId>:<clientSecret>").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());

{
  "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
  }
}

GET

employees

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

import requests
import base64

credentials = base64.b64encode(b"<clientId>:<clientSecret>").decode()

res = requests.get(
    "https://v1-api.ticket-plus.app/employees",
    params={"page": 1, "perPage": 10},
    headers={"Authorization": f"Basic {credentials}"},
)
print(res.json())

const credentials = Buffer.from("<clientId>:<clientSecret>").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());

{
  "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
  }
}

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)>"

import requests
import base64

credentials = base64.b64encode(b"<clientId>:<clientSecret>").decode()

res = requests.get(
    "https://v1-api.ticket-plus.app/employees",
    params={"page": 1, "perPage": 10},
    headers={"Authorization": f"Basic {credentials}"},
)
print(res.json())

const credentials = Buffer.from("<clientId>:<clientSecret>").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());

{
  "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

string

Full-text search across employee names and email addresses.

integer

default:"1"

Page number to return. Starts at 1.

integer

default:"10"

Number of results per page. Maximum is 100.

string

default:"desc"

Sort direction. Allowed values: asc, desc.

string

default:"id"

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

integer[]

Filter to a specific set of employee IDs.

string[]

Filter to specific employee email addresses.

string[]

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

string[]

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

Response

object

required

Show properties

object[]

required

Array of employee objects.

Show employee object

integer

required

Unique employee identifier.

string

required

Employee’s first name.

string

required

Employee’s last name.

string

required

Employee’s email address.

string | null

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

string | null

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

string

required

Resource type label. Always "employee".

object

required

Current subscription details.

Show properties

string

required

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

string | null

Date the subscription started. null if not yet started.

string | null

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

string | null

Date the subscription was paused. null if never paused.

string | null

Date the subscription was cancelled. null if not cancelled.

string | null

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

object

required

The employee’s plan details.

Show properties

string

required

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

string | null

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

object | null

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

Show properties

string

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

integer

Raw contribution amount, in cents (no decimals).

object | null

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

Show properties

string

required

Unique ticket identifier.

string

required

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

string

required

Ticket validity start date.

string

required

Ticket validity end date.

object

required

Digital wallet pass links.

Show properties

string

required

Apple Wallet pass URL.

string

required

Google Pay pass URL.

object[]

required

HR system associations for this employee.

Show hr link object

string

required

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

string

required

The employee’s ID in the external HR system.

number | null

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

string | null

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

string | null

Timestamp of the last sync. null if never synced.

object

required

HAL hypermedia links.

Show properties

object

required

Link to this employee resource.

Show properties

string

required

URL of this employee.

string

required

Media type.

object

required

Link to this employee’s documents.

Show properties

string

required

URL to list this employee’s documents.

string

required

Media type.

integer

required

Current page number returned.

integer

required

Number of results per page.

integer

required

Total number of pages available.

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

Billing Items

Query Parameters

Response

Authorizations

Query Parameters

Response

​Query Parameters

​Response

Authorizations

Query Parameters

Response

Query Parameters

Response