> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phonely.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update an agent's blocked numbers

> Block and unblock phone numbers, in one change.

Only the numbers sent change, so changes from other callers are kept and no `If-Match` is needed. A number
already blocked, or one that isn't blocked, is ignored, so sending the same request again changes nothing.
Answers with all of the agent's blocked numbers. Applies from the next call.



## OpenAPI

````yaml /api-reference/v1/openapi.json patch /v1/agents/{id}/blocked-numbers
openapi: 3.1.0
info:
  description: >-
    Authenticate every request with an org API key: `Authorization: Bearer
    phk_…`.
  title: Phonely API
  version: '1'
servers:
  - description: US
    url: https://api.us.phonely.ai
  - description: AU
    url: https://api.au.phonely.ai
security: []
paths:
  /v1/agents/{id}/blocked-numbers:
    patch:
      tags:
        - Agents
      summary: Update an agent's blocked numbers
      description: >-
        Block and unblock phone numbers, in one change.


        Only the numbers sent change, so changes from other callers are kept and
        no `If-Match` is needed. A number

        already blocked, or one that isn't blocked, is ignored, so sending the
        same request again changes nothing.

        Answers with all of the agent's blocked numbers. Applies from the next
        call.
      operationId: update_agent_blocked_numbers
      parameters:
        - description: The agent's ID.
          in: path
          name: id
          required: true
          schema:
            description: The agent's ID.
            title: Id
            type: string
        - description: Optional. Must be the key's org.
          in: header
          name: Phonely-Organization
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Optional. Must be the key's org.
            title: Phonely-Organization
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentBlockedNumbersUpdate'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentBlockedNumbers'
          description: Successful Response
          headers:
            Phonely-Organization:
              description: The authorized organization for this request.
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            The request is invalid: a malformed body, a bad or unknown field, or
            an unknown query parameter.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The API key is missing, invalid or revoked.
          headers:
            WWW-Authenticate:
              description: Always `Bearer`.
              schema:
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            The key can't do this: a read-only key writing, or
            `Phonely-Organization` naming another org.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The resource doesn't exist, or belongs to another organization.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Rate limited. Retry after the number of seconds in `Retry-After`.
          headers:
            Retry-After:
              description: Seconds until the request can be retried.
              schema:
                type: integer
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An unexpected error. Contact support with the request ID.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            Authentication, authorization or another required service is
            temporarily unavailable.
      security:
        - HTTPBearer: []
components:
  schemas:
    AgentBlockedNumbersUpdate:
      additionalProperties: false
      description: The numbers to block and unblock. Numbers not sent stay as they are.
      properties:
        add:
          description: >-
            Numbers to block, in E.164, such as `+14155550100`. One already
            blocked stays as it is.
          items:
            pattern: ^\+[1-9]\d{6,14}$
            type: string
          maxItems: 1000
          title: Add
          type: array
        remove:
          description: Numbers to unblock, in E.164. One that isn't blocked is ignored.
          items:
            pattern: ^\+[1-9]\d{6,14}$
            type: string
          maxItems: 1000
          title: Remove
          type: array
      title: AgentBlockedNumbersUpdate
      type: object
    AgentBlockedNumbers:
      additionalProperties: false
      description: The phone numbers an agent refuses calls from.
      properties:
        agent_id:
          description: The agent's ID.
          title: Agent Id
          type: string
        object:
          const: agent_blocked_numbers
          default: agent_blocked_numbers
          description: The type of this object, always `agent_blocked_numbers`.
          title: Object
          type: string
        phone_numbers:
          description: >-
            Calls from these numbers are refused. In E.164, such as
            `+14155550100`, in ascending order.
          items:
            type: string
          title: Phone Numbers
          type: array
      required:
        - object
        - agent_id
        - phone_numbers
      title: AgentBlockedNumbers
      type: object
    ErrorResponse:
      additionalProperties: false
      description: The body of every `/v1` error.
      properties:
        error:
          $ref: '#/components/schemas/Error'
          description: What went wrong.
      required:
        - error
      title: ErrorResponse
      type: object
    Error:
      additionalProperties: false
      properties:
        code:
          description: >-
            What went wrong, stable and machine-readable. Known values:
            `validation_failed`, `invalid_cursor`, `invalid_api_key`,
            `invalid_user_token`, `user_unavailable`, `staff_sign_in_required`,
            `insufficient_access`, `organization_mismatch`, `forbidden`,
            `not_found`, `method_not_allowed`, `conflict`,
            `agent_limit_reached`, `agent_too_large`, `sms_setup_required`,
            `opportunity_analysis_not_set_up`, `precondition_failed`,
            `payload_too_large`, `unsupported_media_type`,
            `precondition_required`, `rate_limited`, `internal_error`,
            `knowledge_processing_failed`, `bad_gateway`, `service_unavailable`,
            `gateway_timeout`. More can be added, so handle values you don't
            recognize.
          title: Code
          type: string
          x-extensible-enum:
            - validation_failed
            - invalid_cursor
            - invalid_api_key
            - invalid_user_token
            - user_unavailable
            - staff_sign_in_required
            - insufficient_access
            - organization_mismatch
            - forbidden
            - not_found
            - method_not_allowed
            - conflict
            - agent_limit_reached
            - agent_too_large
            - sms_setup_required
            - opportunity_analysis_not_set_up
            - precondition_failed
            - payload_too_large
            - unsupported_media_type
            - precondition_required
            - rate_limited
            - internal_error
            - knowledge_processing_failed
            - bad_gateway
            - service_unavailable
            - gateway_timeout
        details:
          description: One entry per problem field. Empty when the error has none.
          items:
            $ref: '#/components/schemas/ErrorDetail'
          title: Details
          type: array
        message:
          description: For people. Wording can change; branch on `code`.
          title: Message
          type: string
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Also in the `X-Request-Id` header. Quote it to support.
          title: Request Id
      required:
        - code
        - message
        - details
        - request_id
      title: Error
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        field:
          description: >-
            The field the issue is about, as sent: `agent_id`, `limit`. Empty
            when none.
          title: Field
          type: string
        issue:
          description: >-
            What is wrong with the field. Known values: `required`,
            `unknown_field`, `invalid_json`, `invalid_type`, `invalid_value`,
            `out_of_range`, `invalid_cursor`, `read_only_field`. More can be
            added, so handle values you don't recognize.
          title: Issue
          type: string
          x-extensible-enum:
            - required
            - unknown_field
            - invalid_json
            - invalid_type
            - invalid_value
            - out_of_range
            - invalid_cursor
            - read_only_field
        message:
          description: 'For people: what is wrong with this field.'
          title: Message
          type: string
      required:
        - field
        - issue
        - message
      title: ErrorDetail
      type: object
  securitySchemes:
    HTTPBearer:
      description: 'An org API key: `Authorization: Bearer phk_…`'
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.