TUI Group Persons API

openapi: 3.2.0
info:
  title: NewSkies-Digital-Api Persons API
  version: 4.8.6.23
  description: Navitaire Digital Api
servers:
- url: https://prod.api.tui/flight/newskies/rest
  description: TUI Prod
- url: https://playground.api.tui/flight/newskies/rest
  description: TUI Playground
security:
- JWT: []
tags:
- name: persons
paths:
  /api/nsk/v1/persons:
    post:
      tags:
      - persons
      summary: Creates a new person record (used by agents).
      description: 'This endpoint requires agent permissions.


        GraphQL endpoint: personAdd'
      operationId: nsk_v1_persons_post
      requestBody:
        x-name: request
        description: The person create request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonCreateRequest'
        required: true
        x-position: 1
      responses:
        '201':
          description: The item was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
        '400':
          description: There was a problem with the request and it could not be completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
        '403':
          description: Role permissions are not met.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
  /api/nsk/v2/persons:
    get:
      tags:
      - persons
      summary: Search person records.
      description: 'GraphQL endpoint: personSearchv2'
      operationId: nsk_v2_persons_get
      parameters:
      - name: LastIndex
        in: query
        description: "The index of the last paged item.  This can be found on the\nresponse from the previous set of paged results.\n            "
        schema:
          type:
          - integer
          - 'null'
          format: int32
        x-position: 1
      - name: Username
        in: query
        description: "The person user name to search by.\n            "
        schema:
          type:
          - string
          - 'null'
        x-position: 2
      - name: FirstName
        in: query
        description: "The person's first name to search by.\n            "
        schema:
          type:
          - string
          - 'null'
        x-position: 3
      - name: LastName
        in: query
        description: "The person's last name to search by.\n            "
        schema:
          type:
          - string
          - 'null'
        x-position: 4
      - name: FirstNameMatching
        in: query
        description: "The matching criteria for the person's first name.\n             \nEnumeration values: 0 = StartsWith, 1 = EndsWith, 2 = Contains, 3 = ExactMatch"
        schema:
          $ref: '#/components/schemas/MatchCriteria'
        x-position: 5
      - name: CustomerNumber
        in: query
        description: "The person's customer number.\n            "
        schema:
          type:
          - string
          - 'null'
        x-position: 6
      - name: PhoneNumber
        in: query
        description: "The phone number to search by.\n            "
        schema:
          type:
          - string
          - 'null'
        x-position: 7
      - name: EmailAddress
        in: query
        description: "The email address to search by.\n            "
        schema:
          type:
          - string
          - 'null'
        x-position: 8
      - name: ProgramNumber
        in: query
        description: "The program number to search by.\n            "
        schema:
          type:
          - string
          - 'null'
        x-position: 9
      - name: ProgramCode
        in: query
        description: "The program code to search by.\n            "
        schema:
          type:
          - string
          - 'null'
        x-position: 10
      - name: Type
        in: query
        description: "The person type to search by.\n             \nEnumeration values: 0 = None, 1 = Customer, 2 = Agent"
        schema:
          $ref: '#/components/schemas/PersonType'
        x-position: 11
      - name: NationalIdNumber
        in: query
        description: "The national ID number to search by.\n            "
        schema:
          type:
          - string
          - 'null'
        x-position: 12
      - name: NationalIdNumberMatching
        in: query
        description: "The matching criteria for the national ID number.\n             \nEnumeration values: 0 = StartsWith, 1 = EndsWith, 2 = Contains, 3 = ExactMatch"
        schema:
          $ref: '#/components/schemas/MatchCriteria'
        x-position: 13
      - name: ReturnCount
        in: query
        description: "The number of results to return.\n            "
        schema:
          type:
          - integer
          - 'null'
        x-position: 14
      - name: ActiveOnly
        in: query
        description: "Include active person records only.\n            "
        schema:
          type: boolean
        x-position: 15
      responses:
        '404':
          description: The item was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
        '200':
          description: OK. Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponseOfPersonRecordsResponse'
  /api/nsk/v1/persons/{personKey}:
    get:
      tags:
      - persons
      summary: Retrieves a specific person by key.
      description: 'GraphQL endpoint: person'
      operationId: nsk_v1_persons_personKey_get
      parameters:
      - name: personKey
        in: path
        required: true
        description: The unique person key.
        schema:
          type: string
        x-position: 1
      responses:
        '404':
          description: The item was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
        '200':
          description: OK. Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponseOfPerson'
    put:
      tags:
      - persons
      summary: Updates the person record basic information.
      description: 'GraphQL endpoint: personSet'
      operationId: nsk_v1_persons_personKey_put
      parameters:
      - name: personKey
        in: path
        required: true
        description: The unique person key.
        schema:
          type: string
        x-position: 1
      requestBody:
        x-name: request
        description: The person edit request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonEditRequest'
            examples:
              Person Edit Request:
                description: Example request for updating person's basic information.
                value:
                  name:
                    first: John
                    middle: Cee
                    last: Doe
                    title: Mr.
                    suffix: null
                  type: 1
                  status: 0
                  details:
                    gender: 1
                    dateOfBirth: '2006-07-09T05:55:16.0597472+00:00'
                    nationality: US
                    residentCountry: US
                    passengerType: ADT
                    preferredCultureCode: en-US
                    preferredCurrencyCode: USD
                    nationalIdNumber: null
                    declaredGender: null
                  notificationPreference: 0
        required: true
        x-position: 2
      responses:
        '200':
          description: OK. Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
        '400':
          description: There was a problem with the request and it could not be completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
              examples:
                With Invalid Person Key:
                  description: The person key is not valid or does not exist.
                  value:
                    errors:
                    - id: null
                      code: nsk:Exceptions:InvalidKey
                      message: The identifier 'personKey' with value 'MTW' is invalid.
                      type: Validation
                      details:
                        personKey: MTW
                      rawMessage: The identifier 'personKey' with value 'MTW' is invalid.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                With Invalid Preferred Culture Code:
                  description: The provided culture code in the request is an invalid culture identifier.
                  value:
                    errors:
                    - id: null
                      code: nsk:Person:InvalidPreferredCulture
                      message: nsk:Person:InvalidPreferredCulture
                      type: Validation
                      details: null
                      rawMessage: The preferred culture code 'ZZZ' is invalid.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                With Invalid Preferred Currency Code:
                  description: The provided currency code in the request is not valid or does not exist.
                  value:
                    errors:
                    - id: null
                      code: nsk:Person:InvalidPreferredCurrency
                      message: nsk:Person:InvalidPreferredCurrency
                      type: Validation
                      details: null
                      rawMessage: The preferred currency code 'ZZZ' is invalid.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                With Invalid First Name:
                  description: The provided first name in the request starts with a numerical or special character.
                  value:
                    errors:
                    - id: null
                      code: nsk:Validation:InvalidFirstNameCharacters
                      message: 'A first name may not begin with any of these characters: :@#$%&_+*-=~^`“"''‘,.:;!?|/\(){}[]<>0123456789.'
                      type: Validation
                      details: null
                      rawMessage: 'A first name may not begin with any of these characters: :@#$%&_+*-=~^`“"''‘,.:;!?|/\(){}[]<>0123456789.'
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                With Invalid Middle Name:
                  description: The provided middle name in the request starts with a special character.
                  value:
                    errors:
                    - id: null
                      code: nsk:Validation:InvalidMiddleNameCharacters
                      message: 'A middle name may not begin with any of these characters: :@#$%&_+*-=~^`“"''‘,.:;!?|/\(){}[]<>.'
                      type: Validation
                      details: null
                      rawMessage: 'A middle name may not begin with any of these characters: :@#$%&_+*-=~^`“"''‘,.:;!?|/\(){}[]<>.'
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                With Invalid Last Name:
                  description: The provided last name in the request starts with a numerical or special character.
                  value:
                    errors:
                    - id: null
                      code: nsk:Validation:InvalidLastNameCharacters
                      message: 'A last name may not begin with any of these characters: :@#$%&_+*-=~^`“"''‘,.:;!?|/\(){}[]<>0123456789.'
                      type: Validation
                      details: null
                      rawMessage: 'A last name may not begin with any of these characters: :@#$%&_+*-=~^`“"''‘,.:;!?|/\(){}[]<>0123456789.'
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                Update Status Not Allowed:
                  description: The logged-in user is not allowed to update the person's status.
                  value:
                    errors:
                    - id: null
                      code: nsk:Person:StatusUpdateNotAllowed
                      message: nsk:Person:StatusUpdateNotAllowed
                      type: Validation
                      details: null
                      rawMessage: The logged-in user is not allowed to update their status.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                Update Type Not Allowed:
                  description: The logged-in user is not allowed to update the person's type.
                  value:
                    errors:
                    - id: null
                      code: nsk:Person:TypeUpdateNotAllowed
                      message: nsk:Person:TypeUpdateNotAllowed
                      type: Validation
                      details: null
                      rawMessage: The logged-in user is not allowed to update their type.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
        '401':
          description: Authorization Not Allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
        '500':
          description: A server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
    patch:
      tags:
      - persons
      summary: Patches the person record basic information.
      description: 'Only need to send in the data that is being requested to be updated.


        GraphQL endpoint: personModify'
      operationId: nsk_v1_persons_personKey_patch
      parameters:
      - name: personKey
        in: path
        required: true
        description: The unique person key.
        schema:
          type: string
        x-position: 1
      requestBody:
        x-name: request
        description: The person patch request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeltaMapperOfPersonEditRequest'
            examples:
              Person Edit Request:
                description: Example request for updating person's basic information.
                value:
                  name:
                    first: John
                    middle: Cee
                    last: Doe
                    title: Mr.
                    suffix: null
                  type: 1
                  status: 0
                  details:
                    gender: 1
                    dateOfBirth: '2006-07-09T05:55:16.06105+00:00'
                    nationality: US
                    residentCountry: US
                    passengerType: ADT
                    preferredCultureCode: en-US
                    preferredCurrencyCode: USD
                    nationalIdNumber: null
                    declaredGender: null
                  notificationPreference: 0
        required: true
        x-position: 2
      responses:
        '200':
          description: OK. Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
        '400':
          description: There was a problem with the request and it could not be completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
              examples:
                With Invalid Person Key:
                  description: The person key is not valid or does not exist.
                  value:
                    errors:
                    - id: null
                      code: nsk:Exceptions:InvalidKey
                      message: The identifier 'personKey' with value 'MTW' is invalid.
                      type: Validation
                      details:
                        personKey: MTW
                      rawMessage: The identifier 'personKey' with value 'MTW' is invalid.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                With Invalid Preferred Culture Code:
                  description: The provided culture code in the request is an invalid culture identifier.
                  value:
                    errors:
                    - id: null
                      code: nsk:Person:InvalidPreferredCulture
                      message: nsk:Person:InvalidPreferredCulture
                      type: Validation
                      details: null
                      rawMessage: The preferred culture code 'ZZZ' is invalid.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                With Invalid Preferred Currency Code:
                  description: The provided currency code in the request is not valid or does not exist.
                  value:
                    errors:
                    - id: null
                      code: nsk:Person:InvalidPreferredCurrency
                      message: nsk:Person:InvalidPreferredCurrency
                      type: Validation
                      details: null
                      rawMessage: The preferred currency code 'ZZZ' is invalid.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                With Invalid First Name:
                  description: The provided first name in the request starts with a numerical or special character.
                  value:
                    errors:
                    - id: null
                      code: nsk:Validation:InvalidFirstNameCharacters
                      message: 'A first name may not begin with any of these characters: :@#$%&_+*-=~^`“"''‘,.:;!?|/\(){}[]<>0123456789.'
                      type: Validation
                      details: null
                      rawMessage: 'A first name may not begin with any of these characters: :@#$%&_+*-=~^`“"''‘,.:;!?|/\(){}[]<>0123456789.'
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                With Invalid Middle Name:
                  description: The provided middle name in the request starts with a special character.
                  value:
                    errors:
                    - id: null
                      code: nsk:Validation:InvalidMiddleNameCharacters
                      message: 'A middle name may not begin with any of these characters: :@#$%&_+*-=~^`“"''‘,.:;!?|/\(){}[]<>.'
                      type: Validation
                      details: null
                      rawMessage: 'A middle name may not begin with any of these characters: :@#$%&_+*-=~^`“"''‘,.:;!?|/\(){}[]<>.'
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                With Invalid Last Name:
                  description: The provided last name in the request starts with a numerical or special character.
                  value:
                    errors:
                    - id: null
                      code: nsk:Validation:InvalidLastNameCharacters
                      message: 'A last name may not begin with any of these characters: :@#$%&_+*-=~^`“"''‘,.:;!?|/\(){}[]<>0123456789.'
                      type: Validation
                      details: null
                      rawMessage: 'A last name may not begin with any of these characters: :@#$%&_+*-=~^`“"''‘,.:;!?|/\(){}[]<>0123456789.'
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                Update Status Not Allowed:
                  description: The logged-in user is not allowed to update the person's status.
                  value:
                    errors:
                    - id: null
                      code: nsk:Person:StatusUpdateNotAllowed
                      message: nsk:Person:StatusUpdateNotAllowed
                      type: Validation
                      details: null
                      rawMessage: The logged-in user is not allowed to update their status.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                Update Type Not Allowed:
                  description: The logged-in user is not allowed to update the person's type.
                  value:
                    errors:
                    - id: null
                      code: nsk:Person:TypeUpdateNotAllowed
                      message: nsk:Person:TypeUpdateNotAllowed
                      type: Validation
                      details: null
                      rawMessage: The logged-in user is not allowed to update their type.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                With Null Request:
                  description: Example response when attempting to call the endpoint with a null request
                  value:
                    errors:
                    - id: null
                      code: core:Validation:NullRequest
                      message: The request is null or couldn't be converted to the expected data type.
                      type: Error
                      details: null
                      rawMessage: The request is null or couldn't be converted to the expected data type.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
        '401':
          description: Authorization Not Allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
        '500':
          description: A server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
    delete:
      tags:
      - persons
      summary: Deletes a person by setting the record to terminated.
      description: 'This endpoint requires agent permissions.


        GraphQL endpoint: personDelete'
      operationId: nsk_v1_persons_personKey_delete
      parameters:
      - name: personKey
        in: path
        required: true
        description: The unique person key.
        schema:
          type: string
        x-position: 1
      responses:
        '200':
          description: OK. Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
  /api/nsk/v1/persons/{personKey}/account:
    get:
      tags:
      - persons
      summary: Retrieves the person account and credits based on the person key.
      description: 'If the currency code is not provided it will default to the currency code associated to the account.


        GraphQL endpoint: personsAccount'
      operationId: nsk_v1_persons_personKey_account_get
      parameters:
      - name: personKey
        in: path
        required: true
        description: The person key.
        schema:
          type: string
        x-position: 1
      - name: currencyCode
        in: query
        description: The currency code. This is optional.
        schema:
          type:
          - string
          - 'null'
        x-position: 2
      responses:
        '404':
          description: The item was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
        '200':
          description: OK. Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponseOfAccount'
    post:
      tags:
      - persons
      summary: 'Creates the person account based on the person key and

        data in the request.'
      description: 'GraphQL endpoint: personsAccountAdd'
      operationId: nsk_v1_persons_personKey_account_post
      parameters:
      - name: personKey
        in: path
        required: true
        description: The person key.
        schema:
          type: string
        x-position: 1
      requestBody:
        x-name: request
        description: The create account request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccountRequest'
        required: true
        x-position: 2
      responses:
        '201':
          description: The item was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
        '400':
          description: There was a problem with the request and it could not be completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
  /api/nsk/v1/persons/{personKey}/account/collection:
    post:
      tags:
      - persons
      summary: Creates an account collection based on the person key and data in the request.
      description: 'This endpoint will create a new account collection and a transaction if no account

        transaction exists or no matching collection is found.  An account collection is unique

        based on the transaction code and the expiration date.  If a matching account collection

        is found, a transaction for that collection is generated and the account collection will

        be updated.

        See /api/nsk/v1/resources/accountTransactionCodes for a list of available account transaction

        codes.


        GraphQL endpoint: personsAccountCollectionsAdd'
      operationId: nsk_v1_persons_personKey_account_collection_post
      parameters:
      - name: personKey
        in: path
        required: true
        description: The person key.
        schema:
          type: string
        x-position: 1
      requestBody:
        x-name: request
        description: The create account collection request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCollectionRequest'
        required: true
        x-position: 2
      responses:
        '201':
          description: The item was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
        '400':
          description: There was a problem with the request and it could not be completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
  /api/nsk/v1/persons/{personKey}/account/collection/{accountCollectionKey}/transactions:
    get:
      tags:
      - persons
      summary: 'Retrieves the person account collection transactions based on the person key,

        the account collection key, and data in the request.'
      description: 'GraphQL endpoint: personsAccountTransactions'
      operationId: nsk_v1_persons_personKey_account_collection_accountCollectionKey_transactions_get
      parameters:
      - name: personKey
        in: path
        required: true
        description: The person key.
        schema:
          type: string
        x-position: 1
      - name: accountCollectionKey
        in: path
        required: true
        description: The account collection key.
        schema:
          type: string
        x-position: 2
      - name: StartTime
        in: query
        description: "The starting date and time of the date range to search in.\n            "
        schema:
          type:
          - string
          - 'null'
          format: date-time
        x-position: 3
      - name: EndTime
        in: query
        description: "The end date and time of the date range to search in.\n            "
        schema:
          type:
          - string
          - 'null'
          format: date-time
        x-position: 4
      - name: SortByNewest
        in: query
        description: "Optional filter to sort results by newest.\n            "
        schema:
          type: boolean
        x-position: 5
      - name: PageSize
        in: query
        description: "Used to specify the number of records to return.\n            "
        schema:
          type:
          - integer
          - 'null'
          maximum: 5000.0
          minimum: 10.0
        x-position: 6
      - name: PageIndex
        in: query
        description: "Represents the index of the requested paged item.\n            "
        schema:
          type:
          - integer
          - 'null'
          format: int64
        x-position: 7
      responses:
        '200':
          description: OK. Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponseOfIListOfTransaction'
              examples:
                Retrieve Transactions Response:
                  description: Example response for retrieving transactions.
                  value:
                    data:
                    - accountTransactionCode: null
                      recordLocator: null
                      accountReference: null
                      transactionKey: MSExITEwMjA4OCJsJNQxATUzMyEhUURRNUZ
                      amount: -2.42
                      createdDate: '2026-07-09T05:55:16.3678462Z'
   

# --- truncated at 32 KB (318 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tui-group/refs/heads/main/openapi/tui-group-persons-api-openapi.yml