Guest API | AnyRoad Help Center

Guest API

October 18, 2024

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
"janedoe@example.com: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: <your_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": "janedoe@example.com"
}
}
}

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": "guest@anyroad.com",
"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

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:

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:

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:

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

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,postvisit_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

Example Request

curl -XGET -H 'X-API-KEY: <your_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": "guest@anyroad.com",
"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

Example Request

curl -XGET -H 'X-API-KEY: <your_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 support@anyroad.com.