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

XML Schema:

GET: Get a Customer

POST: Create a Customer

PATCH: Update a 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	Reference 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. * `MOBILITY_ISSUES`: Physical limitations or mobility issues that may impact participation in trip activities. * `RISK_TO_OTHERS`: Pre-existing medical conditions that may put fellow travellers at risk.
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: [`Home`, `Business`, `Cell`, `Fax`]
profile read-only	Reference Object	Salesforce Profile id associated with the customer
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: [`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	Reference Object	The state/province of the billing address.
country	Reference 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.
travel_credits read-only	Nested Object	A list of travel_credit 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.updated 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" }
}