---
title: "Cancel Number"
method: POST
path: "/v1/numbers/cancel"
tags: ["numbers"]
---

# Cancel Number

`POST /v1/numbers/cancel`

## Query parameters

- `phone_number` string, required

## Response `200`

Successful Response

- PhoneNumber
  - `id` string, uuid, required
  - `user_id` string, uuid, required
  - `active` boolean
  - `label` string
  - `inbound_agent` Agent
    - `id` string, uuid, required
    - `user_id` string, uuid, required
    - `name` string, nullable
    - `prompt` Prompt, required
      - `id` string, uuid, required
      - `user_id` string, uuid, required
      - `content` string
      - `collect_fields` CollectField[], nullable
        - `field_type` 'field_type_email', required
        - `label` string, required
        - `name` string, required
        - `description` string, nullable
      - `context_endpoint` string, nullable
      - `prompt_template` PromptTemplate
        - `id` string, uuid, required
        - `user_id` string, uuid, required
        - `label` string
        - `required_context_keys` string[], required
    - `language` 'en' | 'es' | 'de' | 'hi' | 'pt' | 'fr' | 'nl' | 'id' | 'it' | 'ja' | 'ko'
    - `actions` union[], required
      - union
        - TransferCallAction
          - `id` string, uuid, required
          - `user_id` string, uuid, required
          - `type` 'action_transfer_call', required
          - `config` TransferCallConfig, required
            - `phone_number` string, required
          - `action_trigger` union
            - FunctionCallActionTrigger
              - …
            - PhraseBasedActionTriggerOutput
              - …
        - EndConversationAction
          - `id` string, uuid, required
          - `user_id` string, uuid, required
          - `type` 'action_end_conversation', required
          - `config` EmptyActionConfig
          - `action_trigger` union
            - FunctionCallActionTrigger
              - …
            - PhraseBasedActionTriggerOutput
              - …
        - DTMFAction
          - `id` string, uuid, required
          - `user_id` string, uuid, required
          - `type` 'action_dtmf', required
          - `config` EmptyActionConfig
          - `action_trigger` FunctionCallActionTrigger
            - `type` 'action_trigger_function_call', required
            - `config` FunctionCallActionTriggerConfig
        - AddToConferenceAction
          - `id` string, uuid, required
          - `user_id` string, uuid, required
          - `type` 'action_add_to_conference', required
          - `config` AddToConferenceConfig, required
            - `phone_number` string, required
            - `place_primary_on_hold` boolean
          - `action_trigger` union
            - FunctionCallActionTrigger
              - …
            - PhraseBasedActionTriggerOutput
              - …
        - SetHoldAction
          - `id` string, uuid, required
          - `user_id` string, uuid, required
          - `type` 'action_set_hold', required
          - `config` EmptyActionConfig
          - `action_trigger` union
            - FunctionCallActionTrigger
              - …
            - PhraseBasedActionTriggerOutput
              - …
        - ExternalAction
          - `id` string, uuid, required
          - `user_id` string, uuid, required
          - `type` 'action_external', required
          - `config` ExternalActionConfig, required
            - `processing_mode` 'muted'
            - `name` string, required
            - `description` string, required
            - `url` string, required
            - `input_schema` object, required
            - `speak_on_send` boolean, required
            - `speak_on_receive` boolean, required
            - `signature_secret` string
          - `action_trigger` FunctionCallActionTrigger
            - `type` 'action_trigger_function_call', required
            - `config` FunctionCallActionTriggerConfig
    - `voice` union, required
      - AzureVoice
        - `id` string, uuid, required
        - `user_id` string, uuid, required
        - `type` 'voice_azure', required
        - `voice_name` string, required
        - `pitch` integer
        - `rate` integer
      - RimeVoice
        - `id` string, uuid, required
        - `user_id` string, uuid, required
        - `type` 'voice_rime', required
        - `speaker` string, required
        - `speed_alpha` number, nullable
        - `model_id` union
          - 'mist' | 'v1'
          - Undefined
      - ElevenLabsVoice
        - `id` string, uuid, required
        - `user_id` string, uuid, required
        - `type` 'voice_eleven_labs', required
        - `voice_id` string, required
        - `stability` number, nullable
        - `similarity_boost` number, nullable
        - `api_key` string, nullable
        - `optimize_streaming_latency` integer, nullable
        - `model_id` string, nullable
        - `experimental_input_streaming` boolean
      - PlayHtVoice
        - `id` string, uuid, required
        - `user_id` string, uuid, required
        - `type` 'voice_play_ht', required
        - `voice_id` string, required
        - `api_user_id` string, nullable
        - `api_key` string, nullable
        - `version` '1' | '2'
        - `speed` number, nullable
        - `quality` 'faster' | 'draft' | 'low' | 'medium' | 'high' | 'premium', nullable
        - `temperature` number, nullable
        - `top_p` number, nullable
        - `text_guidance` number, nullable
        - `voice_guidance` number, nullable
        - `experimental_remove_silence` boolean
      - VocodeVoice
        - `id` string, uuid, required
        - `user_id` string, uuid, required
        - `type` 'voice_vocode', required
        - `voice_id` 'joe', required
    - `initial_message` string, nullable
    - `webhook` Webhook
      - `id` string, uuid, required
      - `user_id` string, uuid, required
      - `subscriptions` EventType[], required
      - `url` string, required
      - `method` 'GET' | 'POST'
    - `vector_database` PineconeVectorDatabase
      - `id` string, uuid, required
      - `user_id` string, uuid, required
      - `type` 'vector_database_pinecone', required
      - `index` string, required
      - `api_key` string, required
      - `api_environment` string, required
    - `interrupt_sensitivity` 'low' | 'high'
    - `context_endpoint` string, nullable
    - `noise_suppression` boolean
    - `endpointing_sensitivity` 'auto' | 'relaxed' | 'sensitive'
    - `ivr_navigation_mode` 'default' | 'off'
    - `conversation_speed` number
    - `initial_message_delay` number
    - `openai_model_name_override` string, nullable
    - `ask_if_human_present_on_idle` boolean
    - `openai_account_connection` OpenAIAccountConnection
      - `id` string, uuid, required
      - `user_id` string, uuid, required
      - `credentials` OpenAICredentials, required
        - `openai_api_key` string, required
      - `type` 'account_connection_openai', required
    - `run_do_not_call_detection` boolean
    - `llm_fallback` InternalLLMFallback
      - `provider` 'openai' | 'azure', required
      - `model_name` string, required
    - `deepgram_keywords` object, nullable
    - `idle_time_seconds` integer, nullable
    - `llm_temperature` number
  - `outbound_only` boolean
  - `example_context` object, nullable
  - `number` string, required
  - `telephony_provider` 'vonage' | 'twilio'
  - `telephony_account_connection` TwilioAccountConnection
    - `id` string, uuid, required
    - `user_id` string, uuid, required
    - `credentials` TwilioCredentials, required
      - `twilio_account_sid` string, required
      - `twilio_auth_token` string, required
    - `type` 'account_connection_twilio', required
    - `steering_pool` string[]
    - `account_supports_any_caller_id` boolean

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/vocodedev/apis/vocode-hosted-api.md) · [All operations](https://skmtc.net/vocodedev/apis/vocode-hosted-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vocodedev/vocode-hosted-api/versions/ffca17c004e2/schema)