> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getdial.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getdial.ai/_mcp/server.

# Update a phone number

PATCH https://api.getdial.ai/api/v1/numbers/{id}
Content-Type: application/json

Update a number's properties. Send any subset of the fields below — at least one is required; omitted fields are left unchanged. A new `inboundInstruction` takes effect on the next inbound call; in-progress calls are unaffected.

Reference: https://docs.getdial.ai/api-reference/rest-api/phone-numbers/update-number

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: rest
  version: 1.0.0
paths:
  /api/v1/numbers/{id}:
    patch:
      operationId: update-number
      summary: Update a phone number
      description: >-
        Update a number's properties. Send any subset of the fields below — at
        least one is required; omitted fields are left unchanged. A new
        `inboundInstruction` takes effect on the next inbound call; in-progress
        calls are unaffected.
      tags:
        - phoneNumbers
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: 'Your Dial API key, sent as `Authorization: Bearer sk_live_...`'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Phone numbers_updateNumber_Response_200'
        '400':
          description: The request body failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The requested resource was not found on this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                inboundInstruction:
                  type: string
                  description: New inbound voice-agent system prompt for this number.
                inboundVoiceGender:
                  $ref: >-
                    #/components/schemas/ApiV1NumbersIdPatchRequestBodyContentApplicationJsonSchemaInboundVoiceGender
                  description: >-
                    Voice gender for the AI agent on inbound calls to this
                    number. Send null to clear it (the voice reverts to the
                    default, female). Takes effect on the next inbound call.
                inboundLanguage:
                  type:
                    - string
                    - 'null'
                  description: >-
                    BCP-47 language tag for the AI voice agent on inbound calls
                    to this number. Send null to clear it — the language is then
                    detected from the caller's country prefix on each call, with
                    the agent handling both that language and `en-US`. Takes
                    effect on the next inbound call.
                nickname:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Human-readable label for the number. Trimmed; at most 100
                    characters. Send null or an empty string to clear it.
                maxCallDurationSeconds:
                  type:
                    - integer
                    - 'null'
                  description: >-
                    Cap on the length of calls on this number, in seconds, for
                    both inbound calls to the number and outbound calls placed
                    from it. The effective cap on a call is the first one set in
                    priority order — the per-call cap, then this number cap,
                    then the account cap — falling back to the global default.
                    This number cap overrides the account cap (raising or
                    lowering the limit) but is itself overridden by a per-call
                    cap. Must be between 60 and 3600 seconds (1 minute to 1
                    hour); a value outside that range returns 400. Send null to
                    clear it (falls back to the account cap or global default).
                    When a cap is active, Dial automatically injects a warning
                    to the agent ~40 seconds before the hard cut, prompting it
                    to wrap up naturally.
servers:
  - url: https://api.getdial.ai
    description: Dial REST API
