# Phone numbers

## Endpoints

- `GET /graph/whatsapp/{version}/{wabaId}/phone_numbers`: [List phone numbers](https://docs.polymorfa.com/api/graph/phone-numbers/list-phone-numbers)
- `POST /graph/whatsapp/{version}/{phoneNumberId}/register`: [Register](https://docs.polymorfa.com/api/graph/phone-numbers/register)
- `POST /graph/whatsapp/{version}/{phoneNumberId}/deregister`: [Deregister](https://docs.polymorfa.com/api/graph/phone-numbers/deregister)
- `POST /graph/whatsapp/{version}/{phoneNumberId}/request_code`: [Request code](https://docs.polymorfa.com/api/graph/phone-numbers/request-code)
- `POST /graph/whatsapp/{version}/{phoneNumberId}/verify_code`: [Verify code](https://docs.polymorfa.com/api/graph/phone-numbers/verify-code)

## The phone number object

### Attributes

- `id` (string, required). Identifier for this resource.
- `display_phone_number` (string, required). Specifies display phone number for this graph graph phone number.
- `verified_name` (string, required). Human-readable verified name for this graph graph phone number.
- `code_verification_status` (string, required). Specifies code verification status for this graph graph phone number.
- `quality_rating` (string, required). Specifies quality rating for this graph graph phone number.
- `platform_type` (string, required). Category assigned to platform.
- `is_on_biz_app` (boolean). Present for simulated Official API Test numbers: `true` when the number also uses the WhatsApp Business app.
- `throughput` (object, required). Structured throughput values for this graph graph phone number.
  - `level` (string, required). Specifies level for this throughput.
```json
{
  "id": "string",
  "display_phone_number": "string",
  "verified_name": "string",
  "code_verification_status": "string",
  "quality_rating": "string",
  "platform_type": "string",
  "is_on_biz_app": true,
  "throughput": {
    "level": "string"
  }
}
```

## List phone numbers

`GET https://api.polymorfa.com/graph/whatsapp/{version}/{wabaId}/phone_numbers` (Graph API)

Required permission: `sessions:read`

**Protocols:** Linked Device API · Meta Cloud API

**Required scope:** `sessions:read`

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `wabaId` (string, required). Identifier for the waba.

### Request

```bash
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/<wabaId>/phone_numbers" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>"
```

### Responses

#### 200

Phone numbers
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string, required). Identifier for this resource.
  - `display_phone_number` (string, required). Specifies display phone number for this graph graph phone number.
  - `verified_name` (string, required). Human-readable verified name for this graph graph phone number.
  - `code_verification_status` (string, required). Specifies code verification status for this graph graph phone number.
  - `quality_rating` (string, required). Specifies quality rating for this graph graph phone number.
  - `platform_type` (string, required). Category assigned to platform.
  - `is_on_biz_app` (boolean). Present for simulated Official API Test numbers: `true` when the number also uses the WhatsApp Business app.
  - `throughput` (object, required). Structured throughput values for this graph graph phone number.
    - `level` (string, required). Specifies level for this throughput.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "data": [
    {
      "id": "string",
      "display_phone_number": "string",
      "verified_name": "string",
      "code_verification_status": "string",
      "quality_rating": "string",
      "platform_type": "string",
      "throughput": {
        "level": "string"
      }
    }
  ]
}
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

## Register

`POST https://api.polymorfa.com/graph/whatsapp/{version}/{phoneNumberId}/register` (Graph API)

Required permission: `messages:write`

**Protocols:** Meta Cloud API

**Required scope:** `messages:write`

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `phoneNumberId` (string, required). Identifier for the phone number.

### Body


### Request

```bash
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/<phoneNumberId>/register" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d 'null'
```

### Responses

#### 200

Registered

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
null
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

## Deregister

`POST https://api.polymorfa.com/graph/whatsapp/{version}/{phoneNumberId}/deregister` (Graph API)

Required permission: `messages:write`

**Protocols:** Meta Cloud API

**Required scope:** `messages:write`

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `phoneNumberId` (string, required). Identifier for the phone number.

### Request

```bash
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/<phoneNumberId>/deregister" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>"
```

### Responses

#### 200

Deregistered

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
null
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

## Request code

`POST https://api.polymorfa.com/graph/whatsapp/{version}/{phoneNumberId}/request_code` (Graph API)

Required permission: `messages:write`

**Protocols:** Meta Cloud API

**Required scope:** `messages:write`

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `phoneNumberId` (string, required). Identifier for the phone number.

### Body


### Request

```bash
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/<phoneNumberId>/request_code" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d 'null'
```

### Responses

#### 200

Code requested

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
null
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

## Verify code

`POST https://api.polymorfa.com/graph/whatsapp/{version}/{phoneNumberId}/verify_code` (Graph API)

Required permission: `messages:write`

**Protocols:** Meta Cloud API

**Required scope:** `messages:write`

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `phoneNumberId` (string, required). Identifier for the phone number.

### Body


### Request

```bash
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/<phoneNumberId>/verify_code" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d 'null'
```

### Responses

#### 200

Verified

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
null
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```
