> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt > Use this file to discover all available pages before exploring further. # 차단 번호 일괄 생성 > 한 요청으로 차단 번호 규칙을 최대 500건까지 생성합니다. 각 번호는 독립적으로 처리되며, 실패 항목은 성공 항목을 되돌리지 않고 `results`에 보고됩니다. 중복 규칙은 `skipped`로 반환되며, 기존 규칙 교체는 지원하지 않습니다. ## OpenAPI ````yaml /api-reference/v3/openapi.json post /blocked-numbers/bulk openapi: 3.1.0 info: title: vox.ai API description: > vox.ai API v3 ### v3 공개 계약 규칙 - 인증은 `Authorization: Bearer ` 헤더를 사용합니다. 조직 API 키를 Bearer 토큰으로 전달합니다. - 요청과 응답 필드는 기본적으로 `snake_case`를 사용합니다. - `agent.data`는 에이전트 레지스트리와 호환되어야 하므로 `callSettings`, `toolIds`, `builtInTools`, `presetDynamicVariables` 같은 camelCase 필드를 유지합니다. - `_at`으로 끝나는 타임스탬프는 unix milliseconds입니다. 일부 입력값은 호환성을 위해 10~11자리 unix seconds도 허용하고 milliseconds로 정규화합니다. - 캠페인 통화 가능 시간은 분 단위 정수(`start_min` / `end_min`)를 사용합니다. 알림 스케줄은 `HH:MM` 문자열(`start_time` / `end_time`)을 사용합니다. - 응답 객체 자신의 식별자는 `id`입니다. 다른 리소스를 참조하는 필드와 path parameter는 `agent_id`, `call_id`, `telephone_line_id`처럼 명시적인 이름을 사용합니다. - 실패 응답은 `{ "error": { "code", "message", "details" } }` 형태입니다. 가능한 경우 `details.field`, `details.reason`, `details.allowed_values`를 함께 제공합니다. version: 3.0.0 servers: - url: https://client-api.tryvox.co/v3 description: 운영 security: [] paths: /blocked-numbers/bulk: post: tags: - Blocked Numbers summary: 차단 번호 일괄 생성 description: >- 한 요청으로 차단 번호 규칙을 최대 500건까지 생성합니다. 각 번호는 독립적으로 처리되며, 실패 항목은 성공 항목을 되돌리지 않고 `results`에 보고됩니다. 중복 규칙은 `skipped`로 반환되며, 기존 규칙 교체는 지원하지 않습니다. operationId: bulkCreateBlockedNumbers requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkCreateBlockedNumbersRequest' required: true description: 일괄 생성할 번호와 공통 규칙 설정입니다. responses: '200': description: 성공 응답 content: application/json: schema: $ref: '#/components/schemas/BulkCreateBlockedNumbersResponse' '400': description: 요청 검증 오류 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationError: summary: 요청 검증 오류 value: error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank '401': description: 인증이 필요합니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Bearer 토큰 누락 또는 오류 value: error: code: UNAUTHORIZED message: Authentication is required. details: {} '403': description: 권한이 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: 권한이 없습니다. value: error: code: FORBIDDEN message: Permission denied. details: {} '404': description: 리소스를 찾을 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: 리소스를 찾을 수 없습니다. value: error: code: RESOURCE_NOT_FOUND message: Resource not found. details: resource: agent '409': description: 충돌이 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conflict: summary: 상태 충돌이 발생했습니다. value: error: code: CONFLICT message: The requested operation conflicts with current state. details: current_status: draft '429': description: 요청 한도를 초과했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: summary: 요청 한도를 초과했습니다. value: error: code: RATE_LIMIT_EXCEEDED message: Too many requests. details: limit: 5 window_seconds: 1 '500': description: 서버 내부 오류가 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: 서버 내부 오류가 발생했습니다. value: error: code: INTERNAL_ERROR message: Internal server error. details: {} '503': description: 서비스를 일시적으로 사용할 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: serviceUnavailable: summary: 서비스를 일시적으로 사용할 수 없습니다. value: error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. details: {} security: - BearerAuth: [] components: schemas: BulkCreateBlockedNumbersRequest: properties: numbers: items: type: string type: array maxItems: 500 minItems: 1 title: Numbers description: 차단할 전화번호 목록입니다. 한 요청에 최대 500건까지 지정할 수 있습니다. scope: $ref: '#/components/schemas/BlockedNumberScope' description: 모든 입력 번호에 공통으로 적용할 차단 범위입니다. specific_organization_telephone_ids: items: type: string format: uuid type: array title: Specific Organization Telephone Ids description: scope가 'specific'일 때 규칙이 적용되는 보유 전화번호 ID 목록입니다. 'global'이면 빈 배열입니다. direction: $ref: '#/components/schemas/BlockedNumberDirection' description: >- 모든 입력 번호에 공통으로 적용할 통화 방향입니다. inbound는 수신, outbound는 발신, both는 양방향입니다. default: both memo: anyOf: - type: string maxLength: 500 - type: 'null' title: Memo description: 모든 생성 규칙에 공통으로 적용할 메모입니다. 최대 500자. is_active: type: boolean title: Is Active description: 생성된 규칙을 현재 차단 판정에 적용할지 여부입니다. default: true type: object required: - numbers - scope title: BulkCreateBlockedNumbersRequest BulkCreateBlockedNumbersResponse: properties: results: items: $ref: '#/components/schemas/BulkBlockedNumberResultResponse' type: array title: Results description: 입력 번호별 독립 처리 결과입니다. type: object required: - results title: BulkCreateBlockedNumbersResponse ErrorResponse: type: object required: - error title: ErrorResponse description: 모든 실패 응답에서 사용하는 v3 error envelope입니다. examples: - error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: error: $ref: '#/components/schemas/ErrorDetail' description: 오류 payload입니다. BlockedNumberScope: type: string enum: - global - specific title: BlockedNumberScope description: >- 차단 번호의 적용 범위. - `global` : 조직 전체에 적용 (모든 보유 전화번호에서 차단). - `specific` : 특정 보유 전화번호 한정 — `specific_organization_telephone_ids` 로 명시한 번호에서만 차단. BlockedNumberDirection: type: string enum: - inbound - outbound - both title: BlockedNumberDirection description: |- 차단 번호가 차단할 통화 방향. - `inbound` : 해당 번호로부터 걸려오는 통화만 차단. - `outbound` : 해당 번호로 거는 통화만 차단. - `both` : 양방향 모두 차단 (기본값). BulkBlockedNumberResultResponse: properties: input_number: type: string title: Input Number description: 요청에 포함된 원본 입력 번호입니다. normalized_number: anyOf: - type: string - type: 'null' title: Normalized Number description: 정규화된 번호입니다. 유효하지 않으면 null입니다. status: type: string enum: - created - skipped - invalid title: Status description: 처리 상태입니다. created는 생성, skipped는 중복 건너뜀, invalid는 유효성 검증 실패를 뜻합니다. blocked_number: anyOf: - $ref: '#/components/schemas/BlockedNumberResponse' - type: 'null' description: 생성된 차단 규칙입니다. 실패 시 null입니다. reason: anyOf: - type: string - type: 'null' title: Reason description: >- 건너뛰거나 거부된 사유 코드입니다. 가능한 값: 'INVALID_PHONE_NUMBER', 'DUPLICATE_INPUT', 'BLOCKED_NUMBER_RULE_ALREADY_EXISTS', 'BLOCKED_NUMBER_GLOBAL_SCOPE_HAS_SPECIFIC_IDS', 'BLOCKED_NUMBER_SPECIFIC_SCOPE_REQUIRES_IDS', 'INVALID_ORGANIZATION_TELEPHONE_ID', 'ORGANIZATION_TELEPHONE_EXPIRED'. created면 null입니다. type: object required: - input_number - status title: BulkBlockedNumberResultResponse ErrorDetail: type: object required: - code - message - details title: ErrorDetail description: 기계가 읽을 수 있는 v3 오류 상세 정보입니다. examples: - code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: code: type: string title: Code description: 기계가 읽을 수 있는 오류 code입니다. message parsing 대신 이 값을 사용합니다. examples: - VALIDATION_ERROR message: type: string title: Message description: 사용자에게 표시할 수 있는 오류 메시지입니다. 프로그램 처리는 `code`를 사용합니다. examples: - Request validation failed. details: type: object title: Details additionalProperties: true description: 구조화된 context입니다. 주로 `field`, `reason`, `allowed_values`를 포함합니다. BlockedNumberResponse: properties: id: type: string format: uuid title: Id description: 차단 규칙 ID입니다. organization_id: type: string format: uuid title: Organization Id description: 차단 번호를 등록한 조직 ID입니다. number: type: string title: Number description: 차단할 전화번호입니다. 하이픈 없는 숫자 문자열로 정규화되어 저장·반환됩니다. scope: $ref: '#/components/schemas/BlockedNumberScope' description: 차단 규칙의 적용 범위입니다. specific_organization_telephone_ids: items: type: string format: uuid type: array title: Specific Organization Telephone Ids description: scope가 'specific'일 때 규칙이 적용되는 보유 전화번호 ID 목록입니다. 'global'이면 빈 배열입니다. direction: $ref: '#/components/schemas/BlockedNumberDirection' description: 차단할 통화 방향입니다. inbound는 수신, outbound는 발신, both는 양방향입니다. memo: anyOf: - type: string - type: 'null' title: Memo description: 규칙에 대한 메모입니다. 최대 500자. is_active: type: boolean title: Is Active description: 현재 차단 판정에 적용되는지 여부입니다. 비활성이면 목록에는 남지만 판정에서 제외됩니다. created_at: type: integer title: Created At description: 리소스 생성 시각입니다. unix milliseconds 형식입니다. updated_at: type: integer title: Updated At description: 리소스 마지막 수정 시각입니다. unix milliseconds 형식입니다. type: object required: - id - organization_id - number - scope - direction - is_active - created_at - updated_at title: BlockedNumberResponse securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: Organization API key description: '조직 API 키를 `Authorization: Bearer ` 형식으로 보냅니다.' ````