> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pinnacle.sh/v-2/api-reference/rcs-agents/test/whitelist-number/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pinnacle.sh/_mcp/server.

# Whitelist Number for Test Agent

POST https://api.pinnacle.sh/rcs/test/agents/{agentId}/whitelist
Content-Type: application/json

Whitelist a phone number for testing with a specific test agent.During development and testing, RCS agents can only send messages to whitelisted phone numbers.
Use this endpoint to whitelist specific phone numbers so you can send and receive messages from the test agent.## Verification ProcessAfter whitelisting, the recipient must accept the tester invite:1) The recipient's device will receive a message from "RBM Tester Management".
2) The recipient must tap "Make me a tester" to accept.
3) Once accepted, the status transitions from `PENDING` to `ACCEPTED`.## VerificationAccepting the inviteDeclining the invite## CooldownThere is a **2-minute cooldown** after creating or updating a test agent before you can whitelist numbers.
Attempting to whitelist during the cooldown returns a `500` error with the remaining wait time.

Reference: https://docs.pinnacle.sh/api-reference/rcs-agents/test/whitelist-number

## Authentication

- `PINNACLE-API-KEY` header (required) — API Key authentication via header

## Request

### Path parameters

- `agentId` (string, required) — The RCS agent ID (must be prefixed with `agent_`).

### Body (application/json)

This endpoint expects a TestAgentWhitelistRequest.

- `phoneNumber` (string, required) — Phone number to whitelist for testing in E.164 format.

## Response

### 200

Returns the whitelist status of the phone number.

- `status` (enum, required) — Status of a whitelisted phone number for RCS testing. - `PENDING` — The tester invite has been sent but the recipient has not yet accepted or rejected it. - `ACCEPTED` — The recipient accepted the tester invite and can send/receive messages with the test agent. - `REJECTED` — The recipient rejected the tester invite or the invite could not be delivered.
  - Allowed values: `PENDING`, `ACCEPTED`, `REJECTED`

## Errors

### 400 Bad Request Error

Validation failed. The payload has missing required fields and/or invalid types.  See [https://zod.dev/error-formatting](https://zod.dev/error-formatting) for more information.

- `description` (string, required) — Human-readable summary of validation failures.
- `errors` (ZodErrorErrors, required) — Structured dictionary of issues containing two main sections: - `errors`: Array of global validation errors not tied to specific fields - `properties`: Object mapping field names to their specific validation errors, where each field contains an `errors` array

### 401 Unauthorized Error

The request lacks valid authentication credentials or the provided credentials are invalid.  Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.

- `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code.

### 403 Forbidden Error

Your subscription does not include access to this feature.  This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature.

- `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code.

### 404 Not Found Error

The requested resource could not be found.  This may occur if the identifier is incorrect, the resource has been deleted, or you don't have permission to access it.

- `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code.

### 500 Internal Server Error

An internal error occurred. Common causes: - **Cooldown period:** The 2-minute cooldown after agent creation/update has not expired.

- `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code.

## Types

### ZodErrorErrors

Structured dictionary of issues containing two main sections: - `errors`: Array of global validation errors not tied to specific fields - `properties`: Object mapping field names to their specific validation errors, where each field contains an `errors` array

## Examples

### Whitelist Pending

**Response**

```json
{
  "status": "PENDING"
}
```

**SDK Code**

```python Whitelist Pending
import requests

url = "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist"

headers = {"PINNACLE-API-KEY": "<apiKey>"}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript Whitelist Pending
const url = 'https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist';
const options = {method: 'POST', headers: {'PINNACLE-API-KEY': '<apiKey>'}};

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

```go Whitelist Pending
package main

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

func main() {

	url := "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("PINNACLE-API-KEY", "<apiKey>")

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

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

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

}
```

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

url = URI("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist")

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

request = Net::HTTP::Post.new(url)
request["PINNACLE-API-KEY"] = '<apiKey>'

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

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

HttpResponse<String> response = Unirest.post("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist")
  .header("PINNACLE-API-KEY", "<apiKey>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist', [
  'headers' => [
    'PINNACLE-API-KEY' => '<apiKey>',
  ],
]);

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

```csharp Whitelist Pending
using RestSharp;

var client = new RestClient("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist");
var request = new RestRequest(Method.POST);
request.AddHeader("PINNACLE-API-KEY", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift Whitelist Pending
import Foundation

let headers = ["PINNACLE-API-KEY": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

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()
```

### Whitelist Accepted

**Response**

```json
{
  "status": "ACCEPTED"
}
```

**SDK Code**

```python Whitelist Accepted
import requests

url = "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist"

headers = {"PINNACLE-API-KEY": "<apiKey>"}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript Whitelist Accepted
const url = 'https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist';
const options = {method: 'POST', headers: {'PINNACLE-API-KEY': '<apiKey>'}};

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

```go Whitelist Accepted
package main

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

func main() {

	url := "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("PINNACLE-API-KEY", "<apiKey>")

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

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

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

}
```

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

url = URI("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist")

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

request = Net::HTTP::Post.new(url)
request["PINNACLE-API-KEY"] = '<apiKey>'

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

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

HttpResponse<String> response = Unirest.post("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist")
  .header("PINNACLE-API-KEY", "<apiKey>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist', [
  'headers' => [
    'PINNACLE-API-KEY' => '<apiKey>',
  ],
]);

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

```csharp Whitelist Accepted
using RestSharp;

var client = new RestClient("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist");
var request = new RestRequest(Method.POST);
request.AddHeader("PINNACLE-API-KEY", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift Whitelist Accepted
import Foundation

let headers = ["PINNACLE-API-KEY": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

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()
```

### rcs_test_whitelistNumber_example

**Request**

```json
{
  "phoneNumber": "+12345678901"
}
```

**Response**

```json
{
  "status": "PENDING"
}
```

**SDK Code**

```python rcs_test_whitelistNumber_example
import requests

url = "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist"

payload = { "phoneNumber": "+12345678901" }
headers = {
    "PINNACLE-API-KEY": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript rcs_test_whitelistNumber_example
const url = 'https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist';
const options = {
  method: 'POST',
  headers: {'PINNACLE-API-KEY': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"phoneNumber":"+12345678901"}'
};

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

```go rcs_test_whitelistNumber_example
package main

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

func main() {

	url := "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist"

	payload := strings.NewReader("{\n  \"phoneNumber\": \"+12345678901\"\n}")

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

	req.Header.Add("PINNACLE-API-KEY", "<apiKey>")
	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 rcs_test_whitelistNumber_example
require 'uri'
require 'net/http'

url = URI("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist")

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

request = Net::HTTP::Post.new(url)
request["PINNACLE-API-KEY"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"phoneNumber\": \"+12345678901\"\n}"

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

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

HttpResponse<String> response = Unirest.post("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist")
  .header("PINNACLE-API-KEY", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phoneNumber\": \"+12345678901\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist', [
  'body' => '{
  "phoneNumber": "+12345678901"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'PINNACLE-API-KEY' => '<apiKey>',
  ],
]);

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

```csharp rcs_test_whitelistNumber_example
using RestSharp;

var client = new RestClient("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist");
var request = new RestRequest(Method.POST);
request.AddHeader("PINNACLE-API-KEY", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"phoneNumber\": \"+12345678901\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift rcs_test_whitelistNumber_example
import Foundation

let headers = [
  "PINNACLE-API-KEY": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["phoneNumber": "+12345678901"] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456/whitelist")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
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()
```

> One API for RCS, iMessage, MMS, and SMS. Build, test, and scale every channel — send your first message in minutes, not weeks.