Skip to main content
All CollectionsIntegrations & APIsAPIs
Guest API
Guest API
Updated over 2 months ago

The guest API provides info related to guests making a booking through the AnyRoad platform, including name, last name, email address, and add-ons.

To make requests to our API, you will need an API key. Your AnyRoad user id and password are your normal AnyRoad account login credentials. Once you receive your API key, you will be able to make requests to all endpoints. Please keep your API key secure. If you believe your key has been compromised, please contact us for a new one.

All responses adhere to the JSON:API formatting guidelines found here: JSON API — A specification for building APIs in JSON.

Requesting an API Key

Please reach out to your AnyRoad Account Manager to activate your API key. Once activated, send the below request to receive your API key. You will need the AnyRoad account registered email and password associated with the owner of the account.

Request:

You can copy the following:

curl https://app.anyroad.com/external/api/v1/users/key -u
"[email protected]:SuperSecretPa$word"

Response:

Status: 200 

{
"data": {
"type": "users",
"id": "123",
"attributes": {
"key": "example-key-1234"
}
}
}

API Key Verification

To verify that your API key is active, send the following request, where is your API key:

Request:

curl -H 'X-API-KEY: '
https://app.anyroad.com/external/api/v1/users/profile

Response:

Status: 200

{
"data": {
"type": "users",
"id": "123",
"attributes": {
"first_name": "Jane",
"last_name": "Doe",
"email": "[email protected]"
}
}
}

Guests

A guest represents a customer who has made a booking for one of your experiences within the AnyRoad platform. Each guest record is unique for every booking made -- for example, two bookings made by the same person would create two guest records. The data on a guest record reflects the information they have directly entered during the checkout process through answering questions during checkout, as well as any other information gathered through other methods such as feedback surveys.

The Guest Object

{
"data": {
"id": "12345",
"type": "guest",
"attributes": {
"type": "booker"
"first_name": "Roadie",
"last_name": "Guest",
"email": "[email protected]",
"phone": "+14151234567",
"street_address": "540 Howard St",
"city": "San Francisco",
"state_province": "CA",
"postal_code": "94105",
"country": "US",
"birthdate": "1970-01-01",
"gender": "M",
"nps_score_previsit": 8,
"nps_score_postvisit": null,
"nps_score_postvisit_text": null
"checked_in": "2023-07-13T00:00:00Z"
},
"relationships": { ... }
},
"included": [ ... ]
}

Attributes

  • id (alphanumeric): The unique identifier of the guest on a booking.

  • booking_id (integer): The unique identifier of the booking the guest relates to.

  • type (alphanumeric): The guest type, booker or additional_guest.

  • first_name (string): Guest first name.

  • last_name (string): Guest last name.

  • email (string): Guest email.

  • phone (string): Guest phone number including country code, in E.164 format.

  • street_address (string): Guest street address as provided during checkout.

  • city (string): Guest city of residence as provided during checkout.

  • state_province (string): Guest state or province as provided during checkout.

  • postal_code (string): Guest zip or postal code as provided during checkout.

  • country (string): Guest country as provided during checkout. Expressed in ISO alpha-2 representation, e.g. “US”.

  • birthdate (date): Guest date of birth.

  • gender (string): Guest gender. Guest gender is derived from first name and region:

    • M: Male

    • F: Female

  • created (date): Date the guest was created.

  • updated (date): Date the guest was updated.

  • nps_score_previsit (integer): The Net Promoter Score (NPS) answered by guests during checkout before their experience. Ranges from 0 - 10.

  • nps_score_postvisit (integer): The Net Promoter Score (NPS) answered by guests after attending their experience. Ranges from 0 - 10.

  • nps_score_postvisit_text (string): Any text feedback guest submitted along with their nps_score_postvisit.

  • checked_in (date): Date the guest checked in. Will be blank if the guest has not checked in.

Relationships

In addition to the core guest attributes, there may be additional data associated with guests. The IDs and types of associated data records are included alongside the core guest attributes.

Marketing Opt-ins

Guest responses to questions during checkout are marked as marketing opt-ins.

Relationship Key: marketing_optins

Attributes:

  • question (string): The main text of the marketing opt-in question presented to the guest.

  • question_subtext (string): Additional text displayed under the main question.

  • answer (string): The answer provided by the guest.

  • answer_english (string): If the question was presented in a language other than English and has translations available, then this field will contain the English translation of the answer. Otherwise, it will be null.

  • optin_type (string): The types of marketing opt-in:

    • general: General

    • email: Email

    • phone: Phone

Purchase Behavior Answers (Pre-Visit)

These are the guest responses to questions during checkout marked as purchase behavior questions, e.g. “How often in the past 6 months have you consumed this beverage?”.

