Entur Customers API

openapi: 3.2.0
info:
  title: Entur Customers API
  version: 2026.09.0
  contact:
    name: Team Personalisering
    email: team.personalisering@entur.org
  description: 'Operations tagged Customers across 2 of this provider''s published API definitions: entur-personalisation-client-openapi.json, entur-personalisation-client-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.entur.io/personalisation
security:
- jwt: []
tags:
- name: Customers
  description: Find information about memberships and status a customer might have in programs.
paths:
  /v1/customer-memberships:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    post:
      tags:
      - Customers
      summary: Query program memberships of a customer
      description: 'Query the memberships of a customer using customer ID. Returns list of program memberships,

        with the member ID and any member data that is stored in each program.'
      operationId: queryCustomerMemberships
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerMembershipsQuery'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomerMembership'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '500':
          $ref: '#/components/responses/Error500'
      x-entur-permissions:
        value:
          any:
          - personalisation-customerdata:les
          - personalisation-customerdata-global:les
    servers:
    - url: https://api.entur.io/personalisation
  /v1/current-level-summaries:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    post:
      tags:
      - Customers
      summary: Current status of a customer
      description: 'Current Level Summary contains information about the current status of a customer in a program, with information about

        how many points the customer has, what level on the reward ladder they''re at, the rewards they have achieved and any suspensions

        they might have.


        By default, the endpoint will return the customers status at the time the request was made. However, you can specify

        the request parameter statusAt to set which time to query the status for.


        Returns a list of summaries, one for each program the customer is a member of. You can choose to filter on programs, using the program reference.

        Will return empty list if customer is not a member of any programs.'
      operationId: queryCurrentLevelSummaries
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CurrentLevelSummaryQuery'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CurrentLevelSummary'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '500':
          $ref: '#/components/responses/Error500'
      x-entur-permissions:
        value:
          any:
          - personalisation-customerdata:les
          - personalisation-customerdata-global:les
    servers:
    - url: https://api.entur.io/personalisation