components:
  schemas:
    ApiV1NumbersIdPatchRequestBodyContentApplicationJsonSchemaInboundVoiceGender:
      type: string
      enum:
        - male
        - female
      description: >-
        Voice gender for the AI agent on inbound calls to this number. Send null
        to clear it (the voice reverts to the default, female). Takes effect on
        the next inbound call.
      title: >-
        ApiV1NumbersIdPatchRequestBodyContentApplicationJsonSchemaInboundVoiceGender
    PhoneNumberCapabilitiesItems:
      type: string
      enum:
        - sms
        - call
        - imessage
      title: PhoneNumberCapabilitiesItems
    PhoneNumberSetupStatus:
      type: string
      enum:
        - provisioning
        - ready
        - failed
      description: >-
        Whether the number is ready to use. An SMS/call number is always
        `ready`. An `imessage` number is `provisioning` while it's being set up
        and only becomes usable for sending or calling once `ready` (`failed` on
        a setup error). Poll List phone numbers to await `ready`.
      title: PhoneNumberSetupStatus
    PhoneNumberInboundVoiceGender:
      type: string
      enum:
        - male
        - female
      description: >-
        Voice gender the AI agent uses on inbound calls to this number. Null
        when unset — the voice then uses the default, female. Set and cleared
        with Update a phone number.
      title: PhoneNumberInboundVoiceGender
    PhoneNumber:
      type: object
      properties:
        id:
          type: string
        number:
          type: string
          description: The number in E.164 format.
        nickname:
          type:
            - string
            - 'null'
          description: >-
            Optional human-readable label for the number, e.g. "Support line".
            Free text, at most 100 characters, not required to be unique. Null
            when unset. Set and cleared with Update a phone number.
        country:
          type: string
          description: >-
            ISO-3166-1 alpha-2 country code of the number. Always `US` — only US
            numbers can be provisioned at this time.
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumberCapabilitiesItems'
          description: >-
            Channels the number supports. `["sms","call"]` for a standard
            number; `["sms","call","imessage"]` for an iMessage number (which
            sends iMessage with automatic fallback to RCS/SMS). Mirrors the
            `capabilities` accepted when provisioning.
        setupStatus:
          $ref: '#/components/schemas/PhoneNumberSetupStatus'
          description: >-
            Whether the number is ready to use. An SMS/call number is always
            `ready`. An `imessage` number is `provisioning` while it's being set
            up and only becomes usable for sending or calling once `ready`
            (`failed` on a setup error). Poll List phone numbers to await
            `ready`.
        setupError:
          type:
            - string
            - 'null'
          description: >-
            Human-readable reason when `setupStatus` is `failed`; null
            otherwise.
        inboundInstruction:
          type:
            - string
            - 'null'
          description: >-
            System prompt the AI voice agent uses on inbound calls to this
            number. Set at provisioning time and changeable with Update a phone
            number. Null for numbers provisioned before this field existed —
            those reject inbound calls until an instruction is set.
        inboundVoiceGender:
          $ref: '#/components/schemas/PhoneNumberInboundVoiceGender'
          description: >-
            Voice gender the AI agent uses on inbound calls to this number. Null
            when unset — the voice then uses the default, female. Set and
            cleared with Update a phone number.
        inboundLanguage:
          type:
            - string
            - 'null'
          description: >-
            BCP-47 language tag the AI voice agent uses on inbound calls to this
            number. Null when unset — the language is then detected from the
            caller's country prefix on each call, with the agent handling both
            that language and `en-US`. Set and cleared with Update a phone
            number.
        accountId:
          type: string
        createdAt:
          type: string
          format: date-time
        maxCallDurationSeconds:
          type:
            - integer
            - 'null'
          description: >-
            Call-length cap in seconds; the effective cap on a call is the first
            one set in priority order — per-call, then number, then account —
            falling back to the global default. A higher-priority level
            overrides a lower one. Null means this level sets no cap.
      title: PhoneNumber
    Phone numbers_updateNumber_Response_200:
      type: object
      properties:
        number:
          $ref: '#/components/schemas/PhoneNumber'
      title: Phone numbers_updateNumber_Response_200
    ErrorError:
      oneOf:
        - type: string
        - type: object
          additionalProperties:
            description: Any type
      description: An error message, or a validation-error object for 400 responses.
      title: ErrorError
    Error:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorError'
          description: An error message, or a validation-error object for 400 responses.
      title: Error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your Dial API key, sent as `Authorization: Bearer sk_live_...`'

```

## Examples



**Request**

```json
{}
```

**Response**

```json
{
  "number": {
    "id": "num_123e4567-e89b-12d3-a456-426614174000",
    "number": "+14155550123",
    "nickname": "Support line",
    "country": "US",
    "capabilities": [
      "sms",
      "call"
    ],
    "setupStatus": "ready",
    "setupError": "",
    "inboundInstruction": "You are Dial's receptionist. Greet the caller and find out what they need.",
    "inboundVoiceGender": "female",
    "inboundLanguage": "es-ES",
    "accountId": "acct_9876543210abcdef",
    "createdAt": "2024-01-15T09:30:00Z",
    "maxCallDurationSeconds": 300
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.getdial.ai/api/v1/numbers/id"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.getdial.ai/api/v1/numbers/id';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getdial.ai/api/v1/numbers/id"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.getdial.ai/api/v1/numbers/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.getdial.ai/api/v1/numbers/id")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.getdial.ai/api/v1/numbers/id', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.getdial.ai/api/v1/numbers/id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.getdial.ai/api/v1/numbers/id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```