Relationship Key: previsit_purchase_behavior_answers

Attributes:

  • question (string): The main text of the question presented to the guest.

  • question_subtext (string): Additional text displayed under the main question.

  • answer (string): The answer provided by the guest.

  • answer_english (string): If the question was presented in a language other than English and has translations available, then this field will contain the English translation of the answer. Otherwise, it will be null.

Feedback Answers (Post-Visit)

These are guest responses to all questions on their post-experience feedback survey, answered in conjunction with nps_score_postvisit and nps_score_postvisit_text.

Relationship Key: postvisit_feedback_answers

Attributes:

  • question (string): The main text of the question presented to the guest.

  • question_subtext (string): Additional text displayed under the main question text above.

  • answer (string): The answer as provided by guest

Checkout Answers

These are guest responses to any additional questions during checkout that are not marketing opt-ins, purchase behavior, or birthdate.

Relationship Key: checkout_answers

Attributes:

  • question (string): The main text of the question presented to the guest.

  • question_subtext (string): Additional text displayed under the main question.

  • answer (string): The answer provided by the guest.

  • answer_english (string): If the question was presented in a language other than English and has translations available, then this field will contain the English translation of the answer. Otherwise, it will be null.

Including Associated Data

While the IDs and types of relationships are always included inside the “relationships” object by default, the actual data is not. To include the associated data, the API request must contain an included parameter with a comma-separated list of relationship names. All associated data will be included in the “included” property of the response JSON.

Request:

Example Request to include a single relationship’s data:

[URL]?include=marketing_optins

Example Request to include data from 4 different relationships:

[URL]?include=marketing_optins,checkout_answers,previsit_purchase_behavior_answers,postvis
it_feedback_answers

Please refer to the Current Relationships section above for the full list of names of relationships that the Guests API currently supports.

Response:

Example Response:

{
"data": {
"id": "12345",
"type": "guest",
"attributes": { ... },
"relationships": {
"marketing_optins": {
"data": [
{
"id": "11111",
"type": "marketing_optin"
},
{ ... },
]
},
"checkout_answers": {
"data": [
{
"id": "22222",
"type": "checkout_answer"
},
{ ... },
]
},
"previsit_purchase_behavior_answers": {
"data": [
{
"id": "33333",
"type": "previsit_purchase_behavior_answer"
},
{ ... },
]
},
"postvisit_feedback_answers": {
"data": [
{
"id": "44444",
"type": "postvisit_feedback_answer"
},
{ ... },
]
}
}
},
"included": [
{
"id": "11111",
"type": "marketing_optin",
"attributes": {
"question": "Want to be the first to know about new products via
email?",
"question_subtext": "",
"answer": "Yes",
"answer_english": null,
"optin_type": "email"
}
},
{
"id": "22222",
"type": "checkout_answer",
"attributes": {
"question": "How did you hear about this experience?",
"question_subtext": "",
"answer": "Email",
"answer_english": null
}
},
{
"id": "33333",
"type": "previsit_purchase_behavior_answer",
"attributes": {
"question": "In the past 12 months, how often did you make a purchase
at [BRAND]?",
"question_subtext": "",
"answer": "Once a Month",
"answer_english": null
}
},
{
"id": "44444",
"type": "postvisit_feedback_answer",
"attributes": {
"question": "Would you attend another event like this?",
"question_subtext": "",
"answer": "Yes"
}
}
]
}

Endpoints

Retrieve a Guest

Retrieve details about an existing guest record. It requires the guest_id to be passed in as a URL parameter in order to look up the corresponding record.

URL:

https://app.anyroad.com/external/api/v1/guests/

Parameters

  • include (string) - optional: Comma-separated list of relationship keys for which to include data. Refer to the “Including Associated Data” section in this document.

Example Request

curl -XGET -H 'X-API-KEY: '
'https://app.anyroad.com/external/api/v1/guests/'

Example Response

Status: 200 - OK

{
"data": {
"id": "2161130",
"type": "guest",
"attributes": {
"first_name": "Roadie",
"last_name": "Guest",
"email": "[email protected]",
"phone": "+14151234567",
"street_address": "540 Howard St",
"city": "San Francisco",
"state_province": "CA",
"postal_code": "94105",
"country": "US",
"birthdate": "1970-01-01",
"gender": "M",
"nps_score_previsit": 8,
"nps_score_postvisit": null,
"nps_score_postvisit_text": null
},
"relationships": {
"marketing_optins": {
"data": []
},
"checkout_answers": {
"data": []
},
"previsit_purchase_behavior_answers": {
"data": []
},
"postvisit_feedback_answers": {
"data": []
}
}
}
}

