설문 연동하기

응답 API

Walla Open API로 폼 데이터와 응답을 조회하고 관리하세요.

Walla Open API 가이드

Walla Open API를 사용하면 폼 데이터와 응답을 프로그래밍 방식으로 조회하고 관리할 수 있습니다.

버전 정보

변경 사항이 있으면 새 버전으로 제공됩니다.

API 인증 설정

API 키 발급

인증 방식

Walla API는 API Key 인증 방식을 사용합니다. 모든 요청에 아래 헤더를 포함하세요.

X-WALLA-API-KEY: {발급받은 API 키}

기본 URL

https://app.walla.my/open-api/v1

API 엔드포인트

워크스페이스

워크스페이스 목록 조회

접근 권한이 있는 전체 워크스페이스 목록을 조회합니다.

GET /open-api/v1/workspaces

응답 예시:

{  
  "success": true,  "data": [    {      "id": "workspace_abc123",      "name": "마케팅팀 워크스페이스",  
      "teamId": "team_xyz789",      "createdAt": "2024-01-15T09:00:00Z",      "updatedAt": "2024-01-20T14:30:00Z"    }  ]}

워크스페이스 상세 조회

특정 워크스페이스의 상세 정보를 조회합니다.

GET /open-api/v1/workspaces/{workspaceId}

파라미터:

이름위치필수설명
workspaceId경로O워크스페이스 ID

폼 (프로젝트)

전체 폼 목록 조회

접근 권한이 있는 모든 워크스페이스의 폼 목록을 조회합니다.

GET /open-api/v1/forms

워크스페이스 내 폼 목록 조회

특정 워크스페이스 내의 폼 목록을 조회합니다.

GET /open-api/v1/workspaces/{workspaceId}/forms

파라미터:

이름위치필수설명
workspaceId경로O워크스페이스 ID

폼 상세 조회

특정 폼의 상세 정보를 조회합니다.

GET /open-api/v1/forms/{formId}

파라미터:

이름위치필수설명
formId경로O폼 ID

응답 예시:

{  
  "success": true,  "data": {    "id": "form_abc123",    "title": "고객 만족도 조사",  
    "description": "서비스 이용 후 만족도를 평가해주세요",  
    "teamId": "team_xyz789",    "workspaceId": "workspace_abc123",    "creator": "user_123",    "isDeleted": false,    "createdAt": "2024-01-15T09:00:00Z",    "updatedAt": "2024-01-20T14:30:00Z"  }}

필드

폼 필드 목록 조회

특정 폼의 게시된 필드 목록을 조회합니다.

GET /open-api/v1/forms/{formId}/fields

파라미터:

이름위치필수설명
formId경로O폼 ID (게시된 설문의 ID)

응답 예시:

{  
  "success": true,  "data": {    "fields": [      {        "id": "field_001",        "label": "이름을 입력해주세요",  
        "fieldType": "SHORT_TEXT",        "outputType": "string"      },      {        "id": "field_002",        "label": "만족도를 선택해주세요",  
        "fieldType": "RADIO",        "outputType": "string"      }    ]  }}

필드 상세 조회

특정 필드의 상세 정보(속성, 검증 규칙, 출력 스키마 등)를 조회합니다.

GET /open-api/v1/forms/{formId}/fields/{fieldId}

파라미터:

이름위치필수설명
formId경로O폼 ID
fieldId경로O필드 ID

필드 출력 스키마 조회

필드 타입별 출력 스키마 매핑 정보를 조회합니다. 각 필드 타입이 어떤 형식의 데이터를 반환하는지 확인할 수 있습니다.

GET /open-api/v1/field-output-schemas

응답 데이터

응답 목록 조회

특정 폼의 응답 목록을 페이지네이션으로 조회합니다. customerKey 파라미터로 특정 고객의 응답만 필터링할 수도 있습니다.

GET /open-api/v1/forms/{formId}/responses

파라미터:

이름위치필수설명
formId경로O폼 ID
customerKey쿼리X고객 키로 필터링 (해당 customerKey를 가진 응답만 조회)
page쿼리X페이지 번호 (1부터 시작, 기본값: 1)
limit쿼리X페이지당 응답 개수 (최대 100, 기본값: 20)

응답 예시:

