휴대폰 인증 API를
계약 없이 붙여요.

휴대폰 인증 API는 무엇을 확인하나요?

sendwich의 휴대폰 인증 API는 번호의 점유를 확인해요. 그 번호가 적힌 휴대폰을 지금 쓰고 있는 사람이 맞는지를, 사용자가 직접 보낸 문자의 발신 번호로 확인하는 방식이에요.

두 가지 인증 모드

• discover — 번호를 모르는 상태에서 시작해요. 인증이 끝나면 확인된 번호를 응답으로 받아요.
• match — 이미 알고 있는 번호를 넣고, 그 번호에서 온 문자일 때만 인증을 완료해요.

연동은 세 단계로 끝나요.

1. 인증 생성 — 서버에서 인증을 만들고, 응답에 담긴 보낼 문자와 받는 번호를 사용자에게 보여줘요.
2. 사용자가 문자 발송 — 사용자가 자기 휴대폰의 문자 앱에서 그 내용을 그대로 보내요. PC라면 인증 창의 QR 코드로 휴대폰에 이어져요.
3. 결과 확인 — 인증을 조회하거나 웹훅을 받아 확인된 번호를 서비스 계정에 연결해요.

인증 화면을 직접 만들지 않아도 돼요. 응답의 verification_url을 열면 준비된 인증 창이 문자 안내부터 완료 화면까지 처리해요.

코드로 보면 이렇게 생겼어요.

인증을 만들면 사용자가 보낼 문자(sms_text)와 받는 번호(destination)가 함께 돌아와요. 이 두 값을 화면에 그대로 안내하면 돼요.

curl https://api.sendwich.kr/v1/verifications \
  -H "Authorization: Bearer YOUR_LIVE_SECRET_KEY" \
  -H "Idempotency-Key: attempt_93a7_create" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "discover", "client_reference": "attempt_93a7" }'

# 201 Created
# { "id": "vrf_EXAMPLE",
#   "status": "pending",
#   "destination": "16661629",
#   "sms_text": "하늘바다",
#   "expires_at": "2026-09-16T03:05:00.000Z" }

사용자가 문자를 보내면 상태가 verified로 바뀌고, 확인된 번호가 채워져요.

curl https://api.sendwich.kr/v1/verifications/vrf_EXAMPLE \
  -H "Authorization: Bearer YOUR_LIVE_SECRET_KEY"

# 200 OK
# { "id": "vrf_EXAMPLE",
#   "status": "verified",
#   "phone": "+821012345678",
#   "verified_at": "2026-09-16T03:01:12.000Z" }

결과는 조회하거나 웹훅으로 받아요.

짧은 인증 흐름이라면 조회로 충분하고, 사용자가 화면을 떠난 뒤에도 결과를 처리해야 한다면 웹훅이 편해요. 웹훅은 서명 헤더로 발신자를 검증하고, 같은 이벤트가 두 번 도착할 수 있으니 인증 ID 기준으로 중복을 걸러요.

Node.js와 Python 서버에서 인증을 만들고 조회하는 예제, 서명 검증 예제를 문서에 준비해 두었어요.

요금과 한도

Free 요금제는 월 기본료와 API 호출 건당 요금이 모두 0원이에요. Free의 월 API 호출 제공량은 10,000건이에요. 카드 등록이나 계약, 심사 없이 회원가입만으로 API 키를 받을 수 있어요.

인증 화면의 템플릿과 색상을 바꾸거나 내 로고를 넣고 싶다면 Plus를 선택할 수 있어요.