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

# Update Number

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

Update a number. Only the fields you send are changed.

externalId: your own identifier for the number. Send a string to set it,
null to clear it, or omit it to leave it unchanged. Must be unique within
your account (409 otherwise). Works on any number type. The tag is echoed
on every number response and webhook payload and usable for lookup as
GET /v1/numbers/ext:\<externalId> or GET /v1/numbers?externalId=\<externalId>.

expiresAt: hard end date for the number (ISO 8601). After it passes the
number is released automatically and a number.released webhook is sent.
Send a datetime to set or move it (at least 5 minutes out), null to
clear it, or omit it to leave it unchanged.

Fields this endpoint does not support are rejected with 422, never
silently ignored.

Reference: https://docs.agentphone.to/api-reference/numbers/update-number-v-1-numbers-number-id-patch

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `number_id` (string, required)

### Body (application/json)

This endpoint expects an UpdateNumberRequest.

- `externalId` (string, optional, nullable)
- `expiresAt` (datetime, optional, nullable)

## Response

### 200

Successful Response

- `id` (string, required)
- `phoneNumber` (string, required)
- `country` (string, required)
- `status` (string, required)
- `createdAt` (datetime, required)
- `type` (string, optional, default: sms)
- `agentId` (string, optional, nullable)
- `outboundSms` (enum, optional, default: enabled)
  - Allowed values: `enabled`, `activating`, `registration_required`
- `inboundCallsEnabled` (boolean, optional, default: true)
- `readReceiptsEnabled` (boolean, optional, default: true)
- `whatsappEnabled` (boolean, optional, default: false)
- `dailyNewContacts` (DailyNewContactsUsage, optional, nullable)
- `externalId` (string, optional, nullable)
- `rcsFallbackForAlias` (string, optional, nullable)
- `expiresAt` (string, optional, nullable)
- `purchasedAt` (datetime, optional, nullable)
- `renewsAt` (string, optional, nullable) — Scheduled renewal of this number's monthly fee, ISO 8601 UTC. Null when no renewal is scheduled or its date is not known.

## Errors

### 422 Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional)

## Types

### DailyNewContactsUsage

- `used` (integer, required)
- `limit` (integer, optional, nullable)

### ValidationError

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)

### ValidationErrorLocItems

- string
- integer

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "id": "string",
  "phoneNumber": "string",
  "country": "string",
  "status": "string",
  "createdAt": "2024-01-15T09:30:00Z",
  "type": "sms",
  "agentId": "string",
  "outboundSms": "enabled",
  "inboundCallsEnabled": true,
  "readReceiptsEnabled": true,
  "whatsappEnabled": false,
  "dailyNewContacts": {
    "used": 1,
    "limit": 1
  },
  "externalId": "string",
  "rcsFallbackForAlias": "string",
  "expiresAt": "string",
  "purchasedAt": "2024-01-15T09:30:00Z",
  "renewsAt": "string"
}
```

**SDK Code**

```python
import requests

url = "https://api.agentphone.ai/v1/numbers/number_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.agentphone.ai/v1/numbers/number_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.agentphone.ai/v1/numbers/number_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.agentphone.ai/v1/numbers/number_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.agentphone.ai/v1/numbers/number_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.agentphone.ai/v1/numbers/number_id', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.agentphone.ai/v1/numbers/number_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.agentphone.ai/v1/numbers/number_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()
```