# 문자 발신번호 목록 (/docs/api/sendernumbers/listSenderNumbers) **GET /v1/accounts/{accountId}/sender-numbers** ```json { "operationId": "listSenderNumbers", "summary": "문자 발신번호 목록", "description": "문자 발송에 쓸 수 있도록 등록된 발신번호와, 등록하지 않았지만 유예 기간이라 아직 쓸 수 있는 번호,\n070번호·대표번호 회선 수 한도를 함께 돌려줍니다.\n\n발신번호 범위를 지정한 API 키로 호출하면 그 범위 안의 번호만 보입니다.", "tags": [ "SenderNumbers" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "계정 ID", "example": "AC1a2b3c4d" } ], "responses": { "200": { "description": "발신번호 목록", "content": { "application/json": { "schema": { "type": "object", "required": [ "senderNumbers", "grace", "limit" ], "properties": { "senderNumbers": { "type": "array", "description": "등록된 발신번호(승인·승인 대기), 최근 등록 순", "items": { "type": "object", "required": [ "id", "number", "type", "verificationMethod", "status", "createdAt" ], "properties": { "id": { "type": "string", "description": "발신번호 id. 삭제할 때 씁니다.", "example": "cmh1sn0000001" }, "number": { "type": "string", "description": "발신번호(숫자만)", "example": "07052361008" }, "type": { "type": "string", "enum": [ "070", "representative", "mobile" ], "description": "번호 유형. representative=대표번호, mobile=이동전화", "example": "070" }, "verificationMethod": { "type": "string", "enum": [ "own_provisioned", "identity_verified", "usage_cert_ars" ], "description": "등록할 때 거친 확인 방법. own_provisioned=한국AI통신에서 개통한 번호, identity_verified=본인확인한 이동전화번호, usage_cert_ars=다른 통신사업자 대표번호(이용증명원·ARS 심사)", "example": "own_provisioned" }, "status": { "type": "string", "enum": [ "pending", "approved" ], "description": "approved=발송에 쓸 수 있음, pending=승인 대기", "example": "approved" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-10-20T07:02:11.000Z" } } } }, "grace": { "type": "array", "description": "등록하지 않았지만 유예 기간이라 아직 발송에 쓸 수 있는 번호", "items": { "type": "object", "required": [ "number", "expiresAt" ], "description": "등록하지 않았지만 유예 기간이라 만료 시각 전까지 발송에 쓸 수 있는 번호", "properties": { "number": { "type": "string", "example": "07052753809" }, "expiresAt": { "type": "string", "format": "date-time", "description": "이 시각이 지나면 등록하지 않은 이 번호로는 문자를 보낼 수 없습니다.", "example": "2026-11-03T14:59:59.000Z" } } } }, "limit": { "type": "object", "nullable": true, "required": [ "used", "limit", "reached" ], "description": "070번호·대표번호 발신번호 회선 수 한도. 계정이 아니라 명의(개인은 본인확인 정보, 법인은 사업자등록번호) 기준으로, 같은 명의의 다른 계정에 등록한 번호도 함께 셉니다. 명의를 확인할 수 없으면 null 입니다. 관리번호(최종이용자에게 배정한 번호)는 최종이용자 명의로 따로 세므로 이 값에 들지 않습니다.", "properties": { "used": { "type": "integer", "description": "이 명의로 등록한 070번호·대표번호 회선 수(승인 대기 포함)", "example": 2 }, "limit": { "type": "integer", "nullable": true, "description": "등록할 수 있는 회선 수. null 이면 아직 정해지지 않았습니다(법인 종사자 수 증빙 전).", "example": 3 }, "reached": { "type": "boolean", "description": "true 이면 더 등록할 수 없습니다.", "example": false } } } } } } } }, "401": { "description": "인증 실패", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "사람이 읽을 수 있는 에러 메시지" }, "code": { "type": "string", "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n 해제해야 발신됩니다.\n - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)", "example": "recipient_blocked" }, "ip": { "type": "string", "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.", "example": "52.79.213.41" }, "processedAt": { "type": "string", "format": "date-time", "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.", "example": "2026-10-21T04:10:34.303Z" }, "blockers": { "type": "array", "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.", "items": { "type": "object", "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |", "properties": { "number": { "type": "string", "description": "422 응답의 blockers 에만 있다", "example": "07012340002" }, "code": { "type": "string", "enum": [ "number_not_owned", "number_not_carrier_issued", "business_info_incomplete", "identity_unverified", "account_restricted", "business_recheck_pending", "holder_is_personal" ], "example": "number_not_carrier_issued" }, "message": { "type": "string", "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다." } }, "required": [ "code", "message" ] } } } } } } }, "403": { "description": "접근 권한 없음", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "사람이 읽을 수 있는 에러 메시지" }, "code": { "type": "string", "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n 해제해야 발신됩니다.\n - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)", "example": "recipient_blocked" }, "ip": { "type": "string", "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.", "example": "52.79.213.41" }, "processedAt": { "type": "string", "format": "date-time", "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.", "example": "2026-10-21T04:10:34.303Z" }, "blockers": { "type": "array", "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.", "items": { "type": "object", "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |", "properties": { "number": { "type": "string", "description": "422 응답의 blockers 에만 있다", "example": "07012340002" }, "code": { "type": "string", "enum": [ "number_not_owned", "number_not_carrier_issued", "business_info_incomplete", "identity_unverified", "account_restricted", "business_recheck_pending", "holder_is_personal" ], "example": "number_not_carrier_issued" }, "message": { "type": "string", "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다." } }, "required": [ "code", "message" ] } } } } } } } } } ```