UserLoop API
UserLoop API Documentation
Welcome to the UserLoop API documentation! This guide will walk you through how to make requests to the UserLoop API to retrieve customer responses for a specific survey.
Authentication
To authenticate your request, you need to include an API key in the request headers:
x-api-key: YOUR_API_KEY
Replace YOUR_API_KEY with your actual UserLoop API key, which you can generate on your account settings page.
Getting Customer Responses
To retrieve customer responses for a specific survey, send a GET request to the following endpoint:
GET https://api.userloop.io/responses?survey={survey_id}
Replace {survey_id} with the unique identifier of the survey for which you want to retrieve responses.
Example Request
Here's an example GET request to retrieve customer responses for a survey with the ID 1624128792784x564539260540351000:
curl -X GET "https://api.userloop.io/responses?survey=1624128792784x564539260540351000" \
-H "x-api-key: YOUR_API_KEY"Responses Endpoint
The API will return a JSON object containing an array of customer response objects. Each response object contains various fields, such as the customer's answer, answer ID, created timestamp, and more. Refer to the field descriptions section below for a detailed explanation of each field.
- answer: A string representing the customer's answer to the question.
- answer_id: A unique identifier for the specific answer provided by the customer.
- coupon_amount: A string representing the discount amount in the coupon applied to the order (e.g., "0.00").
- coupon_code: A string representing the code used for applying the coupon discount.
- created_at: A timestamp in ISO 8601 format representing when the record was created.
- customer_firstname: The first name of the customer.
- customer_lastname: The last name of the customer.
- customer_order_count: An integer representing the total number of orders placed by the customer.
- discount_generated: A boolean indicating whether a discount was generated for the order.
- email: The email address of the customer.
- followup_question: A boolean indicating whether there was a follow-up question after the initial question.
- landing_page: A string representing the URL path of the landing page where the order was placed.
- line_items: An array of strings listing the names of products included in the order.
- marketing_opt_in: A boolean indicating whether the customer has opted in for marketing communications.
- order_currency_code: A string representing the currency code used for the order (e.g., "GBP").
- order_id: A unique identifier for the order.
- order_platform: A string representing the platform on which the order was placed (e.g., "shopify").
- order_total: A float representing the total amount of the order.
- other: A boolean indicating whether the customer has provided additional information or an alternative answer.
- other_response: A string representing any additional information or alternative answer provided by the customer.
- product_ids: An array of strings listing the unique identifiers of products included in the order.
- question: A string representing the text of the question asked to the customer.
- question_id: A unique identifier for the specific question asked.
- question_type: A string representing the type of question asked (e.g., "Multi Select").
- parent_question: A string representing the text of the parent question, if applicable.
- parent_question_id: A unique identifier for the parent question, if applicable.
- landing_page: A string representing the URL of the website that referred the customer to your site.
- response_id: A unique identifier for the customer's response.
- trigger: A string representing the event or context that triggered the question (e.g., "Shopify Order Confirmation Page").
- utm_campaign: A string representing the UTM campaign parameter, if applicable.
- utm_content: A string representing the UTM content parameter, if applicable.
- utm_source: A string representing the UTM source parameter, if applicable.
- utm_term: A string representing the UTM term parameter, if applicable.
The Response Object
{
"coupon_amount": "5.00",
"coupon_code": "WELCOME5",
"coupon_type": "percentage",
"created_at": "2023-04-01T10:30:25+00:00",
"customer_firstname": "Jane",
"customer_id": "1234567890123",
"customer_lastname": "Doe",
"customer_order_count": 5,
"discount_generated": true,
"email": "jane.doe@example.com",
"followup_question": true,
"l2": "/products/special",
"line_items": ["product A", "product B", "product C"],
"marketing_opt_in": true,
"order_currency_code": "EUR",
"order_id": "9876543210987",
"order_platform": "shopify",
"order_total": "99.99",
"other": true,
"other_response": "Friend's recommendation",
"product_ids": [7, 8, 9, 10, 11],
"question": "Where did you find our store?",
"question_id": 42,
"question_type": "multiple_choice",
"referring_question": "Did someone refer you?",
"referring_question_id": 41,
"referring_site": "https://bing.com",
"response": "Social Media",
"response_id": 10101,
"response_provided_at": "2023-04-01T10:29:59Z",
"trigger": "shopify",
"utm_campaign": "spring_sale",
"utm_content": "banner_ad",
"utm_medium": "cpc",
"utm_source": "facebook",
"utm_term": "spring_collection"
}Getting Surveys, Questions & Answers
Retrieve a list of available surveys and their details.
GET https://api.userloop.io/surveys
Example Request
Here's an example GET request to retrieve all surveys
curl -X GET "https://api.userloop.io/surveys" \
-H "x-api-key: Your API key" \The Survey Endpoint
The API will return a JSON object containing an array of surveys. Each survey contains information about the survey, it's questions and answer options.
survey_title: A string representing the title of the survey.
survey_format: A string representing the format in which the survey is delivered (e.g., "Email").
survey_type: A string representing the type of survey (e.g., "CSAT").
survey_id: A unique identifier for the survey.
questions: An array of question objects, each with the following properties:
question: A string representing the text of the question.
question_type: A string representing the type of question (e.g., "Single Select", "Multi Select", "Open Ended", "Video").
question_order: An integer representing the order of the question within the survey.
required: A boolean indicating whether the question is required to be answered.
is_followup: A boolean indicating whether the question is a follow-up question.
followup_question_id: A unique identifier for the follow-up question, if applicable.
placeholder: A string representing the placeholder text for the question input field, if applicable.
other_enabled: A boolean indicating whether an "Other" option is available for the question.
returning_customers_only: A boolean indicating whether the question is only shown to returning customers.
new_customers_only: A boolean indicating whether the question is only shown to new customers.
subheading: A string representing the subheading for the question, if applicable.
answers: An array of answer objects, each with the following properties:
answer_text: A string representing the text of the answer option.
answer_id: A unique identifier for the specific answer option.
other: A boolean indicating whether the answer option represents an "Other" option. Null if not applicable.
answer_order: An integer representing the order of the answer option within the question.
The Survey Object
{
"survey_title": "Customer Satisfaction Survey",
"survey_format": "Email",
"survey_type": "CSAT",
"survey_id": "1621425970612x489232427424619140",
"questions": [
{
"question": "How would you rate your overall experience with our service?",
"question_type": "Single Select",
"question_order": 1,
"required": true,
"is_followup": false,
"followup_question_id": "",
"placeholder": "Please select your answer",
"other_enabled": false,
"returning_customers_only": false,
"new_customers_only": false,
"subheading": "Get 20% off for responding to this survey",
"answers": [
{
"answer_text": "Excellent",
"answer_id": "1647265558406x910648232202469400",
"other": null,
"answer_order": 1
},
{
"answer_text": "Good",
"answer_id": "1647265561160x664820754398052400",
"other": null,
"answer_order": 2
},
{
"answer_text": "Average",
"answer_id": "1647265563453x754829485638105350",
"other": null,
"answer_order": 3
},
{
"answer_text": "Poor",
"answer_id": "1647265566140x892748573848573480",
"other": null,
"answer_order": 4
},
{
"answer_text": "Very Poor",
"answer_id": "1647265569235x983947563845738450",
"other": null,
"answer_order": 5
}
]
}
]Updated on: 25/04/2023
Thank you!