Entur Developer
Personnel tickets

API for handling loyalty program contracts.


Claims a personnel ticket directly.

POST
https://api.entur.io
/customers/v2/benefits/contracts/claim-personnel-ticket

Claim a personnel ticket for the given customer profile. A personnel ticket may correspond to more than one contract in benefits, and this method will attempt to claim them all.

Claims a personnel ticket directly. › Headers

Authorization
​string · required · style: simple
ET-Client-Name
​string · style: simple

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

X-Correlation-Id
​string · style: simple

Correlation id

Claims a personnel ticket directly. › Request Body

A request for claiming a personnel ticket
externalReference
​string · pattern: \w+-(\w+)+-\w+ · required

The code of the personnel ticket to claim

Example: ABCD-EF12-3456-GH45
customerNumber
​integer · int64 · required

The customerNumber referring to the customer who claims the personnel ticket

Example: 1234567

Claims a personnel ticket directly. › Responses

OK

The response after claiming a contract
customerNumber
​integer · int64 · required

The customerNumber for the customer now claiming the personnel ticket

Example: 1234567
success
​boolean · required

Whether the claim was successful


Validate contract consumption

POST
https://api.entur.io
/customers/v2/benefits/contracts/validate-consumptions

Validate that the customer can consume given contracts

Validate contract consumption › Headers

ET-Client-Name
​string · style: simple

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

X-Correlation-Id
​string · style: simple

Correlation id

Validate contract consumption › Request Body

A request to validate the consumption of one or more product entitlements in an order
​ContractConsumption[] · minItems: 1 · required

A list of consumptions to verify

Validate contract consumption › Responses

OK

The result of a contract consumption validations
code
​string · required

A code pertaining to the reason for rejection, if any. Code 3101 = OK.

Example: 3101
isValid
​boolean · required

True if all consumptions were valid, otherwise false

reason
​string · required

A short message detailing the reasoning behind the status.

Example: ok

Return all contracts with possible filtering

GET
https://api.entur.io
/customers/v2/benefits/contracts

Return all contracts with possible filtering

Return all contracts with possible filtering › query Parameters

uuid
​string · uuid · style: form · explode: true

Get the contract matching the uuid

customerNumber
​integer · int64 · style: form · explode: true

Get all contracts where a customer is a contractConsumer using Unique Entur id

customerRef
​string · style: form · explode: true

Get all contracts where a customer is a contractConsumer using external customer id unique within an organisation

loyaltyProgramId
​integer · int64 · style: form · explode: true

Get all contracts for a specific loyaltyProgram

contractHolder
​integer · int64 · style: form · explode: true

Get all contracts for a specific contract holder. Use customerNumber as value

consumableAfter
​string · date-time · style: form · explode: true

Get all contracts which can be consumed after this date. Supports ISO 8601 date format

consumableBefore
​string · date-time · style: form · explode: true

Get all contracts which can be consumed before this date. Supports ISO 8601 date format

expirationDateAfter
​string · date-time · style: form · explode: true

Get all contracts with expiration date after this date. Supports ISO 8601 date format

expirationDateBefore
​string · date-time · style: form · explode: true

Get all contracts with expiration date before this date. Supports ISO 8601 date format

externalRef
​string · style: form · explode: true

Get all contracts by external reference. This is, for example, the personnel ticket code

organisationId
​integer · int64 · style: form · explode: true

The organisation the contracts belong to. You must have an Internal token to use this.

sortBy
​string[] · style: form · explode: true

Properties to sort the response by. Multiple values can be specified

Enum values:
customerNumber
loyaltyProgramId
uuid
consumableFrom
sortDirection
​string · enum · style: form · explode: true

The sort direction if sortBy is specified

Enum values:
asc
desc
Example: asc
page
​integer · min: 1 · style: form · explode: true

The page to be retrieved. Starts at 1

Example: 5
Default: 1
perPage
​integer · min: 1 · max: 100 · style: form · explode: true

Number of items per page

Example: 50
Default: 30
includeOrderLineEvents
​boolean · style: form · explode: true

Whether to include order line events in the response. Note: setting this to true may impact performance. Default false.

includeConsumers
​string · enum · pattern: all|none|contract-ho… · style: form · explode: true

Whether to include contract consumers in the response. Supported formats are 'all', 'none' and 'contract-holder'. Note: setting this to ALL may impact performance. Default is 'contract-holder'

Enum values:
all
none
contract-holder
Example: none

Return all contracts with possible filtering › Headers

ET-Client-Name
​string · style: simple

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

X-Correlation-Id
​string · style: simple

Correlation id

Return all contracts with possible filtering › Responses

OK

Paged content
​ContractResponse[] · required

All items for this page

totalItems
​integer · int64 · required

Total items which could be returned

Example: 1
totalPages
​integer · int64 · required

Total number of pages

Example: 1

Get contracts by external ref

GET
https://api.entur.io
/customers/v2/benefits/contracts/{externalRef}/by-external-ref

