API
La API está basada en REST y usa HTTP response codes para indicar errores. Todas las respuestas de la API serán en formato JSON, incluyendo los errores.
La API funcionará con cualquier programa que tenga una librería HTTP, como cURL. También puede ser utilizada directamente desde cualquier browser.
Los clientes pueden enviar peticiones a través de HTTPS protegiendo así aún más el flujo de información.
API Endpoint
Las llamadas a la API siempre deberán ser apuntadas al siguiente endpoint. A partir de ese punto variarán por versión y recurso a consumir.
https://api.surveykiwi.comAuth
Antes de poder hacer uso de la API deberás autenticarte con tus llaves de acceso (API_KEY y API_SECRET) que encontrarás o podrás generar en la sección "Mi Cuenta". Si ya las generaste aparecerán en los ejemplos pero sólo tú podrás verlas.
Como resultado obtendrás un access_token que te servirá para realizar llamadas a la API. Puedes utilizar este token mientras sea válido y no haya expirado, caso contrario deberás solicitar otro.
Estas llaves son privadas y únicas y no deben ser compartidas con nadie ni expuestas en códigos client-side.
Returns
Devuelve un objeto con el tipo de token, el token en sí y un valor numérico que indica, en segundos, la vida útil del token.
curl -X POST https://api.surveykiwi.com/oAuth2/token \
-d grant_type=Client_Credentials \
-d client_id=API_KEY \
-d client_secret=API_SECRET{
"token_type": "Bearer",
"expires_in": 900,
"access_token": "[ACCESS_TOKEN]",
"refresh_token": "[REFRESH_TOKEN]"
}Errores
Utilizamos códigos de respuesta HTTP para indicar que una petición a la API fue exitosa o no.
Por lo general códigos en el rango de 2xx indican éxito en la consulta, mientras que códigos en el rango de 4xx indican que algo falló con la información requerida (por ejemplo: falta de algún parámetro, parámetros incorrectos, etc.), y finalmente códigos del tipo 5xx refieren a fallas en el servidor.
Atributos
-
error
El tipo de error. Puede ser:
invalid_token,method_exception,validation_exception,Unauthorized,not_found,internal_server_error,service_unavailable, -
error_description
Es la descripción del error en formato amigable
Códigos de respuesta HTTP
| 200 - OK | Todo funcionó de acuerdo a lo esperado. |
|---|---|
| 400 - Bad Request | La petición no fue aceptada, posiblemente por fallas en la validación de los parámetros enviados (falta de datos o datos equivocados). |
| 401 - Unauthorized | Las llaves de acceso no son correctas o estás queriendo acceder a información restringida. |
| 404 - Not Found | El recurso no existe. |
| 405 - Method Not Allowed | El método (GET, POST, PUT, DELETE) no está permitido para esta petición. |
| 500, 502, 503, 504 - Server Errors | Algo funcionó mal en los servidores. |
Errores
| invalid_token | The access token provided is expired, revoked, malformed, or invalid for other reasons. |
|---|---|
| method_exception | El método utilizado no está permitido. |
| validation_exception | Esta [pregunta|campaña|etc] no te pertenece, Parámetro desconocido, etc. |
| Unauthorized | No estás autorizado para realizar esta acción. |
| not_found | Recurso no encontrado. |
| internal_server_error | Hubo un problema en el servidor. |
| service_unavailable | El servicio no está disponible por el momento. |
Paginado
Todos los recursos que devuelven una lista de objetos pueden ser paginados.
Utiliza dos parámetros, offset y limit, para dar la posibilidad de paginar resultados.
Parámetros
-
limit opcional, default es 10
Límite en el número de objetos a ser devueltos, entre 1 y 100.
-
offset opcional, default es 0
Número que representa a partir de qué posición van a ser devueltos los resultados.
curl -G https://api.surveykiwi.com/v1.0/campaign/list \
--header "Authorization: Bearer [ACCESS_TOKEN]" \
-d offset=0 \
-d limit=2[
{
"id": "55486",
"project_name": "Employee Satisfaction Survey",
"url": "satisfaction-employee",
"state": "active",
"language": "en-us",
"show_responses": 0,
"hidden_fields": 1,
"participants": 4,
"questions": [],
"created_at": "2021-10-06T12:14:23-0300",
"updated_at": "2021-10-06T12:15:34-0300"
},{
"id": "55482",
"project_name": "Product test",
"url": "product-test",
"state": "active",
"language": "en-us",
"show_responses": 0,
"hidden_fields": 1,
"participants": 10,
"questions": [],
"created_at": "2021-10-06T11:52:06-0300",
"updated_at": "2021-10-06T11:58:07-0300"
},
]Campaign
Con este recurso podrás hacer consultas para obtener una lista de tus campañas disponibles y también la lista de respuestas de cada encuesta.
Lista de campañas
Podrás consultar todas tus campañas filtrando por diferentes parámetros.
Parámetros
-
access_token obligatorio
Token obtenido en /oAuth2/token.
-
show_questions opcional, default es 0
Define si quieres que la respuesta incluya la lista de preguntas asociadas a la encuesta. 0 o 1.
-
show_options opcional, default es 0
Define si quieres que la respuesta incluya la lista de opciones asociadas a cada pregunta de la encuesta. 0 o 1.
-
offset opcional, default es 0
EL número de la primer respuesta que deseas.
-
limit opcional, default es 10
Limita la cantidad de respuestas, entre 1 y 100.
-
order_by[] opcional, default es null
Regla para ordenar los resultados. Variable+ASC|DESC separados por coma.
-
where[] opcional, default es null
Regla para filtrar resultados. Formato JSON. Las variables del JSON son
type,var,operatoryval. La variabletypeadmite como valores posiblesdefaulty sirve para definir dentro de qué entorno buscar el valor deval. La variablevaradmite como valores posibles la mayoría de las variables del objeto dentro del entorno definido portype. La variableoperatoradmite como valores posibles operadores de comparación como "=", "<", ">", "<=", ">=", "IS", "IS NOT", etc. La variablevaladmite como valores cualquier dato que quieras.
Returns
Devuelve una lista con objetos. Cada uno contiene la información de una encuesta, sus preguntas y opciones.
GET https://api.surveykiwi.com/v1.0/campaign/listcurl -G https://api.surveykiwi.com/v1.0/campaign/list \
--header "Authorization: Bearer [ACCESS_TOKEN]" \
-d show_questions=1 \
-d show_options=1 \
-d offset=0 \
-d limit=2 \
-d order_by[]=created_at,DESC \
-d where[]='{"type":"default","var":"created_at","operator":"<=","val":"2024-11-21T14:05:24-0300"}'[
{
"id": "55486",
"project_name": "Employee Satisfaction Survey",
"url": "satisfaction-employee",
"state": "active",
"language": "en-us",
"show_responses": 0,
"hidden_fields": 1,
"participants": 4,
"questions": [
{
"id": "542079",
"question": "Please select your department",
"description": null,
"type": "multiple_picture",
"picture": null,
"options": [
{
"id": "1885043",
"option": "Operations",
"thumbnail": "https://d3ejpfy8d58pjw.cloudfront.net/campaigns5f1854022ce73_e9ad2ffa416034b6daacf51cf28d77d9.png",
"alert": null
},{
"id": "1885044",
"option": "Marketing",
"thumbnail": "https://d3ejpfy8d58pjw.cloudfront.net/campaigns5f18540d5584c_8d22454e916e009169c4f3c71ad17719.png",
"alert": null
},
{...}
]
},{
"id": "542080",
"question": "How long have you worked for the company?",
"description": null,
"type": "multiple_choice",
"picture": null,
"options": [
{
"id": "1885051",
"option": "Less than 3 months",
"thumbnail": null,
"alert": null
},{
"id": "1885052",
"option": "Between 3 months and 1 year",
"thumbnail": null,
"alert": null
},
{...}
]
},
{...}
]
"created_at": "2021-10-06T12:14:23-0300",
"updated_at": "2021-10-06T12:15:34-0300"
},{
"id": "55482",
"project_name": "Product test",
"url": "product-test",
"state": "active",
"language": "en-us",
"show_responses": 0,
"hidden_fields": 1,
"participants": 10,
"questions": [
{
"id": "542026",
"question": "How much time have you been using the product? ",
"description": null,
"type": "multiple_choice",
"picture": null,
"options": [
{
"id": "1884929",
"option": "Less than 1 week",
"thumbnail": null,
"alert": null
},{
"id": "1884930",
"option": "Between 1 week and 1 month",
"thumbnail": null,
"alert": null
},
{...}
]
},{
"id": "542027",
"question": "From the following, select any brands that you have bought or tried in the past. ",
"description": null,
"type": "multiple_choice",
"picture": null,
"options": [
{
"id": "1884934",
"option": "BRAND 1",
"thumbnail": null,
"alert": null
},{
"id": "1884935",
"option": "BRAND 2",
"thumbnail": null,
"alert": null
},
{...}
]
},
{...}
]
"created_at": "2021-10-06T11:52:06-0300",
"updated_at": "2021-10-06T11:58:07-0300"
},
]Respuestas de una campaña
Podrás consultar las respuestas de una campaña en particular.
Parámetros
-
access_token obligatorio
Token obtenido en /oAuth2/token.
-
campaign_url obligatorio
"URL name" única de la campaña. ej: satisfaccion
-
status opcional, default es "all"
Permite
active,pending,all. Elige si quieres filtrar las respuestas de usuarios que terminaron la encuesta o no. -
answers opcional, default es "show"
Permite
hideshow. Elige si quieres mostras las respuestas de un encuestado. -
offset opcional, default es 0
EL número de la primera respuesta que deseas.
-
limit opcional, default es 10
Limita la cantidad de respuestas, entre 1 y 100.
-
order_by[] opcional, default es null
Regla para ordenar los resultados. Variable+ASC|DESC separados por coma.
-
where[] opcional, default es null
Regla para filtrar resultados. Formato JSON. Las variables del JSON son
type,var,operatoryval. La variabletypeadmite como valores posibleshiddenfields,participantydefaulty sirve para definir dentro de qué entorno buscar el valor deval. La variablevaradmite como valores posibles la mayoría de las variables del objeto dentro del entorno definido portype. La variableoperatoradmite como valores posibles operadores de comparación como "=", "<", ">", "<=", ">=", "IS", "IS NOT", etc. La variablevaladmite como valores cualquier dato que quieras.
Returns
Devuelve una lista con objetos. Cada uno contiene la información recolectada cuando un usuario responde una encuesta. Datos del encuestado, hiddenfields, lista de preguntas con las respuestas elegidas, etc.
GET https://api.surveykiwi.com/v1.0/campaign/answerscurl -G https://api.surveykiwi.com/v1.0/campaign/answers \
--header "Authorization: Bearer [ACCESS_TOKEN]" \
-d campaign_url=product-test \
-d status=active \
-d offset=0 \
-d limit=2 \
-d order_by[]=created_at,DESC \
-d where[]='{"type":"default","var":"created_at","operator":"<=","val":"2024-11-21T14:05:24-0300"}'[
{
"participant": {
"id": "1840844",
"customs": null,
},
"hiddenfields": {
"name": "Sergei",
"email": "sergei@google.com",
},
"questions": [
{
"id": "542036",
"question": "To start with, choose your gender",
"description": "If you don't want to answer this question you can just click NEXT.",
"answers": [
"https://d3ejpfy8d58pjw.cloudfront.net/campaigns/5f4cfb3f5a555_6e48f2c839ab63c6d7710f9ea4d13bc9.png",
]
},
{
"id": "542026",
"question": "How much time have you been using the product? ",
"description": null,
"answers": [
"Less than 1 week",
]
},
{
"id": "542035",
"question": "What was your first impression with the product?",
"description": null,
"answers": [
"Very positive",
]
},
{
"id": "542027",
"question": "From the following, select any brands that you have bought or tried in the past. ",
"description": null,
"answers": [
"BRAND 2",
"BRAND 3",
"BRAND 4",
"BRAND 5",
]
},
{
"id": "542028",
"question": "When you bought the product, did you analyze any other brands or just our product? ",
"description": null,
"answers": [
"I analyzed several brands",
]
},
{
"id": "542029",
"question": "How frecuently do you use the product?",
"description": null,
"answers": [
"More than once a day",
]
},
{
"id": "542030",
"question": "The following questions will be regarding attributes and characteristics of the product.",
"description": null,
"answers": [],
},
{
"id": "542031",
"question": "Which of the following was the most important characteristic for you to decide to acquire the product?",
"description": "Choose only the MOST important one.",
"answers": [
"Design",
]
},
{
"id": "542032",
"question": "Which is you current <b>general satisfaction</b> level with the product? ",
"description": null,
"answers": [
"Completely satisfied",
]
},
{
"id": "542033",
"question": "Would you recommend this product to a friend who is looking for a product inside this category?",
"description": null,
"answers": [
"10",
]
},
{
"id": "542034",
"question": "If you could change something about the product, what would it be?",
"description": null,
"answers": [
"Perfect product. I will definitely continue using it",
]
},
],
"created_at": "2021-10-06T12:12:32-0300",
"finished_at": "2021-10-06T12:13:10-0300",
"duration": 38,
"score": 0.00,
},
{
"participant": {
"id": "1840832",
"customs": null,
},
"hiddenfields": {
"name": "Joe",
"email": "joe@gmail.com",
},
"questions": [
{
"id": "542036",
"question": "To start with, choose your gender",
"description": "If you don't want to answer this question you can just click NEXT.",
"answers": [
"https://d3ejpfy8d58pjw.cloudfront.net/campaigns/5f4cfb3f5a555_6e48f2c839ab63c6d7710f9ea4d13bc9.png",
]
},
{
"id": "542026",
"question": "How much time have you been using the product? ",
"description": null,
"answers": [
"Between 6 months and 1 year",
]
},
{
"id": "542035",
"question": "What was your first impression with the product?",
"description": null,
"answers": [
"Very negative",
]
},
{
"id": "542027",
"question": "From the following, select any brands that you have bought or tried in the past. ",
"description": null,
"answers": [
"BRAND 4",
"BRAND 5",
]
},
{
"id": "542028",
"question": "When you bought the product, did you analyze any other brands or just our product? ",
"description": null,
"answers": [
"I analyzed one or two brands at most",
]
},
{
"id": "542029",
"question": "How frecuently do you use the product?",
"description": null,
"answers": [
"Less than once a week",
]
},
{
"id": "542030",
"question": "The following questions will be regarding attributes and characteristics of the product.",
"description": null,
"answers": [],
},
{
"id": "542031",
"question": "Which of the following was the most important characteristic for you to decide to acquire the product?",
"description": "Choose only the MOST important one.",
"answers": [
"Size",
]
},
{
"id": "542032",
"question": "Which is you current <b>general satisfaction</b> level with the product? ",
"description": null,
"answers": [
"Dissatisfied",
]
},
{
"id": "542033",
"question": "Would you recommend this product to a friend who is looking for a product inside this category?",
"description": null,
"answers": [
"2",
]
},
{
"id": "542034",
"question": "If you could change something about the product, what would it be?",
"description": null,
"answers": [
"Terrible quality of the product",
]
},
],
"created_at": "2021-10-06T12:01:39-0300",
"finished_at": "2021-10-06T12:02:13-0300",
"duration": 34,
"score": 0.00,
},
]Question
Con este recurso podrás obtener un objeto único con la información de una pregunta específica.
Detalles de una pregunta
Obtendrás los detalles de una pregunta específica pasando como parámetro el ID.
Parámetros
-
access_token obligatorio
Token obtenido en /oAuth2/token.
-
id obligatorio
ID único de la pregunta
Returns
Devuelve un objeto con toda la información disponible de una pregunta en particular y sus opciones.
GET https://api.surveykiwi.com/v1.0/questioncurl -G https://api.surveykiwi.com/v1.0/question \
--header "Authorization: Bearer [ACCESS_TOKEN]" \
-d id=542026{
"id": "542026",
"question": "How much time have you been using the product? ",
"description": null,
"type": "multiple_choice",
"max_length": null,
"mandatory": null,
"position": "2",
"picture": null,
"random": null,
"range_from": null,
"range_to": null,
"other": null,
"alerts": null,
"alert_words": null,
"options": [
{
"id": "1884929",
"option": "Less than 1 week",
"thumbnail": null,
"alert": null
},
{
"id": "1884930",
"option": "Between 1 week and 1 month",
"thumbnail": null,
"alert": null
},
]
}Webhooks
Usa los webhooks para ser notificado cuando un usuario responda una encuesta en tiempo real.
las APIs pueden enviar notificaciones a tu aplicación cuando un usuario responda cualquiera de tus encuestas en el momento en que las responde.
Esto es muy útil para los casos en que necesites alimentar tu propia base de datos con las respuestas de tus usuarios sin la necesidad de recurrir a las APIs para obtener esta información.
Puedes registrar tus URLs a las que se enviarán notificaciones apenas suceda una acción.
Se enviará una notificación a esta URL vía HTTP POST con toda la información obtenida en la respuesta de un usuario.
Cuando usar Webhooks
Los webhooks sólo son necesarios para obtener información detrás de escena en tiempo real.
Puedes utilizar webhooks para:
- Guardar las respuestas de los usuarios en el momento en que estos responden.
- Enviar un email a tus usuarios apenas responden una encuesta.
- Ser notificado mediante PUSH en tu celular a través de aplicaciones de terceros.
- Generar reportes propios en tu aplicación.
Configuración
Puedes configurar tus webhooks en la sección APIs de tu dashboard.
En el bloque Webhooks haz click en "Crear Webhook". Ingresa la URLs hacia donde quieres que se envien las notificaciones y guarda los cambios.
Puedes enviar notificaciones de prueba para configurar el endpoint de tu lado.
Es posible ingresar cualquier URL que quieras, pero es recomendable que tus endpoints sean dedicados para recibir información de las APIs.
Recibiendo una notificación de Webhook
Crear un webhoook endpoint en tu servidor no es diferente a crear cualquier página de tu sitio web.
Con PHP deberías crear un nuevo archivo .php destinado a recibir la información y proporcionar una respuesta.
Los datos enviados por webhook estarán en formato JSON. Deberás procesarlo y devolver un status 200 para notificar que el mensaje fue recibido con éxito.
{
"campaign": {
"id": "55482",
"project_name": "Product test",
"url": "product-test",
"url_complete": "https%3A%2F%2Fsupport.surveykiwi.com%2Fproduct-test"
},
"participant": {
"id": "1840844",
},
"hiddenfields": {
"name": "Sergei",
"email": "sergei@google.com",
},
"questions": [
{
"id": "542036",
"question": "To start with, choose your gender",
"description": "If you don't want to answer this question you can just click NEXT.",
"answers": [
{
"id": "11931336",
"text": "Man",
"original_answer": "Man",
"picture": "https://d3ejpfy8d58pjw.cloudfront.net/campaigns/5f4cfb3f5a555_6e48f2c839ab63c6d7710f9ea4d13bc9.png",
"score": null,
"alert": null,
"option_type": "regular"
},
]
},
{
"id": "542026",
"question": "How much time have you been using the product? ",
"description": null,
"answers": [
{
"id": "11931337",
"text": "Less than 1 week",
"original_answer": "Less than 1 week",
"picture": null,
"score": null,
"alert": null,
"option_type": "regular"
},
]
},
{
"id": "542035",
"question": "What was your first impression with the product?",
"description": null,
"answers": [
{
"id": "11931338",
"text": "Very positive",
"original_answer": "Very positive",
"picture": null,
"score": null,
"alert": null,
"option_type": "regular"
},
]
},
{
"id": "542027",
"question": "From the following, select any brands that you have bought or tried in the past. ",
"description": null,
"answers": [
{
"id": "11931339",
"text": "BRAND 2",
"original_answer": "BRAND 2",
"picture": null,
"score": null,
"alert": null,
"option_type": "regular"
},
{
"id": "11931340",
"text": "BRAND 3",
"original_answer": "BRAND 3",
"picture": null,
"score": null,
"alert": null,
"option_type": "regular"
},
{
"id": "11931341",
"text": "BRAND 4",
"original_answer": "BRAND 4",
"picture": null,
"score": null,
"alert": null,
"option_type": "regular"
},
{
"id": "11931342",
"text": "BRAND 5",
"original_answer": "BRAND 5",
"picture": null,
"score": null,
"alert": null,
"option_type": "regular"
},
]
},
{
"id": "542028",
"question": "When you bought the product, did you analyze any other brands or just our product? ",
"description": null,
"answers": [
{
"id": "11931343",
"text": "I analyzed several brands",
"original_answer": "I analyzed several brands",
"picture": null,
"score": null,
"alert": null,
"option_type": "regular"
},
]
},
{
"id": "542029",
"question": "How frecuently do you use the product?",
"description": null,
"answers": [
{
"id": "11931344",
"text": "More than once a day",
"original_answer": "More than once a day",
"picture": null,
"score": null,
"alert": null,
"option_type": "regular"
},
]
},
{
"id": "542030",
"question": "The following questions will be regarding attributes and characteristics of the product.",
"description": null,
"answers": [],
},
{
"id": "542031",
"question": "Which of the following was the most important characteristic for you to decide to acquire the product?",
"description": "Choose only the MOST important one.",
"answers": [
{
"id": "11931345",
"text": "Design",
"original_answer": "Design",
"picture": null,
"score": null,
"alert": null,
"option_type": "regular"
},
]
},
{
"id": "542032",
"question": "Which is you current <b>general satisfaction</b> level with the product? ",
"description": null,
"answers": [
{
"id": "11931346",
"text": "Completely satisfied",
"original_answer": "Completely satisfied",
"picture": null,
"score": null,
"alert": null,
"option_type": "regular"
},
]
},
{
"id": "542033",
"question": "Would you recommend this product to a friend who is looking for a product inside this category?",
"description": null,
"answers": [
{
"id": "11931347",
"text": "10",
"original_answer": "10",
"picture": null,
"score": null,
"alert": null,
"option_type": "regular"
},
]
},
{
"id": "542034",
"question": "If you could change something about the product, what would it be?",
"description": null,
"answers": [
{
"id": "11931348",
"text": "Perfect product. I will definitely continue using it",
"original_answer": "Perfect product. I will definitely continue using it",
"picture": null,
"score": null,
"alert": null,
"option_type": "regular"
},
]
},
],
"thankyou_screen": {
"id": "91138",
"type": "custom",
"title": "Thank you for your feedback!",
"description": "Your information help us improve the quality of our products and new features.",
"button_text": null,
"button_url": null,
"picture": "",
"video": null,
"show_responses": null
},
"created_at": "2021-10-06T12:12:32-0300",
"finished_at": "2021-10-06T12:13:10-0300",
"duration": 38,
"score": 0.00,
}
Respondiendo al webhook
Para notificarnos de que tu servidor recibió la información enviada, tu endpoint deberá responder un status 200 (HTTP status code)
Todos los status fuera del rango 200, incluyendo los códigos 3xx, indicará que el envío falló y que no recibiste la información enviada.
Esto significa que una redirección o una respuesta del tipo "Not Modified" será interpretada como un fallo.
Se ignorará cualquier otra información enviada en el header o en el body de la respuesta.
En tu dashboard, en la sección APIs podrás obtener información y chequear el historial de eventos enviados a tus endpoints.
Comprobando las firmas del Webhook
Se firmarán los webhooks que se envíen a tus endpoints. Se incluirá una firma en el header SK-Signature por cada envío. Esto te ayudará a validar que el envío de datos haya salido de la plataforma y no por terceros.
Antes de poder validar las firmas deberás tomar nota de ellas en el panel donde se encuentran tus webhooks.
Previniendo ataques de reenvíos.
Un ataque de reenvíos es cuando interceptan un envío válido con su correspondiente firma y la reenvían. Para prevenir estos ataques se agrega un timestamp en el header SK-Signature. De esta manera podrás comprobar si la firma es válida al afirmar que no ha pasado cierto tiempo comparado con el timestamp enviado.
Verificando Firmas.
El header SK-Signature contiene un timestamp y una firma. El timestamp está prefijado por un t=, y la firma está prefijada por un esquema. El esquema comienza con una v seguida por un número entero. Por ahora sólo será válido el número 1, por lo que el esquema válido será v1
SK-Signature: \
t=1539794213,
v1=720c0195d5fc0d6dc06accf258d3aaf6165a729efbda7f3628d54803576e2c9e