openapi: 3.2.0 info: title: Entur Employee API version: 2026.08.0 contact: name: Entur Team Personalisering email: team.personalisering@entur.org termsOfService: http://entur.org description: 'Operations tagged Employee across 2 of this provider''s published API definitions: entur-personnel-tickets-openapi.json, entur-personnel-tickets-openapi.yml. Each path carries the servers of the definition it was published in.' 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 servers: - url: https://api.entur.io /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 servers: - url: https://api.entur.io components: schemas: 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. 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 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 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 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 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 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 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 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 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 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 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. 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 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 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 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 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 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 parameters: X-Correlation-Id: name: X-Correlation-Id in: header description: Correlation id required: false style: simple explode: false schema: type: string 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: `-`.' required: false style: simple explode: false schema: type: string responses: Error401: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Error500: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Error404: description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Error403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: jwt: type: http scheme: bearer bearerFormat: JWT x-refined-from: - entur-personnel-tickets-openapi.json - entur-personnel-tickets-openapi.yml