1. Preparation

   • The Walla Response API is an API that allows the data collected via Walla to be integrated with external systems.

   • Using the Walla Response API, you can transfer data collected in Walla to external systems.

     The Walla Response API can only be used by users with admin privileges within the team. If you are not an admin, contact your team administrator to request permissions or obtain an API key from them.

     The team to which the project you want to access via the API belongs must be subscribed to the Enterprise plan.
     
     

2. Issuing an API Key

   • Team administrators in Walla can view and issue API keys from the team settings page in Walla.

     Make sure to check and save the API key and Client ID in a secure location, such as a notepad.

⚠️ Be careful not to expose the API key to external parties.

3. Glossary

   1. projectKey

      • The Walla project key is a unique value generated for each form created in Walla. This value can be found in the shared URL of the deployed Walla form.

        https://walla.my/v/{PROJECT_KEY}
        https://walla.my/survey/{PROJECT_KEY}

        
        

   2. fieldLabel

      • Refers to the Title inside each field of a Walla form.
        
        

   3. value

      • The response value given by survey participants for the corresponding fieldLabel.
        
        

   4. responseKey

      • Each response in a Walla survey has a unique response key.

      • This response key can be found in the Walla response sheet or received via a webhook.
        
        

   5. customerKey

      • A unique identifier for the person who participated in the Walla survey.

      • This key can be passed as a parameter in the survey URL when the respondent submits their answers, allowing you to track the survey with the unique identifier from the external system that manages customer information.

        ex)
        https://walla.my/survey/{PROJECT_KEY}?customerKey={CUSTOMER_KEY}
        https://walla.my/v/{PROJECT_KEY}?customerKey={CUSTOMER_KEY}

      
      

   6. fieldId

      • A unique key value for each field in a Walla survey.
        
        

   7. response

      • The response values given by participants in a Walla survey.

        • id: The unique key for the field, which is the same as fieldId.

        • label: The Title of the field, which is the same as fieldLabel.

        • answer: The value provided by the respondent for the field, which is the same as value.

          {
            "response": [
              {
                "id": "fieldId",
                "label": "fieldLabel",
                "answer": "value"
              },
              {
                "id": "fieldId",
                "label": "fieldLabel",
                "answer": "value"
              }
            ]
          }

      
      

4. Using the API

   1. Creating an Authorization Token

      • To use the Walla Response API, you need to first include the following in the headers:

        • key: "Authorization"

        • value: TOKEN
          
          

   2. Testing the API

      • You can test the Walla Response API using the following link (opens in a new tab)

      • On this page, enter the token you generated and click the [Try it out] button to test the API.
        
        

