Customers

This resource represents a customer (aka traveller) that books a product. Information contained within this resource is used for operational and billing purposes.

Internal processes are often used to merge records in order to provide a single view of a customer when duplicate records are found. When this occurs, a deleted Webhooks event will be fired. Subsequent GET requests to the deleted resource will return a 301 status code. This is an indication that any local copies of this record should be updated with the URI of the new customer resource listed in the Location field, in the header of the response. For further details on this code, please consult rest_errors.

XML Schema:

GET: get-customer

POST: create-customer

PATCH: update-customer

Fields

Name Type Description
id read-only String  
href read-only Field  
name required Nested Object  
  • legal_first_name required
String Legal first name as it appears on a passport.
  • legal_middle_name
String Legal middle name as it appears on a passport.
  • legal_last_name required
String Legal last name as it appears on a passport.
  • common_name
String The name this person likes to be called if different from their legal name.
  • title required
String The title. Valid values are: Mr, Mrs, Ms, and Miss
date_of_birth required Date The date of birth for the customer, often used to calculate the price when booking product.
place_of_birth String The location of birth, as it appears on a passport.
gender String The gender of the customer. Can be MALE, FEMALE, or UNKNOWN. Case-sensitive
nationality required Nested Object The nationality, as it appears on a passport.
passport Nested Object Passport information, as it is shown on the passport.
  • number
String Passport number.
  • issue_date
Date Passport date of issue.
  • expiry_date
Date Passport expiry date.
  • place_of_issue
String Passport place of issue.
medical_notes String DEPRECATED. Please use medical_details. Relevant medical/health notes to share with product operators. This is a required field and should be submitted with the value ‘None’ if the customer does not have any relevant medical/health notes.
medical_details Field Medical Details
  • type required
String The type of information supplied. Possible values are: MEDICAL_CONDITIONS: Pre-existing medical conditions that may impact the ability to complete or take part in trip activities, or travel to remote areas without access to medical care; RISK_TO_OTHERS: Pre-existing medical conditions that may put fellow travellers at risk; MOBILITY_ISSUES: Physical limitations or mobility issues that may impact participation in trip activities.
  • value required
String Text for this medical detail.
meal_preference String Relevant meal preferences to share with the product operators.
meal_notes String Relevant meal notes (i.e allergies) to share with product operators.
account_email String The email address for booking-related communication.
phone_numbers Field  
  • number required
String A telephone number. No specific format.
  • type required
String A brief description of the type of telephone number, must be one of the following values: Home, Business, Cell, Fax
emergency_contacts Field  
  • first_name required
String The first name of an emergency contact.
  • last_name required
String The last name of an emergency contact.
  • phone_numbers required
Field Telephone number information of emergency contacts.
    • number required
String A telephone number. No specific format.
    • type required
String A brief description of the type of telephone number, must be one of the following values: Home, Business, Cell, Fax
address Nested Object The address of the customer.
  • street
String The street of the billing address.
  • city
String The city of the billing address.
  • state
Nested Object The state/province of the billing address.
  • country
Nested Object The country of the billing address.
  • postal_zip
String The postal/zip of the billing address.
  • latitude
Decimal A geographic coordinate that specifies the north-south position of a point on the Earth’s surface (valid values range from -90.0 to 90.0)
  • longitude
Decimal A geographic coordinate that specifies the east-west position of a point on the Earth’s surface (valid values range from -180.0 to 180.0)
bookings read-only Nested Object A list of bookings associated with the customer.
membership_programs Field Membership Programs
  • code required
String A unique code identifying the membership program.
  • label required
String The membership program name.
  • value required
String Data specific to the membership program.

Get a Customer

GET /customers/(string: customer_id)/

Create a Customer

When creating a customer, please be aware that the unique id returned upon a successful 201 CREATED response may change for that particular customer shortly or in the distant future.

The reasoning for this is because upon creation of a customer, an asynchronous process is run to ensure the customer is not created as a duplicate, thus ensuring your data is clean and accurate. If a duplicate is found, the customer record you just created will now redirect to an existing customer record, that was found by this duplicate identification process.

You will receive a customers.deleted webhook when this identification merges two customers, but because this process can occur very quickly, it is recommended you do a GET on any existing customer instances you have before using the customer id in other HTTP methods (for instance, when creating a departure service)

POST /customers/

Example request:

POST /customers/ HTTP/1.1
Host: rest.gadventures.com
Accept: application/json
Content-Type:application/json

