# 050 안심번호 착신 변경 (/docs/api/numbers/updateSafetyNumberForwarding)
**PUT /v1/accounts/{accountId}/safety-numbers/{number}/forwarding**
```json
{
  "operationId": "updateSafetyNumberForwarding",
  "summary": "050 안심번호 착신 변경",
  "description": "걸려 온 통화를 보낼 곳을 바꿉니다. 두 가지 방식이 있습니다.\n\n- **`carrier_direct`** 통신사가 `forwardTargets`(휴대전화·지역번호·070, 최대 3개)로 바로 연결합니다.\n- **`platform`** 우리 시스템이 받아 `forwardTo`(내가 보유한 070 또는 대표번호)로 전환합니다. 대표번호로 받으려면 이 방식을 씁니다.\n\n호출할 때마다 방식이 호출한 값으로 바뀝니다(예: `platform` 이던 번호를 `carrier_direct` 로 호출하면 직결로 바뀝니다).\n통신사 반영은 보통 바로 끝나며, 늦어도 5분 안에 반영됩니다. `carrierStatus` 로 확인합니다.\n",
  "tags": [
    "Numbers"
  ],
  "parameters": [
    {
      "name": "accountId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "계정 ID",
      "example": "AC1a2b3c4d"
    },
    {
      "name": "number",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "050 안심번호",
      "example": "050412345678"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "description": "착신 설정. `forwardMode` 에 따라 보내는 값이 다릅니다.\n- `carrier_direct`(기본): `forwardTargets` 가 필요합니다.\n- `platform`: `forwardTo` 가 필요합니다.\n",
          "properties": {
            "forwardMode": {
              "type": "string",
              "enum": [
                "carrier_direct",
                "platform"
              ],
              "default": "carrier_direct",
              "description": "착신 방식.\n- `carrier_direct`: 통신사가 `forwardTargets` 로 바로 연결합니다.\n- `platform`: 우리 시스템이 받아 `forwardTo`(내 070·대표번호)로 전환합니다. 콘솔의 「내 번호로 연결」과 같습니다. 받은 통화에는 전환받는 번호의 수신 요금이 적용됩니다.\n"
            },
            "forwardTargets": {
              "type": "array",
              "maxItems": 3,
              "items": {
                "type": "string"
              },
              "description": "`carrier_direct` 일 때의 착신 번호(국내 9~11자리, 최대 3개). 빈 배열이면 착신을 해제합니다.\n휴대전화·지역번호·070 번호를 쓸 수 있고 내가 보유한 070 도 됩니다. 050·060·080 같은 특수번호는 쓸 수 없고, 대표번호(8자리)는 이 방식으로 넣을 수 없습니다(`platform` 방식을 사용하세요).\n여러 개를 넣으면 앞에서부터 차례로 연결합니다.\n",
              "example": [
                "01012345678"
              ]
            },
            "forwardTo": {
              "type": "string",
              "description": "`platform` 일 때 전환할 번호. 이 계정이 보유한 070 또는 대표번호이어야 합니다. 050 번호끼리는 연결할 수 없습니다.\n그 번호의 받는 설정(웹훅·에이전트·콜 플로우 등)대로 통화를 받습니다.\n",
              "example": "07052753966"
            }
          }
        },
        "examples": {
          "carrierDirect": {
            "summary": "통신사가 내 휴대폰으로 바로 연결",
            "value": {
              "forwardMode": "carrier_direct",
              "forwardTargets": [
                "01012345678"
              ]
            }
          },
          "platform": {
            "summary": "우리 시스템이 받아 내 070 으로 전환",
            "value": {
              "forwardMode": "platform",
              "forwardTo": "07052753966"
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "변경됨",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "description": "050 안심번호 하나. 걸려 온 통화는 통신사가 착신 번호로 바로 연결하거나(carrier_direct), 우리 시스템이 받아 내 070·대표번호로 전환한다(platform).",
            "required": [
              "number",
              "forwardMode",
              "forwardTargets",
              "carrierStatus"
            ],
            "properties": {
              "number": {
                "type": "string",
                "description": "050 안심번호(11~12자리)",
                "example": "050412345678"
              },
              "forwardMode": {
                "type": "string",
                "enum": [
                  "carrier_direct",
                  "platform"
                ],
                "description": "착신 방식.\n- `carrier_direct`: 통신사가 `forwardTargets` 로 바로 연결합니다.\n- `platform`: 우리 시스템이 받아 내 070·대표번호로 전환합니다. `forwardTargets` 에 전환 대상 번호가 하나 나옵니다.\n두 방식 모두 `PUT .../safety-numbers/{number}/forwarding` 으로 바꿀 수 있습니다.\n"
              },
              "forwardTargets": {
                "type": "array",
                "maxItems": 3,
                "items": {
                  "type": "string"
                },
                "description": "착신 번호. `carrier_direct` 이면 통신사가 연결하는 번호(국내 9~11자리, 최대 3개)이고, `platform` 이면 전환 대상인 내 070·대표번호 하나입니다.\n비어 있으면 착신하지 않습니다.\n",
                "example": [
                  "01012345678"
                ]
              },
              "carrierStatus": {
                "type": "string",
                "enum": [
                  "pending",
                  "active",
                  "failed"
                ],
                "description": "통신사 착신 반영 상태. pending = 반영 대기, active = 반영됨, failed = 반영 실패(자동으로 다시 시도합니다)."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "착신 번호 형식 오류(국내 9~11자리가 아니거나 050·060·080 등 특수번호), `platform` 인데 `forwardTo` 가 없거나 이 계정이 보유한 070·대표번호가 아님, 050 끼리 연결",
      "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"
                  ]
                }
              },
              "numbers": {
                "type": "array",
                "description": "`ringback_audio_in_use` 일 때만 옵니다. 그 연결음 음원을 쓰는 번호입니다.",
                "items": {
                  "type": "string"
                },
                "example": [
                  "07012345678"
                ]
              }
            }
          }
        }
      }
    },
    "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"
                  ]
                }
              },
              "numbers": {
                "type": "array",
                "description": "`ringback_audio_in_use` 일 때만 옵니다. 그 연결음 음원을 쓰는 번호입니다.",
                "items": {
                  "type": "string"
                },
                "example": [
                  "07012345678"
                ]
              }
            }
          }
        }
      }
    },
    "404": {
      "description": "이 계정의 050 안심번호가 아님",
      "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"
                  ]
                }
              },
              "numbers": {
                "type": "array",
                "description": "`ringback_audio_in_use` 일 때만 옵니다. 그 연결음 음원을 쓰는 번호입니다.",
                "items": {
                  "type": "string"
                },
                "example": [
                  "07012345678"
                ]
              }
            }
          }
        }
      }
    }
  }
}
```