> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.claw-ops.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.claw-ops.com/_mcp/server.

# 인증 시작

POST https://api.claw-ops.com/v2/verifications
Content-Type: application/json

인증 한 건을 만들고 사용자에게 코드를 보냅니다.

**v2 는 경로에 계정 ID 가 없습니다** — 계정은 API 키가 정합니다. 요청·응답 필드는 모두
camelCase 입니다.

```json
{ "to": "01012345678", "channel": "sms" }
```

### 재발송은 같은 요청을 한 번 더 부르는 것입니다

같은 번호로 다시 부르면 **새 건이 생기고 앞 건도 살아 있습니다.** 둘 중 어느 코드로든
통과하며, 하나가 통과하면 나머지는 자동으로 `canceled` 가 됩니다. 진행 중인 건이 있다고
거절하지 않습니다 — 문자를 못 받은 사용자가 만료를 기다리는 것 말고 방법이 없어지기
때문입니다.

제어는 한도가 합니다. 직전 건 생성 후 **60초** 안에 다시 부르면 `429` 이고,
같은 번호로 시간당 5건·하루 10건·동시 5건까지입니다.

### 코드는 응답에 실리지 않습니다

코드가 사용자에게 가는 경로는 문자 본문 하나뿐이고, 저장도 해시로만 합니다.

Reference: https://docs.claw-ops.com/api-reference/claw-ops-api/verifications/create-verification

## Authentication

- `Authorization` header (bearer token, required) — API Key를 Bearer 토큰으로 전달

## Request

### Body (application/json)

This endpoint expects an object.

- `to` (string, required) — 인증 대상 번호. 문자 API 와 같은 정규화 규칙을 씁니다 — 국내 표기와 `+82` E.164 를 모두 받고, 그 밖의 값은 `400 invalid_phone` 입니다.
- `channel` (enum, required) — 인증 방식. - `sms` — 코드를 문자로 보냅니다. - `call` — 전화를 걸어 코드를 두 번 읽어 줍니다. 받지 않거나 통화가 실패하면 그 건은 `failed` 로 닫히고 **다시 걸지 않습니다.** 미응답은 통화료가 붙지 않습니다(과금 원점이 응답 시각입니다). 둘 다 사용자가 듣거나 읽은 코드를 `check` 로 대조합니다 — **호출 방법이 같습니다.** 계약에는 `sms_inbound`(사용자가 문자를 보냄)·`call_inbound` (사용자가 전화를 검)도 정의돼 있으며 순차로 열립니다.
  - Allowed values: `sms`, `call`
- `from` (string, optional) — 발신에 쓸 **계정 보유 번호**. 생략하면 계정 번호 중 하나를 고릅니다. 계정에 번호가 하나도 없으면 `422 no_number` 이고, 다른 계정의 번호를 주면 `400 from_not_owned` 입니다.
- `codeLength` (integer, optional, default: 6) — 코드 자릿수. 숫자만 쓰며 앞자리 0 이 올 수 있습니다.
- `ttlSeconds` (integer, optional, default: 180) — 코드 유효 시간(초).
- `locale` (enum, optional, default: ko) — 문자 문안 언어. 지금은 `ko` 하나입니다 — 값을 먼저 열어 두면 `en` 을 넣고도 한국어 문자를 받는 「있는데 안 되는」 상태가 됩니다. 값을 나중에 더하는 것은 하위호환입니다.
  - Allowed values: `ko`
- `templateVariables` (map from string to string, optional) — 문안에 채울 값. `서비스명` 을 주면 문자 앞에 `[서비스명]` 으로 붙습니다. 코드는 우리가 채우므로 여기 넣지 않습니다.
- `idempotencyKey` (string, optional) — 같은 계정에서 같은 키로 다시 요청하면 **발송하지 않고** 1회차 결과를 그대로 돌려줍니다. 빈 문자열은 `400` 입니다 — 템플릿에서 빈 값이 들어가 멱등이 조용히 꺼지는 걸 막습니다.

## Response

### 201

인증 시작됨

- `verificationId` (string, optional)
- `status` (enum, optional) — - `pending` — 코드를 기다리는 중 - `verified` — 통과. **1회용입니다** — 같은 건을 두 번 소비할 수 없습니다 - `expired` — `ttlSeconds` 가 지남 - `max_attempts` — 대조 5회를 모두 사용 - `canceled` — 취소했거나, 같은 번호의 다른 건이 먼저 통과함 - `failed` — 전달 자체가 실패(문자 발송 실패, 통화 미응답·실패)
  - Allowed values: `pending`, `verified`, `expired`, `max_attempts`, `canceled`, `failed`
- `channel` (enum, optional)
  - Allowed values: `sms`, `call`
- `to` (string, optional)
- `from` (string, optional) — 발신에 쓴 계정 보유 번호.
- `codeLength` (integer, optional)
- `remainingAttempts` (integer, optional) — 남은 대조 횟수. 건당 5회에서 시작합니다.
- `expiresAt` (datetime, optional)
- `createdAt` (datetime, optional)
- `verifiedAt` (datetime, optional, nullable)
- `instruction` (VerificationInstruction, optional, nullable) — 사용자에게 **그대로 보여 줘야 하는 것**. 발신형(`sms`·`call`)은 우리가 사용자에게 코드를 전달하므로 `null` 입니다. 수신형 채널이 열리면 보낼 번호와 문구가 여기 담깁니다.

## Errors

### 400 Bad Request Error

잘못된 요청 (`invalid_phone`·`invalid_input`·`from_not_owned`)