{
  "name": {
    "legal_first_name": "Gunther",
    "legal_last_name": "Strober",
    "legal_middle_name": "Maximilian",
    "common_name": "Gunt",
    "title": "Mr"
  },
  "date_of_birth": "1980-02-02",
  "place_of_birth": "Vienna",
  "gender": "MALE",
  "nationality": { "id": 13 },
  "passport": {
    "number": "HK12345",
    "issue_date": "2011-01-01",
    "expiry_date": "2021-01-01",
    "place_of_issue": "Graz"
  },
  "medical_notes": "mild macular degeneration, both eyes",
  "meal_preference": "No preference",
  "meal_notes": "No shellfish",
  "account_email": "gunt.strober@gmail.com",
  "phone_numbers": [
    { "number": "316 111 1111", "type": "Home" },
    { "number": "316 999 1456", "type": "Business" },
    { "number": "316 905 123", "type": "Cell" }
  ],
  "emergency_contacts": [
    {
      "first_name": "Anke",
      "last_name": "Strober",
      "phone_numbers": [{ "number": "316 111 1111", "type": "Home" }, { "number": "316 281 1314", "type": "Business" }]
    }
  ],
  "address": {
    "street": "Hoffnungslose Strasse 13",
    "city": "Graz",
    "state": { "id": "AT-6" },
    "country": { "id": "AT" },
    "postal_zip": "8010"
  }
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "id": "1008126",
  "href": "/customers/1008126",
  "name": {
    "legal_first_name": "Gunther",
    "legal_last_name": "Strober",
    "legal_middle_name": "Maximilian",
    "common_name": "Gunt",
    "title": "Mr"
  },
  "date_of_birth": "1980-02-02",
  "place_of_birth": "Vienna",
  "gender": "MALE",
  "nationality": { "id": "13", "href": "/nationalities/13", "name": "Austrian" },
  "passport": {
    "number": "HK12345",
    "issue_date": "2011-01-01",
    "expiry_date": "2021-01-01",
    "place_of_issue": "Graz"
  },
  "medical_notes": "mild macular degeneration, both eyes",
  "meal_preference": "No Preference",
  "meal_notes": "no shellfish",
  "account_email": "gunt.strober@gmail.com",
  "phone_numbers": [
    { "number": "316 111 1111", "type": "Home" },
    { "number": "316 999 1456", "type": "Business" },
    { "number": "316 905 123", "type": "Cell" }
  ],
  "emergency_contacts": [
    {
      "first_name": "Anke",
      "last_name": "Strober",
      "phone_numbers": [{ "number": "316 111 1111", "type": "Home" }, { "number": "316 281 1314", "type": "Business" }]
    }
  ],
  "address": {
    "street": "Hoffnungslose Strasse 13",
    "city": "Graz",
    "state": { "id": "AT-6", "href": "/states/AT-6", "name": "Steiermark" },
    "country": { "id": "AT", "href": "/countries/AT", "name": "Austria" },
    "postal_zip": "8010",
    "latitude": null,
    "longitude": null
  },
  "bookings": { "href": "/customers/1008126/bookings" }
}

Update a Customer

PATCH /customers/(string: customer_id)/

Example request:

PATCH /customers/1008126/ HTTP/1.1
Host: rest.gadventures.com
Accept: application/json
Content-Type:application/json

{
  "name": {
    "legal_first_name": "Gunther",
    "legal_last_name": "Strober",
    "legal_middle_name": "Maximilian",
    "common_name": "Gunt",
    "title": "Mr"
  },
  "date_of_birth": "1980-02-02",
  "place_of_birth": "Vienna",
  "gender": "MALE",
  "nationality": { "id": 13 },
  "passport": {
    "number": "HK12345",
    "issue_date": "2011-01-01",
    "expiry_date": "2021-01-01",
    "place_of_issue": "Graz"
  },
  "medical_notes": "mild macular degeneration, both eyes",
  "meal_preference": "No preference",
  "meal_notes": "No shellfish",
  "account_email": "gunt.strober@gmail.com",
  "phone_numbers": [
    { "number": "316 111 1111", "type": "Home" },
    { "number": "316 999 1456", "type": "Business" },
    { "number": "316 905 123", "type": "Cell" }
  ],
  "emergency_contacts": [
    {
      "first_name": "Anke",
      "last_name": "Strober",
      "phone_numbers": [{ "number": "316 111 1111", "type": "Home" }, { "number": "316 281 1314", "type": "Business" }]
    }
  ],
  "address": {
    "street": "Hoffnungslose Strasse 13",
    "city": "Graz",
    "state": { "id": "AT-6" },
    "country": { "id": "AT" },
    "postal_zip": "8010"
  }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "1008126",
  "href": "/customers/1008126",
  "name": {
    "legal_first_name": "Gunther",
    "legal_last_name": "Strober",
    "legal_middle_name": "Maximilian",
    "common_name": "Gunt",
    "title": "Mr"
  },
  "date_of_birth": "1980-02-02",
  "place_of_birth": "Vienna",
  "gender": "MALE",
  "nationality": { "id": "13", "href": "/nationalities/13", "name": "Austrian" },
  "passport": {
    "number": "HK12345",
    "issue_date": "2011-01-01",
    "expiry_date": "2021-01-01",
    "place_of_issue": "Graz"
  },
  "medical_notes": "mild macular degeneration, both eyes",
  "meal_preference": "No Preference",
  "meal_notes": "no shellfish",
  "account_email": "gunt.strober@gmail.com",
  "phone_numbers": [
    { "number": "316 111 1111", "type": "Home" },
    { "number": "316 999 1456", "type": "Business" },
    { "number": "316 905 123", "type": "Cell" }
  ],
  "emergency_contacts": [
    {
      "first_name": "Anke",
      "last_name": "Strober",
      "phone_numbers": [{ "number": "316 111 1111", "type": "Home" }, { "number": "316 281 1314", "type": "Business" }]
    }
  ],
  "address": {
    "street": "Hoffnungslose Strasse 13",
    "city": "Graz",
    "state": { "id": "AT-6", "href": "/states/AT-6", "name": "Steiermark" },
    "country": { "id": "AT", "href": "/countries/AT", "name": "Austria" },
    "postal_zip": "8010",
    "latitude": null,
    "longitude": null
  },
  "bookings": { "href": "/customers/1008126/bookings" }
}