components:
  schemas:
    CustomerMembershipsQuery:
      required:
      - customerId
      type: object
      properties:
        customerId:
          type: string
          description: Customer id of the member
          examples:
          - '29582738'
        programReferences:
          type:
          - array
          - 'null'
          description: List of reference to the programs to query.
          items:
            type: string
            description: List of reference to the programs to query.
            examples:
            - '["flexiticket","reis"]'
          examples:
          - - flexiticket
            - reis
      description: Program memberships for a customer
      writeOnly: true
    CurrentReward:
      required:
      - '@type'
      - description
      - rewardId
      type: object
      properties:
        description:
          type: string
        rewardId:
          type: integer
          format: int64
        '@type':
          type: string
      description: The current rewards the member has achieved in the program
      discriminator:
        propertyName: '@type'
        mapping:
          CurrentPercentDiscountedProductReward: '#/components/schemas/CurrentPercentDiscountedProductReward'
          CurrentFeatureReward: '#/components/schemas/CurrentFeatureReward'
    Error:
      required:
      - correlationId
      - message
      - status
      - title
      type: object
      properties:
        status:
          type: integer
          description: The http status code.
          format: int32
          examples:
          - 400
        title:
          type: string
          examples:
          - An error occurred
        detail:
          type:
          - string
          - 'null'
          description: The main error message.
          examples:
          - An error occurred
        message:
          type: string
          description: The main error message.
          examples:
          - An error occurred
        correlationId:
          type: string
          description: The unique correlation id for the request.
          examples:
          - b5d4960d-7ab2-43d6-a8f3-113da042a288
        errors:
          type:
          - array
          - 'null'
          description: Validation error on a specific field.
          items:
            $ref: '#/components/schemas/FieldError'
    CustomerMembership:
      required:
      - memberId
      - programId
      type: object
      properties:
        programId:
          type: integer
          format: int64
        programReference:
          type:
          - string
          - 'null'
          description: '

            Unique reference for the program.

            '
          examples:
          - reis
        memberId:
          type: integer
          description: The ID for the customer's membership in the program
          format: int64
        memberMetadata:
          type:
          - object
          - 'null'
          additionalProperties:
            type: object
            description: Metadata about the member
          description: Metadata about the member
      description: Information about a customers membership in a program
    CurrentLevelSummary:
      required:
      - currentRewards
      - memberId
      - pointDefinitionStatuses
      - programId
      - suspensionStatuses
      type: object
      properties:
        programId:
          type: integer
          description: "\nId of the program.\nWARNING: Don't use this for matching with a specific program, since it may vary across environments. \nUse \"programReference\" instead.\n    "
          format: int64
          examples:
          - 1
        programReference:
          type:
          - string
          - 'null'
          description: "\nReference to the program.\nThis is a unique reference that is the same in all environments, and can be used to identify the program.\nNullable for backwards compatibility reasons. Should be filled out in most cases.\n    "
          examples:
          - flexiticket
        memberId:
          type: integer
          description: "\nId of the member within the program. Can be used to look up more information about the member.\n    "
          format: int64
          examples:
          - 1
        currentLevel:
          anyOf:
          - $ref: '#/components/schemas/LevelStatus'
          - type: 'null'
        currentRewards:
          type: array
          description: The current rewards the member has achieved in the program
          items:
            $ref: '#/components/schemas/CurrentReward'
        suspensionStatuses:
          type: array
          items:
            $ref: '#/components/schemas/SuspensionStatus'
        pointDefinitionStatuses:
          type: array
          description: The current status of each point definition in the program
          items:
            $ref: '#/components/schemas/PointDefinitionStatus'
      description: Summary of the current level of a member
      readOnly: true
    FieldError:
      required:
      - field
      - message
      type: object
      properties:
        field:
          type: string
        message:
          type: string
      description: Validation error on a specific field.
    CurrentPointsPeriod:
      required:
      - startOfPeriod
      type: object
      properties:
        startOfPeriod:
          type: string
          description: The start of the period for which the current points are valid
          format: date-time
        endOfPeriod:
          type:
          - string
          - 'null'
          description: The end of the period for which the current points are valid
          format: date-time
      description: '

        The period for which the current points are valid. Only filled out if the point definition is periodic.

        Can return the first active period after the queried time if there is no period active at that point.

        '
    SuspensionStatusType:
      type: string
      description: "\n        The type of suspension:\n        - Rewards: Member is suspended from receiving rewards\n        - GivePointsEffect: Member is suspended from being given points\n        - ConsumePointsEffect: Member is suspended from using points\n        - UpdateMemberMetadata: Member is suspended from updating their metadata. \n        - SuspendRewardsEffect: Member is suspended from being put into reward suspension\n        - SuspendEffectEffect: Member is suspended from being put into effect suspension\n    "
      enum:
      - Rewards
      - GivePointsEffect
      - SuspendRewardsEffect
      - SuspendEffectEffect
      - ConsumePointsEffect
    SuspensionStatus:
      required:
      - endAt
      - referenceId
      - startAt
      - suspensionType
      type: object
      properties:
        referenceId:
          type: string
          description: The reference id of the suspension
        suspensionType:
          $ref: '#/components/schemas/SuspensionStatusType'
        startAt:
          type: string
          description: When the suspension started
          format: date-time
        endAt:
          type: string
          description: When the suspension will end
          format: date-time
      description: Status of a suspension
    LevelStatus:
      required:
      - levelId
      - rewards
      type: object
      properties:
        levelId:
          type: integer
          description: Id of the level in the reward ladder
          format: int64
          examples:
          - 1
        rewards:
          type: array
          description: Rewards for this level
          items:
            $ref: '#/components/schemas/LevelStatusReward'
      description: The current level in the reward ladder the member has achieved
    LevelStatusReward:
      required:
      - '@type'
      - description
      - rewardId
      type: object
      properties:
        description:
          type: string
        rewardId:
          type: integer
          format: int64
        '@type':
          type: string
      description: Rewards for this level
      discriminator:
        propertyName: '@type'
        mapping:
          LevelStatusPercentDiscountedProductReward: '#/components/schemas/LevelStatusPercentDiscountedProductReward'
          LevelStatusFeatureReward: '#/components/schemas/LevelStatusFeatureReward'
    CurrentLevelSummaryQuery:
      required:
      - customerId
      type: object
      properties:
        programId:
          type:
          - integer
          - 'null'
          description: Id of the program to query. If null, will return summary of all programs the customer is enrolled in.
          format: int64
          examples:
          - 1
        programReference:
          type:
          - string
          - 'null'
          description: Reference to the program to query. Better to use than programId, since programId might vary in different environments.
          examples:
          - flexiticket
        customerId:
          type: string
          description: Customer id of the member
          examples:
          - '29582738'
        programReferences:
          type:
          - array
          - 'null'
          description: List of reference to the programs to query. If given then it overrides the programReference parameter.
          items:
            type: string
            description: List of reference to the programs to query. If given then it overrides the programReference parameter.
            examples:
            - '["flexiticket","reis"]'
          examples:
          - - flexiticket
            - reis
        statusAt:
          type:
          - string
          - 'null'
          description: Get current level summary at a given date and time. Defaults to now if not set.
          format: date-time
          examples:
          - '2023-10-01T12:00:00.567Z'
      description: Status query for a member
      writeOnly: true
    PointDefinitionStatus:
      required:
      - currentPoints
      - pendingPoints
      - pointDefinitionId
      - pointDefinitionPluralName
      - pointDefinitionReference
      - pointDefinitionSingularName
      type: object
      properties:
        pointDefinitionId:
          type: integer
          description: Id of the point definition
          format: int64
        pointDefinitionReference:
          type: string
          description: '

            Unique reference for the point. Meant to be used to identify what kind of point this is, across different environments

            where the id might be different. This enables clients of the api to enrich the presentation of the point definition,

            beyond what this api delivers (for example giving the point definition an icon, or more descriptive text).

            '
          examples:
          - trips_done
        pointDefinitionSingularName:
          type: string
          description: Singular name of the point definition
          examples:
          - reise
        pointDefinitionPluralName:
          type: string
          description: Plural name of the point definition
          examples:
          - reiser
        currentPoints:
          type: number
          description: The amount of points the member currently has of this point definition
          examples:
          - 15
        pendingPoints:
          type: number
          description: '

            The amount of points the member has received, but are not valid yet.

            If the point definition is periodic, this field will only contain the pending points in the current point period.

            '
          examples:
          - 15
        cappingStatus:
          anyOf:
          - $ref: '#/components/schemas/CappingStatus'
          - type: 'null'
        currentPointsPeriod:
          anyOf:
          - $ref: '#/components/schemas/CurrentPointsPeriod'
          - type: 'null'
      description: The current status of a point definition in a program for a member
    CappingStatus:
      required:
      - cappingAmount
      - isReached
      type: object
      properties:
        cappingAmount:
          type: number
          description: The amount that this point definition is capped at
          examples:
          - 100
        isReached:
          type: boolean
          description: Whether the capping amount has been reached by the member
          examples:
          - true
      description: The capping status for this point definition, if capping is enabled
  responses:
    Error400:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error500:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error404:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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: `<company>-<application>`.'
      required: false
      style: simple
      explode: false
      schema:
        type: string
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Entur Developer Documentation
  url: https://developer.entur.org/pages-personalisation-docs-personalisation-client-integration-guide
x-refined-from:
- entur-personalisation-client-openapi.json
- entur-personalisation-client-openapi.yml