# 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](https://jsonapi.org/). # 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: ' 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 - **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** # 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 - **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": "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 - **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. - **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. - **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. - **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 [support@anyroad.com](mailto:support@anyroad.com).