Skip to main content

​
Overview

Surveys allow community administrators to collect feedback and opinions from residents. Each survey can contain multiple questions of different types.

​
Question Types

Surveys support different question types:
  • tipoPregunta = 0: Multiple choice
  • tipoPregunta = 1: Text response
  • tipoPregunta = 2: Rating scale

​
Get All Surveys

GET /api/encuestas
Returns all surveys in the system. Authorization: Required (ADMIN_COMPANY, SYSTEM_ADMIN) Response: 
[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "communityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "communityName": "Example Community",
    "titulo": "Community Satisfaction Survey",
    "descripcion": "Help us improve our community services",
    "fechaInicio": "2026-03-01T00:00:00Z",
    "fechaFin": "2026-03-31T23:59:59Z",
    "isActive": true,
    "createdAt": "2026-02-28T08:00:00Z",
    "updatedAt": "2026-02-28T08:00:00Z",
    "preguntas": [
      {
        "id": "4fa85f64-5717-4562-b3fc-2c963f66afa6",
        "tipoPregunta": 0,
        "pregunta": "How satisfied are you with our services?",
        "opciones": ["Very satisfied", "Satisfied", "Neutral", "Dissatisfied"]
      },
      {
        "id": "5fa85f64-5717-4562-b3fc-2c963f66afa6",
        "tipoPregunta": 1,
        "pregunta": "What improvements would you suggest?",
        "opciones": []
      }
    ]
  }
]

​
Get Surveys by Community

GET /api/encuestas/community/{communityId}
Returns all surveys for a specific community. Authorization: Required (ADMIN_COMPANY, SYSTEM_ADMIN) Path Parameters:
  • communityId (guid, required): Community ID
Response: Same structure as Get All Surveys

​
Get Survey by ID

GET /api/encuestas/{id}
Returns a specific survey by ID, including all questions. Authorization: Required (ADMIN_COMPANY, SYSTEM_ADMIN) Path Parameters:
  • id (guid, required): Survey ID
Response: 
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "communityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "communityName": "Example Community",
  "titulo": "Community Satisfaction Survey",
  "descripcion": "Help us improve our community services",
  "fechaInicio": "2026-03-01T00:00:00Z",
  "fechaFin": "2026-03-31T23:59:59Z",
  "isActive": true,
  "createdAt": "2026-02-28T08:00:00Z",
  "updatedAt": "2026-02-28T08:00:00Z",
  "preguntas": [
    {
      "id": "4fa85f64-5717-4562-b3fc-2c963f66afa6",
      "tipoPregunta": 0,
      "pregunta": "How satisfied are you with our services?",
      "opciones": ["Very satisfied", "Satisfied", "Neutral", "Dissatisfied"]
    }
  ]
}
Error Responses:
  • 404 Not Found: Survey not found

​
Create Survey

POST /api/encuestas
Creates a new survey with questions. Authorization: Required (ADMIN_COMPANY, SYSTEM_ADMIN) Request Body: 
{
  "communityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "titulo": "Community Satisfaction Survey",
  "descripcion": "Help us improve our community services",
  "fechaInicio": "2026-03-01T00:00:00Z",
  "fechaFin": "2026-03-31T23:59:59Z",
  "isActive": true,
  "preguntas": [
    {
      "tipoPregunta": 0,
      "pregunta": "How satisfied are you with our services?",
      "opciones": ["Very satisfied", "Satisfied", "Neutral", "Dissatisfied"]
    },
    {
      "tipoPregunta": 1,
      "pregunta": "What improvements would you suggest?",
      "opciones": null
    }
  ]
}
Field Validations:
  • communityId (guid, required): Community ID
  • titulo (string, required): Survey title
  • descripcion (string, required): Survey description
  • fechaInicio (datetime, required): Survey start date
  • fechaFin (datetime, required): Survey end date
  • isActive (boolean, optional): Default: true
  • preguntas (array, optional): List of questions to include
Question Fields:
  • tipoPregunta (integer, required): Question type (0: multiple choice, 1: text, 2: rating)
  • pregunta (string, required): Question text
  • opciones (array of strings, optional): Available options for multiple choice questions
Response: Same structure as Get Survey by ID Status Code: 201 Created Error Responses:
  • 400 Bad Request: Invalid data or validation error

​
Update Survey

PUT /api/encuestas/{id}
Updates an existing survey and its questions. Authorization: Required (ADMIN_COMPANY, SYSTEM_ADMIN) Path Parameters:
  • id (guid, required): Survey ID
Request Body: 
{
  "communityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "titulo": "Updated Survey Title",
  "descripcion": "Updated description",
  "fechaInicio": "2026-03-01T00:00:00Z",
  "fechaFin": "2026-03-31T23:59:59Z",
  "isActive": true,
  "preguntas": [
    {
      "tipoPregunta": 0,
      "pregunta": "Updated question?",
      "opciones": ["Option 1", "Option 2"]
    }
  ]
}
Field Validations: Same as Create Survey Response: Same structure as Get Survey by ID Error Responses:
  • 404 Not Found: Survey not found
  • 400 Bad Request: Invalid data or validation error

​
Delete Survey

DELETE /api/encuestas/{id}
Deletes a survey and all associated questions and responses. Authorization: Required (ADMIN_COMPANY, SYSTEM_ADMIN) Path Parameters:
  • id (guid, required): Survey ID
Response: No content Status Code: 204 No Content Error Responses:
  • 404 Not Found: Survey not found

​
Submit Survey Responses

POST /api/encuestas/{id}/responder
Allows a resident to submit their responses to a survey. The resident ID is automatically obtained from the authenticated user. Authorization: Required (authenticated resident) Path Parameters:
  • id (guid, required): Survey ID
Request Body: 
{
  "respuestas": [
    {
      "preguntaId": "4fa85f64-5717-4562-b3fc-2c963f66afa6",
      "respuesta": "Very satisfied"
    },
    {
      "preguntaId": "5fa85f64-5717-4562-b3fc-2c963f66afa6",
      "respuesta": "The community could improve communication and maintenance services."
    }
  ]
}
Field Structure:
  • respuestas (array, required): List of responses
    • preguntaId (guid, required): Question ID from the survey
    • respuesta (string, required): The resident’s answer
Response: No content Status Code: 204 No Content Error Responses:
  • 400 Bad Request: Invalid data, survey not active, or user is not registered as a resident
  • 401 Unauthorized: User is not authenticated
Notes:
  • Each resident can only submit responses once per survey
  • The survey must be active and within the date range (between fechaInicio and fechaFin)
  • For multiple choice questions, the response should match one of the available options
  • For text questions, any string response is accepted
  • The resident ID is automatically extracted from the authenticated user’s JWT token

​
Survey Object Schema

FieldTypeDescription
idguidUnique identifier for the survey
communityIdguidCommunity ID
communityNamestringName of the community (populated from community data)
titulostringSurvey title
descripcionstringSurvey description
fechaIniciodatetimeSurvey start date
fechaFindatetimeSurvey end date
isActivebooleanWhether the survey is active
createdAtstringISO date string for creation time
updatedAtstringISO date string for last update time (optional)
preguntasarrayArray of question objects

​
Question Object Schema

FieldTypeDescription
idguidUnique identifier for the question
tipoPreguntaintegerQuestion type (0: multiple choice, 1: text, 2: rating)
preguntastringQuestion text
opcionesarrayArray of option strings (for multiple choice questions)

Build docs developers (and LLMs) love

Get started for freeTalk to us