Entur Employee API
API for fetching employees in the personnel ticket system. An employee is the main entity of the pbsys system. They are hired by a Company and work at a WorkPlace. Employees are created from ImportedEmployee
API for fetching employees in the personnel ticket system. An employee is the main entity of the pbsys system. They are hired by a Company and work at a WorkPlace. Employees are created from ImportedEmployee
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/entur:entur-employee-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Personnel tickets Employee API
description: Personnel tickets are a Norwegian railway discount scheme providing reduced fares for employees, pensioners, and eligible family members in participating companies.
termsOfService: http://entur.org
contact:
name: Entur Team Personalisering
email: team.personalisering@entur.org
version: 2026.08.0
servers:
- url: https://api.entur.io
security:
- jwt: []
tags:
- name: Employee
description: API for fetching employees in the personnel ticket system. An employee is the main entity of the pbsys system. They are hired by a Company and work at a WorkPlace. Employees are created from ImportedEmployee
paths:
/personnelticket/v2/employees:
parameters:
- $ref: '#/components/parameters/ET-Client-Name'
- $ref: '#/components/parameters/X-Correlation-Id'
get:
tags:
- Employee
summary: Find employees
operationId: findEmployees
parameters:
- name: employeeNo
in: query
required: false
style: form
explode: true
schema:
type: string
- name: companyId
in: query
required: false
style: form
explode: true
schema:
type: integer
format: int64
- name: dateOfBirth
in: query
required: false
style: form
explode: true
schema:
type: string
format: date
- name: ssn
in: query
required: false
style: form
explode: true
schema:
type: string
- name: includeFamilyMembers
in: query
required: false
style: form
explode: true
schema:
type: boolean
- name: includeTicketRights
in: query
required: false
style: form
explode: true
schema:
type: boolean
- name: page
in: query
required: false
style: form
explode: true
schema:
type: integer
format: int32
- name: perPage
in: query
required: false
style: form
explode: true
schema:
type: integer
format: int32
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PageEmployeeResponse'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'500':
$ref: '#/components/responses/Error500'
x-entur-permissions:
value:
all:
- Personalbillett-Rettighetshaver:les
- Personalbillett-Rettighetshaver-Sensitiv:les
/personnelticket/v2/employees/{id}:
parameters:
- $ref: '#/components/parameters/ET-Client-Name'
- $ref: '#/components/parameters/X-Correlation-Id'
get:
tags:
- Employee
summary: Attempts to look up a single given employee
operationId: findEmployee
parameters:
- name: id
in: path
required: true
style: simple
explode: false
schema:
type: integer
format: int64
- name: includeFamilyMembers
in: query
required: false
style: form
explode: true
schema:
type: boolean
- name: includeTicketRights
in: query
required: false
style: form
explode: true
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeResponse'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'500':
$ref: '#/components/responses/Error500'
x-entur-permissions:
value:
all:
- Personalbillett-Rettighetshaver.employeeId:les
- Personalbillett-Rettighetshaver-Sensitiv.employeeId:les
- Personalbillett-Billettrettigheter.employeeId:les
components:
schemas:
SimpleRule:
required:
- id
- name
type: object
properties:
id:
type: integer
description: Rule id
format: int64
name:
type: string
description: Rule name
description: Rule describing who are eligible for what ticket right
TicketRightsHolderResponse:
required:
- id
- ticketHolderCode
type: object
properties:
id:
type: integer
description: The ticket right holder id
format: int64
ticketHolderCode:
type: string
description: The personnel ticket code for the ticket rights holder
ticketRight:
$ref: '#/components/schemas/TicketRightResponse'
firstName:
type: string
description: Unused. This field is populated by employee / family member data and will be removed in future versions.
deprecated: true
surname:
type: string
description: Unused. This field is populated by employee / family member data and will be removed in future versions.
deprecated: true
addressLine:
type: string
description: Unused. This field is populated by employee / family member data and will be removed in future versions.
deprecated: true
postalCode:
type: string
description: Unused. This field is populated by employee / family member data and will be removed in future versions.
deprecated: true
postalPlace:
type: string
description: Unused. This field is populated by employee / family member data and will be removed in future versions.
deprecated: true
countryCode:
type: string
description: Unused. This field is populated by employee / family member data and will be removed in future versions.
deprecated: true
dateOfBirth:
type: string
description: Unused. This field is populated by employee / family member data and will be removed in future versions.
format: date
deprecated: true
examples:
- '2023-01-01'
description: All items for this page
ErrorSpecification:
required:
- defaultMessage
- field
type: object
properties:
field:
type: string
description: The field of the associated object in the request related to the error.
defaultMessage:
type: string
description: The message explaining why the error occurred.
rejectedValues:
type: object
description: A list of rejected values.
description: Optional list of error specifications.
EmployeeDisabilityProofResponse:
required:
- isRegistered
- year
type: object
properties:
year:
type: integer
description: The year this information is valid for
format: int32
examples:
- 2020
isRegistered:
type: boolean
description: Whether a disability proof has been registered this year
examples:
- true
description: Yearly disability proof information
PageEmployeeResponse:
required:
- items
- totalItems
- totalPages
type: object
properties:
items:
type: array
description: All items for this page
items:
$ref: '#/components/schemas/EmployeeResponse'
totalItems:
type: integer
description: Total items which could be returned
format: int64
examples:
- 1
totalPages:
type: integer
description: Total number of pages
format: int64
examples:
- 1
description: Paged content
TicketRightResponse:
required:
- calculationTimestamp
- employeeId
- ticketHolderId
- ticketType
- ticketrightId
- validFrom
- validUntil
type: object
properties:
ticketrightId:
type: integer
description: The ticket right id
format: int64
ticketHolderId:
type: integer
description: The id of the ticket holder, either an employee or a family member
format: int64
employeeId:
type: integer
description: The id of the employee who is responsible
format: int64
validFrom:
type: string
description: The date from when the ticket right is valid
format: date
examples:
- '2019-03-13'
validUntil:
type: string
description: The date from when the ticket right stops being valid
format: date
examples:
- '2019-06-13'
ticketType:
$ref: '#/components/schemas/TicketTypeResponse'
note:
type: string
description: Any additional information
canSendTicket:
type: boolean
description: This field will be discontinued in the next vesion of the API.
deprecated: true
ticketCreated:
type: string
description: This field will be discontinued in the next vesion of the API.
format: date-time
deprecated: true
errorMessage:
type: string
description: This field will be discontinued in the next vesion of the API.
deprecated: true
createdByRule:
$ref: '#/components/schemas/SimpleRule'
calculationTimestamp:
type: string
description: When the ticketright was calculated
format: date-time
ticketRightsHolder:
$ref: '#/components/schemas/TicketRightsHolderResponse'
legacySyncStatus:
$ref: '#/components/schemas/SyncStatus'
essSyncStatus:
$ref: '#/components/schemas/SyncStatus'
manualOrder:
$ref: '#/components/schemas/ManualOrderResponse'
description: A ticket right granted to an employee or a family member
EmployeeYearlyFeeResponse:
required:
- isPaid
- year
type: object
properties:
year:
type: integer
description: The year this fee is valid
format: int32
examples:
- 2020
isPaid:
type: boolean
description: Whether this yearly fee has been paid
examples:
- true
description: Yearly fee information
FamilyMemberLowIncomeResponse:
required:
- isRegistered
- year
type: object
properties:
year:
type: integer
description: Year of registered low income
format: int32
examples:
- 2015
isRegistered:
type: boolean
description: Whether low income is registered
examples:
- true
description: Low income information
FamilyMemberResponse:
required:
- employeeId
- firstName
- id
- isDeleted
- relation
- surname
type: object
properties:
id:
type: integer
description: The ID of the family member
format: int64
employeeId:
type: integer
description: The ID of the employee
format: int64
relation:
$ref: '#/components/schemas/FamilyRelation'
dateOfBirth:
type: string
description: When the family member was born
format: date
examples:
- '2023-01-01'
ssn:
type: string
description: The family members social security number
examples:
- '12345'
firstName:
type: string
description: The family member's first name
surname:
type: string
description: The family member's surname
abstainFromTicket:
type: boolean
description: Whether a ticket should be created
note:
type: string
description: Any additional information
isDeleted:
type: boolean
description: Whether the family member has been marked for deletion
ticketRights:
type: array
description: A list of the family member's ticket rights
items:
$ref: '#/components/schemas/TicketRightResponse'
ticketHolderCode:
type: string
description: The family members ticket holder code
examples:
- JDSF-DGJE-SHU4
createdAt:
type: string
description: The date of creation.
format: date-time
createdBy:
type: string
description: The source for the first creation
updatedAt:
type: string
description: The date the last time the family member was updated
format: date-time
updatedBy:
type: string
description: The source for the last update
lowIncomes:
type: array
description: The low income registrations for the current and the next year
items:
$ref: '#/components/schemas/FamilyMemberLowIncomeResponse'
customerNumber:
type: integer
description: The employees customer number in ESS. Note this profile is owned by JBD and is the profile connected to the ticket right. A 'null'-value here may indicate that the ticket right is not yet synced to ESS.
format: int64
examples:
- 1337370
description: A family member must be connected to an employee
CompanyResponse:
required:
- addressLine
- allowETickets
- allowLocalEmployees
- companyId
- employeeNoPrefix
- isDeleted
- name
- postalCode
- reportSeparator
type: object
properties:
companyId:
type: integer
description: The company ID
format: int64
name:
type: string
description: The company name
addressLine:
type: string
description: The company postal address
postalCode:
type: string
description: The company postal code
employeeNoPrefix:
type: string
description: A prefix to be prepended to all employee numbers connected to this company
allowLocalEmployees:
type: boolean
description: Whether local employees are allowed
allowETickets:
type: boolean
description: Whether the company allows the usage of e-tickets for its personnel tickets
isDeleted:
type: boolean
description: Whether the company is deleted
reportSeparator:
type: string
description: 'Which character to separate elements within tax report: '',''(default) or '';'''
deleted:
type: boolean
writeOnly: true
description: Companies are where employees are hired
Product:
required:
- id
- name
- validFrom
- validUntil
type: object
properties:
id:
type: integer
description: The product id
format: int64
name:
type: string
description: Human readable product name
validFrom:
type: string
description: When the product is valid from
format: date
examples:
- '2023-01-01'
validUntil:
type: string
description: When the product is valid to
format: date
examples:
- '2023-01-01'
description: A personnel ticket product
ErrorResponse:
required:
- correlationId
- error
- message
- path
- status
- timestamp
type: object
properties:
timestamp:
type: string
description: When the error occurred.
format: date-time
examples:
- '2007-12-03T10:15:30+01:00'
status:
type: integer
description: The http status code.
format: int32
examples:
- 400
errorCode:
type: string
description: Application specific error code
examples:
- '1033'
error:
type: string
description: The http status reason.
examples:
- Bad request
path:
type: string
description: The request URI.
examples:
- /loyaltyPrograms
message:
type: string
description: The main error message.
examples:
- Validation failed for ...
correlationId:
type: string
description: The unique correlation id for the request.
examples:
- b5d4960d-7ab2-43d6-a8f3-113da042a288
errors:
type: array
description: Optional list of error specifications.
items:
$ref: '#/components/schemas/ErrorSpecification'
description: Response object for errors occurring in the customers API
TicketTypeResponse:
required:
- canHaveStationPairs
- code
- countryCode
- description
- generatesTicketRights
- id
- isDeleted
type: object
properties:
id:
type: integer
description: Ticket type id
format: int64
code:
type: string
description: Ticket type
description:
type: string
description: Ticket type description
countryCode:
type: string
description: Country code
generatesTicketRights:
type: boolean
description: Whether or not this this ticket type is relevant for sending as input to a Manual order. If this = false (the default), it will not generate new tickets rights by manual order.
canHaveStationPairs:
type: boolean
description: 'Whether or not this ticket type is compatible with station pairs when placing a manual order. The default = false. '
isDeleted:
type: boolean
description: Whether the ticket type is deleted.
description: The Ticket type informs of which country it is valid in and what train class it covers.
StationResponse:
required:
- id
type: object
properties:
id:
type: string
description: Station in NetEX format.
name:
type: string
description: Station name
description: Station with NetEX and name
SyncStatus:
type: object
properties:
isReadyToSync:
type: boolean
description: Whether the ticket right is ready to be sent to the ticketing system
syncTimestamp:
type: string
description: When the ticket right was sync'ed
format: date-time
examples:
- '2019-06-13T12:34:56+01:00'
errorMessage:
type: string
description: If the system has failed in sending the ticket right to the ticketing system, this will hold the error message. Default is null
description: Status fields related to synchronization with other services
EmployeeCategoryResponse:
required:
- year
type: object
properties:
year:
type: integer
description: The year this category is valid
format: int32
examples:
- 2
category:
$ref: '#/components/schemas/Product'
description: Category information
FamilyRelation:
required:
- code
- description
type: object
properties:
code:
type: string
description: The code used for input
readOnly: true
description:
type: string
description: A description of the particular code's meaning
readOnly: true
description: The relation a family member has to an employee
EmployeeResponse:
required:
- employeeNo
- firstName
- id
- isDeleted
- postalCode
- surname
- ticketHolderCode
type: object
properties:
id:
type: integer
description: The id of the employee
format: int64
employeeNo:
type: string
description: Employee number
company:
$ref: '#/components/schemas/CompanyResponse'
employmentType:
$ref: '#/components/schemas/EmploymentType'
dateOfBirth:
type: string
description: When the employee was born
format: date
examples:
- '2023-01-01'
ssn:
type: string
description: The employee's social security number
firstName:
type: string
description: The employee's first name
surname:
type: string
description: The employee's surname
addressLine:
type: string
description: The employee's postal address
postalCode:
type: string
description: The employee's postal code
preferredProduct:
$ref: '#/components/schemas/Product'
abstainFromTicket:
type: boolean
description: Whether a ticket should be created
sendTicketToPrivateAddress:
type: boolean
description: Unused
deprecated: true
jobDescription:
type: string
description: Unused
deprecated: true
hireStartDate:
type: string
description: When the employee was hired
format: date
examples:
- '2019-04-12'
payType:
type: string
description: Pay type - see the codes in the API documentation
examples:
- A
hireEndDate:
type: string
description: When the employee left the company
format: date
examples:
- '2019-04-17'
hireEndCause:
type: string
description: Why the employee left the company
disabilityGrade:
type: integer
description: The employee's degree of disability. Default 0.
format: int32
examples:
- 20
disabilityFromDate:
type: string
description: Unused
format: date
deprecated: true
examples:
- '2023-01-01'
disabilityProofRegistered:
type: boolean
description: Deprecated. Use disability proofs.
deprecated: true
disabilityProofRegisteredDate:
type: string
description: Unused
format: date
deprecated: true
examples:
- '2023-01-01'
employmentPercentage:
type: integer
description: Employment percentage
format: int32
examples:
- 80
employmentPercentageDate:
type: string
description: Date for registered employment percentage
format: date
examples:
- '2019-07-13'
paidPercentage:
type: integer
description: The pay level. This is calculated based on the employment percentage and the type of employment. Typically holds the same value as employment percentage, unless special circumstances apply
format: int32
paidPercentageDate:
type: string
description: Date for last change to paidPercentage
format: date
deprecated: true
examples:
- '2023-01-01'
leaveFromDate:
type: string
description: When the employee starts a leave
format: date
examples:
- '2019-05-12'
isOnWaitPay:
type: boolean
description: Unused
deprecated: true
waitPayDate:
type: string
description: Unused
format: date
deprecated: true
examples:
- '2023-01-01'
isFeePaid:
type: boolean
description: Deprecated. Use yearlyFees
deprecated: true
note:
type: string
description: Any additional information
isDeleted:
type: boolean
description: Whether the employee has been marked for deletion
lastUpdate:
type: string
description: When the imported employee was last updated
format: date-time
sourceLastUpdate:
type: string
description: The source for the last update
familyMembers:
type: array
description: The employee's family members
items:
$ref: '#/components/schemas/FamilyMemberResponse'
ticketRights:
type: array
description: The employee's ticket rights
items:
$ref: '#/components/schemas/TicketRightResponse'
ticketHolderCode:
type: string
description: The employee's ticket holder code
createdAt:
type: string
description: The date of creation.
format: date-time
createdBy:
type: string
description: The source for the first creation
categories:
type: array
description: The registered categories on this employee
items:
$ref: '#/components/schemas/EmployeeCategoryResponse'
yearlyFees:
type: array
description: The status of yearly fees for the current and the next year
items:
$ref: '#/components/schemas/EmployeeYearlyFeeResponse'
disabilityProofs:
type: array
description: The status of disability proofs for the current and the next year
items:
$ref: '#/components/schemas/EmployeeDisabilityProofResponse'
customerNumber:
type: integer
description: The employees customer number in ESS. Note this profile is owned by JBD and is the profile connected to the ticket right. A 'null'-value here may indicate that the ticket right is not yet synced to ESS.
format: int64
examples:
- 1337370
description: All items for this page
EmploymentType:
required:
- code
- description
type: object
properties:
code:
type: string
description: The code used for input
readOnly: true
description:
type: string
description: A description of the particular code's meaning
readOnly: true
description: Employment type. Examples include Employee, Part time, Temp
ManualOrderResponse:
required:
- fromDate
- id
- isDeleted
- issueDate
- ticketType
- toDate
type: object
properties:
id:
type: integer
description: Id of this manual order.
format: int64
ticketType:
$ref: '#/components/schemas/TicketTypeResponse'
issueDate:
type: string
description: When this manual order was first issued.
format: date-time
fromDate:
type: string
description: First date the ticket right should be available.
format: date
examples:
- '2023-01-01'
toDate:
type: string
description: Last date the ticket right should be available.
format: date
examples:
- '2023-01-01'
stations:
uniqueItems: true
type: array
description: Any station pairs for this manual order.
items:
$ref: '#/components/schemas/StationPairResponse'
isDeleted:
type: boolean
description: Whether this manual order is deleted or not.
description: A manual order. This may contain a list of station pairs.
StationPairResponse:
required:
- fromStation
- id
- toStation
type: object
properties:
id:
type: integer
description: Id of this station pair
format: int64
fromStation:
$ref: '#/components/schemas/StationResponse'
toStation:
$ref: '#/components/schemas/StationResponse'
description: A set of stations on NetEX format.
responses:
Error401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Error404:
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Error500:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Error403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
parameters:
ET-Client-Name:
name: ET-Client-Name
in: header
description: 'Entur Client Header.
It is required that all consumers identify themselves by using this header.
Entur will deploy strict rate-limiting policies on API-consumers who do not identify with a header and reserves the right to block unidentified consumers.
The structure of ET-Client-Name should be: `<company>-<application>`.'
required: false
style: simple
explode: false
schema:
type: string
X-Correlation-Id:
name: X-Correlation-Id
in: header
description: Correlation id
required: false
style: simple
explode: false
schema:
type: string
securitySchemes:
jwt:
type: http
scheme: bearer
bearerFormat: JWT