5. API 상세 스펙

   • base URL: https://staging---walla-api-thqwfj7gra-uc.a.run.app

   1. checkFieldDataExists: Check if a response exists for a specific field.

      • method: POST

      • url: https://staging---walla-api-thqwfj7gra-uc.a.run.app/checkFieldDataExists

      • parameters: empty

      • header: Authorization: {TOKEN}

      • request body:

      {
      "projectKey": "string",
      "fieldLabel": "string",
      "value": "string"
      }

      • response: It returns a boolean result with a true/false value.
        
        

   2. checkCustomerKeyExists: Check if a survey response exists for a specific customer.

      • method: POST

      • url: https://staging---walla-api-thqwfj7gra-uc.a.run.app/checkCustomerKeyExists

      • parameters: empty

      • header: Authorization: {TOKEN}

      • request body:

        {
        "projectKey": "string",
        "customerKey": "string"
        }

      • response: It returns a boolean result with a true/false value.
        
        

   3. listColumnData: Returns a list of responses for a specific field.

      • method: POST

      • url: https://staging---walla-api-thqwfj7gra-uc.a.run.app/listColumnData

      • parameters: empty

      • header: Authorization: {TOKEN}

      • request body:

        {
          "projectKey": "string",
          "fieldLabel": "string"
        }

      • response: Returns an array of information about responses for a specific field in a specific project. Each response includes the response content, timestamp, and response key.

        ⚠️ The timestamp is a date string in ISO 8601 format. ex) 2024-04-15T09:28:55.000Z

        {
        "fieldLabel": "string",
        "responses": [
            {
              "response": "string",
              "timestamp": "string",
              "responseKey": "string"
            }
          ],
        "fieldId": "string"
        }

   4. listCustomerKeys: customerKey 가 사용된 응답의 데이터를 배열로 반환합니다.

      • method: POST

      • url: https://staging---walla-api-thqwfj7gra-uc.a.run.app/listCustomerKeys

      • parameters: empty

      • header: Authorization: {TOKEN}

      • request body:

        {
          "projectKey": "string"
        }

      • response: Returns an array of data for responses where the customerKey is used.

        [
            {
                "customerKey": "string",
                "timestamp": "string"
            },
            {
                "customerKey": "string",
                "timestamp": "string"
            }
        ]

        
        

        
        

   5. getResponseByCustomerKey: Returns the survey response submitted by a specific customer.

      • method: POST

      • url: https://staging---walla-api-thqwfj7gra-uc.a.run.app/getResponseByCustomerKey

      • parameters: empty

      • header: Authorization: {TOKEN}

      • request body:

        {
          "projectKey": "string",
          "customerKey": "string"
        }

      • response: Returns responses associated with the customerKey. The response includes the timestamp, project key, response key, and customer key, and each object contains the field's unique fieldId (id), field's Title (label), and the response for that field (answer).

        {
          "timestamp": "string",
          "projectKey": "string",
          "responseKey": "string",
          "customerKey": "string",
          "response": [
            {
              "id": "string",
              "label": "string",
              "answer": "string"
            }
          ]
        }

        
        

   6. getResponseByResponseKey: Returns the response for a specific response key.

      • method: POST

      • url: https://staging---walla-api-thqwfj7gra-uc.a.run.app/getResponseByResponseKey

      • parameters: empty

      • header: Authorization: {TOKEN}

      • request body:

        {
          "projectKey": "string",
          "responseKey": "string"
        }

      • response: Returns responses associated with the responseKey. The response includes the timestamp, project key, response key, and customer key, and each object contains the field's unique fieldId (id), field's Title (label), and the response for that field (answer).

        {
          "timestamp": "string",
          "projectKey": "string",
          "customerKey": "string",
          "response": [
            {
              "id": "string",
              "label": "string",
              "answer": "string"
            }
          ]
        }

      
      

   7. getProjectResponses: Returns all responses for a specific project.

      • method: POST

      • url: https://staging---walla-api-thqwfj7gra-uc.a.run.app/getProjectResponses

      • parameters: empty

      • header: Authorization: {TOKEN}

      • request body:

        {
          "projectKey": "string"
        }

      • response: Returns all responses for a project. Each response includes the fieldId (id), field Title (label), timestamp, and hidden fields.

        {
            "projectDetails": {
                "fields": [
                    {
                        "id": "string",
                        "label": "string"
                    }
                ],
                "hiddenFields": [],
                "projectKey": "string"
            },
            "responses": [
                {
                    "timestamp": "string",
                    "customerKey": "string",
                    "responseKey": "string",
                    "response": [
                        {
                            "id": "string",
                            "label": "string",
                            "answer": "string"
                        }
                    ]
                },
                {
                    "timestamp": "string",
                    "customerKey": "string",
                    "responseKey": "string",
                    "response": [
                        {
                            "id": "string",
                            "label": "string",
                            "answer": "string"
                        }
                    ]
                }
            ]
        }

      
      

6. Error Response Codes

   1. All API calls require a TOKEN.

   2. 400 Bad Request

      • This is returned when an invalid value is provided for a specific key.

        {
          "message": "Bad Request"
        }

      • Returned when the project to be queried does not exist.

        {
          "message": "Bad Request: Project does not exist"
        }

   3. 403 Unauthorized & Forbidden

      • Returned when the issued Client ID does not have permission to access the project.

        {
          "message": "Unauthorized: No Access to Project"
        }

      • Returned when the Authorization token is missing in the header.

        {
          "message": "Unauthorized: No API Key"
        }

      • Returned when an invalid Authorization token is provided in the header.

        {
          "message": "Unauthorized: Invalid API Key"
        }

      • Returned when a person who is not an admin within the team attempts to use the API.

        {
          "message": "Unauthorized: No Access to API"
        }

   4. 500 Internal Server Error

      • Returned when a server error occurs.

        {
          "message": "Internal Server Error"
        }