{  
  "success": true,  "data": {    "responses": [      {        "responseId": "resp_abc123",        "customerKey": "customer_001",        "submittedAt": "2024-01-20T14:30:00Z",        "field_001": "홍길동",  
        "field_002": "매우 만족",  
        "hidden-field_utm": "facebook"      }    ],    "pagination": {      "page": 1,      "limit": 20,      "totalCount": 150,      "totalPages": 8    }  }}

customerKey로 필터링 예시:

GET /open-api/v1/forms/{formId}/responses?customerKey=customer_001

단일 응답 조회

특정 응답의 상세 정보를 조회합니다.

GET /open-api/v1/forms/{formId}/responses/{responseId}

파라미터:

이름위치필수설명
formId경로O폼 ID
responseId경로O응답 ID

응답 예시:

{  
  "success": true,  "data": {    "responseId": "resp_abc123",    "formId": "form_abc123",    "teamId": "team_xyz789",    "workspaceId": "workspace_abc123",    "response": {      "field_001": "홍길동",  
      "field_002": "매우 만족",  
      "hidden-field_utm": "facebook"    },    "submittedAt": "2024-01-20T14:30:00Z",    "customerKey": "customer_001",    "startedAt": "2024-01-20T14:25:00Z"  }}

Form Delivery (발송)

참고: Form Delivery 기능은 ONPREM 환경에서만 사용 가능합니다. SaaS 환경에서는 사용할 수 없습니다.

폼 발송

특정 프로젝트(게시된 설문)를 수신인에게 발송합니다. 게시되지 않은 설문은 발송할 수 없습니다.

POST /open-api/v1/forms/{formId}/delivery

파라미터:

이름위치필수설명
formId경로O폼 ID

요청 본문:

{  
  "recipients": [    {      "customerKey": "customer_001",      "email": "user@example.com",      "phoneNumber": "010-1234-5678"    }  ],  "subject": "설문이 도착했습니다.",  
  "message": "설문 링크를 확인하세요."  
}
필드필수설명
recipientsO수신자 목록 (배열)
recipients[].customerKeyO고객 식별 키
recipients[].emailX이메일 주소
recipients[].phoneNumberX전화번호
subjectX이메일 제목 (기본값: "설문이 도착했습니다.")
messageX발송 메시지

수신인 목록 조회

특정 프로젝트의 전체 수신인 목록을 조회합니다.

GET /open-api/v1/forms/{formId}/delivery

수신인 상태 조회

특정 수신인들의 진행 상태를 조회합니다.

POST /open-api/v1/forms/{formId}/delivery/status

요청 본문:

{  
  "customerKeys": ["customer_001", "customer_002"]}

응답 예시:

{  
  "success": true,  "data": [    {      "id": "delivery_abc123",      "formId": "form_abc123",      "customerKey": "customer_001",      "email": "user@example.com",      "status": "RESPONDED",      "lastSentAt": "2024-01-20T10:00:00Z",      "createdAt": "2024-01-19T09:00:00Z"    }  ]}

발송 상태 값:

상태설명
NOT_SENT아직 발송되지 않음
SENT발송됨
OPENED링크 열람함
RESPONDED응답 완료함

응답 데이터 구조

필드 타입별 응답 값 형식

각 필드 값의 형식은 필드 타입에 따라 다릅니다.

필드 타입출력 형식예시
SHORT_TEXT, LONG_TEXTstring"홍길동"
RADIO, DROPDOWNstring"옵션1"
CHECKBOXstring[]["옵션1", "옵션2"]
FILE_UPLOADstring[]["https://...file1.pdf"]
DATEstring"2024-01-20"
NUMBERstring"42"

상세한 출력 스키마는 GET /open-api/v1/field-output-schemas API를 참조하세요.

히든 필드

히든 필드는 hidden-{필드ID} 형식의 키로 응답 데이터에 포함됩니다.

{  
  "hidden-field_abc123": "facebook",  "hidden-field_xyz789": "spring_campaign"}

히든 필드 값은 URL 파라미터로 전달됩니다.

https://walla.my/v/{formId}?utm_source=facebook&utm_campaign=spring_campaign

customerKey

customerKey는 Form Delivery에서 각 수신자를 식별하기 위해 자동 생성되는 값입니다.

  • 발송 상태 추적 (발송됨 → 열람 → 응답완료)에 사용합니다.
  • 응답 데이터를 필터링할 때 활용할 수 있습니다.
  • Form Delivery를 사용하지 않으면 비어 있을 수 있습니다.

