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

bash

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

Success Response (200)

json

[
  {
    "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 survey, including all questions with multi-language support. The response structure varies based on the has_page value:

has_page: false: Questions are returned directly in the questions field
has_page: true: Questions are organized within pages in the pages field

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

bash

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

Success Response (200) - Without Pages

When has_page is false, questions are returned directly:

json

{
  "has_page": false,
  "translations": [
    {
      "language_code": "pt-BR",
      "nps": "Como você avalia sua experiência?",
      "discursive_question": "Deixe seu comentário",
      "question_page": "Em qual salão você se encontra?"
    },
    {
      "language_code": "en-US",
      "nps": "How do you rate your experience?",
      "discursive_question": "Leave your comment",
      "question_page": "Which salon are you at?"
    }
  ],
  "questions": [
    {
      "id": "q1-uuid-example",
      "required": true,
      "others": false,
      "unknown": false,
      "type": "Resposta curta",
      "format": "default",
      "options": [],
      "translations": [
        {
          "language_code": "pt-BR",
          "name": "Qual seu nome completo?",
          "description": "Informe seu nome para identificação"
        },
        {
          "language_code": "en-US",
          "name": "What is your full name?",
          "description": "Enter your name for identification"
        }
      ]
    },
    {
      "id": "q2-uuid-example",
      "required": false,
      "others": false,
      "unknown": false,
      "type": "Rating",
      "format": "default",
      "options": [
        {
          "id": "opt1-uuid",
          "translations": [
            {
              "language_code": "pt-BR",
              "name": "Excelente"
            },
            {
              "language_code": "en-US",
              "name": "Excellent"
            }
          ]
        },
        {
          "id": "opt2-uuid",
          "translations": [
            {
              "language_code": "pt-BR",
              "name": "Bom"
            },
            {
              "language_code": "en-US",
              "name": "Good"
            }
          ]
        }
      ],
      "translations": [
        {
          "language_code": "pt-BR",
          "name": "Como você avalia o atendimento?",
          "description": "Avalie a qualidade do atendimento recebido",
          "detractor_replica": "Lamentamos pela sua experiência",
          "neutral_replica": "Obrigado pelo feedback",
          "promoter_replica": "Ficamos felizes com sua avaliação!"
        },
        {
          "language_code": "en-US",
          "name": "How do you rate the service?",
          "description": "Rate the quality of the service received",
          "detractor_replica": "We're sorry for your experience",
          "neutral_replica": "Thank you for your feedback",
          "promoter_replica": "We're happy with your rating!"
        }
      ]
    }
  ]
}

Success Response (200) - With Pages

When has_page is true, questions are organized in pages:

json

{
  "has_page": true,
  "translations": [
    {
      "language_code": "pt-BR",
      "nps": "Como você avalia sua experiência?",
      "discursive_question": "Deixe seu comentário",
      "question_page": "Em qual salão você se encontra?"
    },
    {
      "language_code": "en-US",
      "nps": "How do you rate your experience?",
      "discursive_question": "Leave your comment",
      "question_page": "Which salon are you at?"
    }
  ],
  "pages": [
    {
      "id": "page1-uuid-example",
      "translations": [
        {
          "language_code": "pt-BR",
          "name": "Dados Pessoais"
        },
        {
          "language_code": "en-US",
          "name": "Personal Data"
        }
      ],
      "questions": [
        {
          "id": "q1-uuid-example",
          "required": true,
          "others": false,
          "unknown": false,
          "type": "Resposta curta",
          "format": "default",
          "options": [],
          "translations": [
            {
              "language_code": "pt-BR",
              "name": "Qual seu nome completo?",
              "description": "Informe seu nome para identificação"
            },
            {
              "language_code": "en-US",
              "name": "What is your full name?",
              "description": "Enter your name for identification"
            }
          ]
        }
      ]
    },
    {
      "id": "page2-uuid-example",
      "translations": [
        {
          "language_code": "pt-BR",
          "name": "Avaliação do Atendimento"
        },
        {
          "language_code": "en-US",
          "name": "Service Evaluation"
        }
      ],
      "questions": [
        {
          "id": "q2-uuid-example",
          "required": true,
          "others": false,
          "unknown": false,
          "type": "Rating",
          "format": "default",
          "options": [
            {
              "id": "opt1-uuid",
              "translations": [
                {
                  "language_code": "pt-BR",
                  "name": "Excelente"
                },
                {
                  "language_code": "en-US",
                  "name": "Excellent"
                }
              ]
            },
            {
              "id": "opt2-uuid",
              "translations": [
                {
                  "language_code": "pt-BR",
                  "name": "Bom"
                },
                {
                  "language_code": "en-US",
                  "name": "Good"
                }
              ]
            }
          ],
          "translations": [
            {
              "language_code": "pt-BR",
              "name": "Como você avalia o atendimento?",
              "description": "Avalie a qualidade do atendimento recebido",
              "detractor_replica": "Lamentamos pela sua experiência",
              "neutral_replica": "Obrigado pelo feedback",
              "promoter_replica": "Ficamos felizes com sua avaliação!"
            },
            {
              "language_code": "en-US",
              "name": "How do you rate the service?",
              "description": "Rate the quality of the service received",
              "detractor_replica": "We're sorry for your experience",
              "neutral_replica": "Thank you for your feedback",
              "promoter_replica": "We're happy with your rating!"
            }
          ]
        }
      ]
    }
  ]
}

Response Structure

Field	Type	Description
`has_page`	boolean	Indicates if the survey has multiple pages
`translations`	array	Translations of the survey's main texts
`questions`	array	List of questions (only when `has_page: false`)
`pages`	array	List of pages with questions (only when `has_page: true`)

`translations` object (survey)

Field	Type	Description
`language_code`	string	Language code (e.g., "pt-BR", "en-US", "es-ES")
`nps`	string	Main NPS question text
`discursive_question`	string	Discursive/comment question text
`question_page`	string	Page selection question text

Page Structure

Field	Type	Description
`id`	string	Unique page ID (UUID)
`translations`	array	Page name translations
`questions`	array	List of page questions

`translations` object (page)

Field	Type	Description
`language_code`	string	Language code (e.g., "pt-BR", "en-US")
`name`	string	Page name/title

Question Structure

Field	Type	Description
`id`	string	Unique question ID (UUID)
`required`	boolean	Whether the question is required
`others`	boolean	Whether "Others" option is allowed
`unknown`	boolean	Whether "Don't know/Unknown" option is allowed
`type`	string	Question type (see table below)
`format`	string	Display format (see table below)
`options`	array	Available response options
`translations`	array	Question translations in different 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

`translations` object (question)

Field	Type	Description
`language_code`	string	Language code (e.g., "pt-BR", "en-US")
`name`	string	Translated question text
`description`	string	Translated description (optional)
`promoter_replica`	string	Response for high scores (optional)
`neutral_replica`	string	Response for medium scores (optional)
`detractor_replica`	string	Response for low scores (optional)
`criteria`	string	Translated criteria (optional)

Option Structure

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

`translations` object (option)

Field	Type	Description
`language_code`	string	Language code (e.g., "pt-BR", "en-US")
`name`	string	Translated option text

Response Codes

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

Recommended Integration Flow

Fetch survey: GET /api/searches/:id
Select language: Filter translations by the desired language_code
Check has_page:
- If false: Iterate directly over questions
- If true: Show page selection and iterate over pages[].questions
Render questions: Use translations to display in the correct language

Surveys ​

List Surveys ​

Request Example ​

Success Response (200) ​

Response Structure ​

Response Codes ​

Get Survey with Questions ​

URL Parameters ​

Request Example ​

Success Response (200) - Without Pages ​

Success Response (200) - With Pages ​

Response Structure ​

translations object (survey) ​

Page Structure ​

translations object (page) ​

Question Structure ​

Question Types (type) ​

Display Formats (format) ​

translations object (question) ​

Option Structure ​

translations object (option) ​

Response Codes ​

Recommended Integration Flow ​

Surveys

List Surveys

Request Example

Success Response (200)

Response Structure

Response Codes

Get Survey with Questions

URL Parameters

Request Example

Success Response (200) - Without Pages

Success Response (200) - With Pages

Response Structure

`translations` object (survey)

Page Structure

`translations` object (page)

Question Structure

Question Types (type)

Display Formats (format)

`translations` object (question)

Option Structure

`translations` object (option)

Response Codes

Recommended Integration Flow