Surveys

Endpoints for querying available surveys.

List Surveys

GET /api/searches

Returns the list of surveys linked to the user's token.

Use cases:

• Get survey IDs for integration
• Populate survey selectors
• Validate available surveys for dispatch

Request Example

curl -X GET "https://api-b2s.experienciab2s.com/api/searches" \
     -H "Authorization: Bearer YOUR_TOKEN"

Success Response (200)

[
  {
    "id": "103a525c-0ce3-4182-a504-aad595425233",
    "name": "Satisfaction Survey - Restaurant",
    "company_id": "603a525c-0ce3-4182-a504-aad595425233"
  },
  {
    "id": "203a525c-0ce3-4182-a504-aad595425233",
    "name": "Satisfaction Survey - Delivery",
    "company_id": "503a525c-0ce3-4182-a504-aad595425233"
  }
]

Response Structure

Field	Type	Description
id	string	Unique survey ID (UUID)
name	string	Survey name
company_id	string	Linked company ID (UUID)

Response Codes

Code	Description
200	Surveys found
401	Missing or invalid token
403	Invalid token or unauthorized user
404	Integration token not found

Get Survey with Questions

GET /api/searches/:id

Returns the complete details of a specific survey, including all configured questions, response options, and available translations.

Use cases:

• Render custom survey form
• Get complete question structure for integration
• Load question translations for multilingual systems
• Validate question types and formats before submission

URL Parameters

Parameter	Type	Required	Description
id	string	Yes	Unique survey ID (UUID)

Request Example

curl -X GET "https://api-b2s.experienciab2s.com/api/searches/103a525c-0ce3-4182-a504-aad595425233" \
     -H "Authorization: Bearer YOUR_TOKEN"

Success Response (200)

{
  "nps": "How do you rate your experience?",
  "discursive_question": "Leave your comment",
  "questions": [
    {
      "id": "q1-uuid-example",
      "name": "How do you rate the service?",
      "required": true,
      "others": false,
      "unknown": false,
      "description": "Rate the quality of the service received",
      "type": "Rating",
      "format": "default",
      "detractor_replica": "We're sorry for your experience",
      "neutral_replica": "Thank you for your feedback",
      "promoter_replica": "We're happy with your rating!",
      "options": [
        {
          "id": "opt1-uuid",
          "name": "Excellent",
          "optionTranslations": [
            {
              "id": "trans1-uuid",
              "option_id": "opt1-uuid",
              "language_code": "pt",
              "name": "Excelente"
            },
            {
              "id": "trans2-uuid",
              "option_id": "opt1-uuid",
              "language_code": "es",
              "name": "Excelente"
            }
          ]
        }
      ],
      "translations": [
        {
          "id": "qtrans1-uuid",
          "question_id": "q1-uuid-example",
          "language_code": "pt",
          "name": "Como você avalia o atendimento?",
          "description": "Avalie a qualidade do atendimento recebido",
          "promoter_replica": "Ficamos felizes com sua avaliação!",
          "neutral_replica": "Obrigado pelo feedback",
          "detractor_replica": "Lamentamos pela sua experiência"
        }
      ]
    },
    {
      "id": "q2-uuid-example",
      "name": "Select the attendant",
      "required": true,
      "others": false,
      "unknown": true,
      "description": "Choose the attendant who served you",
      "type": "Atendente",
      "format": "select",
      "options": [
        {
          "id": "att1-uuid",
          "name": "John Smith",
          "optionTranslations": []
        },
        {
          "id": "att2-uuid",
          "name": "Mary Johnson",
          "optionTranslations": []
        }
      ],
      "translations": []
    }
  ]
}

Response Structure

Field	Type	Description
nps	string	Main NPS question text
discursive_question	string	Discursive/comment question text
questions	array	List of survey questions

Question Structure

Field	Type	Description
id	string	Unique question ID (UUID)
name	string	Question text/title
required	boolean	Whether the question is required
others	boolean	Whether "Others" option is allowed
unknown	boolean	Whether "Don't know/Unknown" option is allowed
description	string	Auxiliary question description
type	string	Question type (see table below)
format	string	Display format (see table below)
detractor_replica	string	Follow-up question for low scores - optional
neutral_replica	string	Follow-up question for medium scores - optional
promoter_replica	string	Follow-up question for high scores - optional
options	array	Available response options
translations	array	Question translations in other languages

Question Types (type)

Type	Description
Atendente	Attendant/employee selection
Caixa de seleção	Multiple choice with checkboxes
CSAT	Customer Satisfaction Score (1-5)
Data	Date selection field
Emoticon	Emoticon/emoji rating
Like/Dislike	Binary rating (like/dislike)
Multipla escolha	Selection among multiple options
NPS	Net Promoter Score (0-10)
Rating	Star/score rating
Resposta curta	Free text field

Display Formats (format)

Format	Description	Available in
default	Default display (buttons/cards)	All types
select	Dropdown menu	Atendente, Multipla escolha
checkbox	Multiple selection checkbox	Atendente

Option Structure

Field	Type	Description
id	string	Unique option ID (UUID)
name	string	Option text
optionTranslations	array	Option translations in other languages

OptionTranslation Structure

Field	Type	Description
id	string	Unique translation ID (UUID)
option_id	string	Related option ID
language_code	string	Language code (e.g., "pt", "es")
name	string	Translated option text

QuestionTranslation Structure

Field	Type	Description
id	string	Unique translation ID (UUID)
question_id	string	Related question ID
language_code	string	Language code (e.g., "pt", "es")
name	string	Translated question text
description	string	Translated description (optional)
promoter_replica	string	Translated follow-up question (high scores) (optional)
neutral_replica	string	Translated follow-up question (medium scores) (optional)
detractor_replica	string	Translated follow-up question (low scores) (optional)
criteria	string	Translated criteria (optional)

Response Codes

Code	Description
200	Survey found successfully
401	Missing or invalid token
403	Invalid token or unauthorized user
404	Survey not found