Docs

Passenger Profiles ​

A company that keeps a profile directory holds the details of the people who travel for it: names, contact details, date of birth, nationality and travel cards. Search the directory with passengerProfiles, pick a passenger profile, and book with its details instead of asking for them again. A travel agency's search reaches the profiles of every company it books for, and a company's search reaches its own.

Searching requires the passenger_profiles:read scope (see API Scopes). A sales agent that keeps no profile directory gets NO_PROFILE_DIRECTORY; contact team@allaboard.eu if yours should have one.

Searching Profiles ​

passengerProfiles takes:

  • filter: what to search by.
    • query: the text to find profiles by, at least one character besides blanks. It is matched against names the way the directory's own search does, or against email addresses when it contains an @.
    • salesAgentUid (optional): narrows the search to the profiles of one sales agent, your own or one you have access to. accessibleSalesAgents lists the ones you can book for. Without it the search spans every company you may book for.
  • first (optional): how many profiles to read, 1 to 25. It is 25 by default, and more is read as 25.
  • after (optional): a cursor from a previous page of the same search. See Paging.
Example: Search passenger profiles
graphql
query PassengerProfiles {
  passengerProfiles(filter: { query: "jane doe" }, first: 10) {
    edges {
      node {
        id
        firstName
        lastName
        birthDate
        email
        salesAgent {
          uid
          name
          costCenters {
            id
            name
            default
          }
        }
        costCenter {
          id
          name
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
query PassengerProfiles {
  passengerProfiles(filter: { query: "jane doe" }, first: 10) {
    edges {
      node {
        id
        firstName
        lastName
        birthDate
        email
        salesAgent {
          uid
          name
          costCenters {
            id
            name
            default
          }
        }
        costCenter {
          id
          name
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Paging ​

The list is a connection without a totalCount. Pages hold 25 profiles by default and at most, and can hold fewer than asked for, or none, while pageInfo.hasNextPage is still true. Continue with after set to pageInfo.endCursor. Cursors are opaque and only continue the search they came from, so present one with the same filter and first.

What a Profile Holds ​

A PassengerProfile always has these:

  • id identifies the profile in the profile directory it was read from. It is opaque: keep it for list keys, selection and spotting the same profile on another page, and never parse it. It identifies a profile, not a person, so the same person in two directories, or with two agencies, has two ids.
  • salesAgent is the company whose profile directory holds the profile. A booking from the profile is placed on one of its costCenters.
  • costCenter is the profile's preferred cost center: our best guess from the directory, to pre-select unless the person booking knows better. It is the cost center the directory names for the profile when we recognise it under salesAgent, otherwise the sales agent's default. Any of salesAgent.costCenters may be booked on instead.
  • travelCards are the profile's travel cards, as far as we recognise them. The list can be empty.

Every other detail, firstName, lastName, title, birthDate, email, tel and nationality, is null when the directory doesn't hold it or we could not read it.

A profile carries no passenger type and no age. Both depend on the travel date as well as the birth date, and a profile has no journey. Derive them from birthDate once you know the journey's departure date.

Errors ​

A search that can't run is an error, never an empty page:

  • FORBIDDEN: the API key lacks the passenger_profiles:read scope, or filter.salesAgentUid names a sales agent whose orders are switched off.
  • NO_PROFILE_DIRECTORY: your sales agent keeps no profile directory.
  • UPSTREAM_UNAVAILABLE: the profile directory could not be searched. Try again later.
  • UNAUTHORIZED: filter.salesAgentUid names a sales agent that is neither your own nor one you have access to.
  • INVALID_ARGUMENT: filter.query is blank, first is below 1, after comes from another search, or filter.salesAgentUid names a sales agent that is not a company in the profile directory.

A missing scope or a missing profile directory won't change when you retry, so offer the search only where it works.

Next Steps ​