Finds contracts by external reference.

Get contracts by external ref › path Parameters

externalRef
​string · required · style: simple

Get contracts by external ref › query Parameters

organisationId
​integer · int64 · style: form · explode: true

The organisation the contracts belong to, left empty will use orgID from token.

page
​integer · min: 1 · style: form · explode: true

Selects a specific page in the collection

Example: 1
Default: 1
perPage
​integer · min: 1 · max: 100 · style: form · explode: true

Selects the number of elements per page

Example: 5
Default: 30
includeOrderLineEvents
​boolean · style: form · explode: true

Whether to include order line events in the response. Note: setting this to true may impact performance. Default false.

includeConsumers
​string · enum · pattern: all|none|contract-ho… · style: form · explode: true

Whether to include contract consumers in the response. Supported formats are 'all', 'none' and 'contract-holder'. Note: setting this to ALL may impact performance. Default is 'contract-holder'

Enum values:
all
none
contract-holder
Example: none

Get contracts by external ref › Headers

ET-Client-Name
​string · style: simple

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

X-Correlation-Id
​string · style: simple

Correlation id

Entur-Customer-Number
​string · style: simple

To identify logged in user and limit access per user

Get contracts by external ref › Responses

OK

Paged content
​ContractResponse[] · required

All items for this page

totalItems
​integer · int64 · required

Total items which could be returned

Example: 1
totalPages
​integer · int64 · required

Total number of pages

Example: 1

GET
https://api.entur.io
/customers/v2/benefits/contract-consumers/{customerNumber}/contracts

Return all valid contracts by customer number. Returns only contracts with status VALID within timeframe.

path Parameters

customerNumber
​integer · int64 · required · style: simple

query Parameters

travelDate
​string · date-time · style: form · explode: true
organisationId
​integer · int64 · style: form · explode: true
includeExpiredContracts
​boolean · style: form · explode: true
includeOrderLineEvents
​boolean · style: form · explode: true

Whether to include order line events in the response. Note: setting this to true may impact performance. Default false.

includeConsumers
​string · enum · pattern: all|none|contract-ho… · style: form · explode: true

Whether to include contract consumers in the response. Supported formats are 'all', 'none' and 'contract-holder'. Note: setting this to ALL may impact performance. Default is 'contract-holder'

Enum values:
all
none
contract-holder
Example: none

Headers

ET-Client-Name
​string · style: simple

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

X-Correlation-Id
​string · style: simple

Correlation id

Responses

OK

A contract between a customer and an organisation
consumableFrom
​string · date-time · required

From when the contract can be consumed

Example: 2007-12-03T10:15:30+01:00
createdAt
​string · date-time · required

When the contract was created

Example: 2007-12-03T10:15:30+01:00
createdBy
​string · required

Which client created the contract

Example: 123e4567-e89b-12d3-a456-426655440000
lastChangedAt
​string · date-time · required

When the contract was last changed

Example: 2007-12-03T10:15:30+01:00
lastChangedBy
​string · required

Which client changed the contract last

Example: 123e4567-e89b-12d3-a456-426655440000
​LoyaltyProgramFlatResponse · required

The current values for a loyalty program

organisationId
​integer · int64 · required

Which organisation the contract concerns

Example: 1
status
​string · required

The contract status. A normal contract has status valid. It can be expired, refunded, cancelled, misused and valid

Example: Refunded
uuid
​string · required

Unique contract identifier

Example: 123e4567-e89b-12d3-a456-426655440000
acceptanceDate
​string · date-time

When the contract was accepted by the customer

Example: 2007-12-03T10:15:30+01:00
​ContractConsumerResponse[]

The list of customers allowed to use the contract

couponsLimit
​integer · int64

How many coupons the contract has. Default is cascaded from Loyalty Program Version. If set, the contract will be blocked for usage when all coupons are used. Coupons are registered via an OrderLineEvent.

Example: 10
​TotalAmount

The current total for this contract (earn/burn or giftcard)

expirationDate
​string · date-time

When the contract expires

Example: 2007-12-03T10:15:30+01:00
externalRef
​string

Optional external reference. Examples are membership number and employee number

Example: 123415A
​OrderLineEventResponse[]

A list of order line events related to this contract

parent
​string

If present, contract UUID of the parent contract. This field is usually set if the contract is created by a coupon usage, whereas this contract has a time constraint and the parent has a coupon constraint.

Example: fd29908d-a2ae-4fe0-8e10-7f0db437c554
​PolicyResponse[]

The list of keys validated against the customer claiming the contract

remainingCoupons
​integer · int64

The remaining coupons for coupon based contracts. Derived from couponsLimit and orderLineEvents. The amount of remaining coupons are counted yearly and based of the earliest travel date.

​object[]

If present, contains timed contracts that are dependent on this contract. See Contract response

​TransactionResponse[]

The list of transactions for this contract (earn/burn or giftcard)


Did you find what you were looking for?