에러 응답

API 요청이 실패하면 HTTP 상태 코드와 에러 메시지가 반환됩니다.

상태 코드설명
400잘못된 요청 (파라미터 오류 등)
403인증 실패 또는 권한 없음
404리소스를 찾을 수 없음
500서버 에러

에러 응답 예시:

{  
  "error": "Form not found or not published"}

사용 예시

1. customerKey를 활용한 응답 연동 시나리오

  • 외부 시스템의 고객 ID를 Walla customerKey로 사용합니다.
  • GET /forms/{formId}/responses?customerKey={customerKey}로 해당 고객의 응답을 조회합니다.
  • totalCount가 0보다 크면 응답이 존재합니다.

2. 폼 응답 목록 조회

curl -X GET "https://app.walla.my/open-api/v1/forms/{formId}/responses?page=1&limit=50" \  -H "X-WALLA-API-KEY: your_api_key"```  
  
### 3. 특정 응답 조회  
  
```bash  
curl -X GET "https://app.walla.my/open-api/v1/forms/{formId}/responses/{responseId}" \  -H "X-WALLA-API-KEY: your_api_key"```  
  
### 4. customerKey로 응답 필터링  
  
```bash  
curl -X GET "https://app.walla.my/open-api/v1/forms/{formId}/responses?customerKey=customer_001" \  -H "X-WALLA-API-KEY: your_api_key"```  
  
### 5. Form Delivery로 설문 발송  
  
```bash  
curl -X POST "https://app.walla.my/open-api/v1/forms/{formId}/delivery" \  -H "X-WALLA-API-KEY: your_api_key" \  -H "Content-Type: application/json" \  -d '{    "recipients": [      {        "customerKey": "customer_001",        "email": "user@example.com"      }    ],    "subject": "고객 만족도 조사",  
    "message": "소중한 의견을 남겨주세요."  
  }'```

Field Type

TypeName
RADIO객관식
CHECKBOX객관식 (다중선택)
PICTURE_CHOICE사진선택
DROPDOWN드롭다운
LINEAR선형배율
RADIO_GRID객관식 표
CHECKBOX_GRID객관식 표 (다중선택)
PRIVACY_POLICY_INFORMATION개인정보 수집
SHORT_TEXT단답형
LONG_TEXT장문형
NUMBER숫자
TABLE표
SECRETS비밀 정보 입력
DESCRIPTION설명
WEBSITE_LINK임베딩
DATE날짜
TIME시간
EMAIL이메일
ADDRESS주소
PHONE_NUMBER전화번호
FILE_UPLOAD파일 업로드
IMAGE_UPLOAD사진 촬영
VIDEO_UPLOAD영상 촬영
GEOLOCATION위치기록
TOSS_PAYMENTS토스 페이먼츠
REJECT탈락
ENDING_DESCRIPTION엔딩필드 (종료페이지)
ENDING_REDIRECT엔딩필드 (URL로 이동)
SUBMIT제출하기

자동화 (웹훅)

자동화는 사용자가 만든 폼에 응답이 제출되는 순간, 외부 서비스(웹훅, Slack, Discord, Gmail 등)로 데이터를 즉시 전송해주는 기능입니다.

응답 자동으로 삭제하기

개인정보처럼 일정 기간이 지나면 폐기해야 하는 데이터는 응답 자동 삭제 기능을 이용해 설정한 기간 이후 자동으로 삭제할 수 있어요. 별도로 일일이 관리하지 않아도, 법적 기준에 따라 안전하게 데이터가 파기됩니다.

목차

Walla Open API 가이드버전 정보API 인증 설정API 키 발급인증 방식기본 URLAPI 엔드포인트워크스페이스워크스페이스 목록 조회워크스페이스 상세 조회폼 (프로젝트)전체 폼 목록 조회워크스페이스 내 폼 목록 조회폼 상세 조회필드폼 필드 목록 조회필드 상세 조회필드 출력 스키마 조회응답 데이터응답 목록 조회단일 응답 조회Form Delivery (발송)폼 발송수신인 목록 조회수신인 상태 조회응답 데이터 구조필드 타입별 응답 값 형식히든 필드customerKey에러 응답사용 예시1. customerKey를 활용한 응답 연동 시나리오2. 폼 응답 목록 조회Field Type