- `error` (string, optional) — 사람이 읽을 수 있는 에러 메시지
- `code` (string, optional) — 기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서 바뀔 수 있지만 코드는 계약입니다. 같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는 - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서 해제해야 발신됩니다. - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다. 전화번호 정규화 관련: - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님) - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)
- `ip` (string, optional) — `overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다. 해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔 「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.

### 401 Unauthorized Error

인증 실패

- `error` (string, optional) — 사람이 읽을 수 있는 에러 메시지
- `code` (string, optional) — 기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서 바뀔 수 있지만 코드는 계약입니다. 같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는 - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서 해제해야 발신됩니다. - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다. 전화번호 정규화 관련: - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님) - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)
- `ip` (string, optional) — `overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다. 해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔 「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.

### 403 Forbidden Error

접근 권한 없음, 또는 국외 IP 에서의 문자 발송 (`overseas_ip_blocked`)

- `error` (string, optional) — 사람이 읽을 수 있는 에러 메시지
- `code` (string, optional) — 기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서 바뀔 수 있지만 코드는 계약입니다. 같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는 - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서 해제해야 발신됩니다. - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다. 전화번호 정규화 관련: - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님) - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)
- `ip` (string, optional) — `overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다. 해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔 「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.

### 422 Unprocessable Entity Error

계정에 쓸 수 있는 번호가 없음 (`no_number`). 수신형 채널은 번호가 먼저 있어야 합니다. 이미 쓴 `idempotencyKey` 를 **다른 요청**(다른 `to`·`channel`)에 다시 쓰면 `idempotency_key_reused` 입니다 — 그대로 1회차 건을 돌려주면 문자는 안 나갔는데 응답의 `to` 만 옛 번호인 상태를 호출자가 알아챌 방법이 없습니다.

- `error` (string, optional) — 사람이 읽을 수 있는 에러 메시지
- `code` (string, optional) — 기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서 바뀔 수 있지만 코드는 계약입니다. 같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는 - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서 해제해야 발신됩니다. - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다. 전화번호 정규화 관련: - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님) - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)
- `ip` (string, optional) — `overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다. 해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔 「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.

### 429 Too Many Requests Error

한도 초과 또는 쿨다운 중 (`rate_limited`). `Retry-After` 헤더의 초가 지난 뒤 다시 부르세요.

- `error` (string, optional) — 사람이 읽을 수 있는 에러 메시지
- `code` (string, optional) — 기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서 바뀔 수 있지만 코드는 계약입니다. 같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는 - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서 해제해야 발신됩니다. - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다. 전화번호 정규화 관련: - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님) - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)
- `ip` (string, optional) — `overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다. 해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔 「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.

### 502 Bad Gateway Error

전달하지 못함 (`send_failed`) — `sms` 는 문자 발송, `call` 은 발신 자체가 실패한 경우입니다. 그 건은 `failed` 로 닫힙니다.

- `error` (string, optional) — 사람이 읽을 수 있는 에러 메시지
- `code` (string, optional) — 기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서 바뀔 수 있지만 코드는 계약입니다. 같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는 - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서 해제해야 발신됩니다. - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다. 전화번호 정규화 관련: - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님) - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)
- `ip` (string, optional) — `overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다. 해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔 「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.

### 503 Service Unavailable Error

그 채널이 이 배포에 열려 있지 않음 (`channel_unavailable`). 그 건은 `failed` 로 닫힙니다. 다른 채널로 다시 부르세요.

- `error` (string, optional) — 사람이 읽을 수 있는 에러 메시지
- `code` (string, optional) — 기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서 바뀔 수 있지만 코드는 계약입니다. 같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는 - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서 해제해야 발신됩니다. - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다. 전화번호 정규화 관련: - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님) - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)
- `ip` (string, optional) — `overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다. 해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔 「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.

## Types

### VerificationInstruction

사용자에게 **그대로 보여 줘야 하는 것**. 발신형(`sms`·`call`)은 우리가 사용자에게 코드를 전달하므로 `null` 입니다. 수신형 채널이 열리면 보낼 번호와 문구가 여기 담깁니다.

- `type` (string, optional)
- `sendTo` (string, optional)
- `body` (string, optional)
- `callTo` (string, optional)
- `code` (string, optional)
- `deadline` (datetime, optional)

## Examples

**Request**

```json
{
  "to": "01012345678",
  "channel": "sms"
}
```

**Response**

```json
{
  "verificationId": "VE1a2b3c4d5e6f7a8b",
  "status": "pending",
  "channel": "sms",
  "to": "01012345678",
  "from": "07052358010",
  "codeLength": 6,
  "remainingAttempts": 5,
  "expiresAt": "2024-01-15T09:30:00Z",
  "createdAt": "2024-01-15T09:30:00Z",
  "verifiedAt": "2024-01-15T09:30:00Z",
  "instruction": {
    "type": "string",
    "sendTo": "string",
    "body": "string",
    "callTo": "string",
    "code": "string",
    "deadline": "2024-01-15T09:30:00Z"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.claw-ops.com/v2/verifications"

payload = {
    "to": "01012345678",
    "channel": "sms"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.claw-ops.com/v2/verifications';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"to":"01012345678","channel":"sms"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.claw-ops.com/v2/verifications"

	payload := strings.NewReader("{\n  \"to\": \"01012345678\",\n  \"channel\": \"sms\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.claw-ops.com/v2/verifications")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"to\": \"01012345678\",\n  \"channel\": \"sms\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.claw-ops.com/v2/verifications")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"to\": \"01012345678\",\n  \"channel\": \"sms\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.claw-ops.com/v2/verifications', [
  'body' => '{
  "to": "01012345678",
  "channel": "sms"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.claw-ops.com/v2/verifications");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"to\": \"01012345678\",\n  \"channel\": \"sms\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "to": "01012345678",
  "channel": "sms"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.claw-ops.com/v2/verifications")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```