Status: 401 - Unauthorized

 { error: "Invalid API key." }

Status: 404 - Not Found

 { error: "Not Found." }

List all Guests

List all guest records that have been created. Guests are returned in sorted order, with the most recent guests appearing first.

URL:

https://app.anyroad.com/external/api/v1/guests

Parameters

  • booking_id (string) - optional: The ID of a booking in the AnyRoad system. Used to filter the results to a specific booking. All guest records associated with the particular booking will be listed.

  • date_type (string) - optional: The type of date queried by from_date and to_date . If date_type is not provided, queries will default to experience date.

    • experience: date range applies to the experience date of the booking. For example, if a guest placed their booking on 2018-03-01 for an experience on 2018-04-01, the data returned will be based on the 2018-04-01 experience date. Experience date is in your local timezone, and the time portion of the query is ignored. For example, from_date “2018-01-01T00:00:00 00:00” with to_date “2018-01-01T00:00:00 00:00” will return all bookings that happened on 2018-01-01 local time. “2018-01-01T14:00:00 00:00” will return the same results since time is ignored for experience date.

    • booking: date range applies to the booking date of the booking. For example, if a guest placed their booking on 2018-03-01 for an experience on 2018-04-01, the data returned will be based on the 2018-03-01 booking date. Booking date is in UTC time and includes the time portion of the query. For example from_date “2018-01-01T14:00:00 00:00” with to_date “2018-01-01T16:00:00 00:00” will return all bookings that were placed between 2018-01-01 at 14:00 to 2018-01-01 at 16:00 in UTC. If you want to query booking date based on your own local timezone you can modify the last portion of the query. For example, to translate the UTC time into PDC (UTC -7) you would modify the query like this: “2018-01-01T14:00:00 -07:00”.

    • created: date range applies to the created date of the guest. Created date is in UTC time and includes the time portion of the query. For example from_date “2018-01-01T14:00:00 00:00” with to_date “2018-01-01T16:00:00 00:00” will return all guests that were created between 2018-01-01 at 14:00 to 2018-01-01 at 16:00 in UTC. If you want to query the created date based on your own local timezone you can modify the last portion of the query. For example, to translate the UTC time into PDC (UTC -7) you would modify the query like this: “2018-01-01T14:00:00 -07:00”.

    • updated: date range applies to the updated date of the guests. Updated date is in UTC time and includes the time portion of the query. For example from_date “2018-01-01T14:00:00 00:00” with to_date “2018-01-01T16:00:00 00:00” will return all guests that were updated between 2018-01-01 at 14:00 to 2018-01-01 at 16:00 in UTC. If you want to query the updated date based on your own local timezone you can modify the last portion of the query. For example, to translate the UTC time into PDC (UTC -7) you would modify the query like this: “2018-01-01T14:00:00 -07:00”.

  • from_date (datetime) - optional: RFC 3339 date representation. In local time for experience date with time ignored. In UTC time for booking date with time and timezone allowed. Example: “2018-01-01T14:00:00 00:00”. If from_date is not provided, queries will default to yesterday, beginning of day.

  • to_date (datetime) - optional: RFC 3339 date representation. In local time for experience date with time ignored. In UTC time for booking date with time and timezone allowed. Example: “2018-01-01T14:00:00 00:00”. If from_date is not provided, queries will default to yesterday, end of day.

  • include (string) - optional: Comma-separated list of relationship keys for which to include data for. Refer to the “Including Associated Data” section in this document.

  • page (integer) - optional: The page of results to be returned. Default is 1. Each page contains up to 20 guest records

Example Request 

curl -XGET -H 'X-API-KEY: '
'https://app.anyroad.com/external/api/v1/guests'

Example Response

Status: 200 - OK

{
"data": {
"id": "11111",
"type": "guest",
"attributes": {
"relationships": { ... }
},
{ ... },
{ ... },
// ...
],
"included": [ ... ],
"meta": {
"totalPages": 1000
},
"links": {
"self": "https://app.anyroad.com/external/api/v1/guests?page=1",
"first": "https://app.anyroad.com/external/api/v1/guests?page=1",
"prev": null,
"next": "https://app.anyroad.com/external/api/v1/guests?page=2",
"last": "https://app.anyroad.com/external/api/v1/guests?page=1000"
}
}

Status: 400 - Bad Request

 { error: "Bad Request." }

Status: 401 - Unauthorized

 { error: "Invalid API key." }

If you have any additional questions, you can contact our Customer Experience team via chat or at [email protected].

Related Articles
Time Slot API
Experiences API
Customer Profile API
Bookings API
Tickets API
Did this answer your question?