# Suppressed Numbers API

Manage the company's Suppressed Numbers, including creating, updating, deleting, and retrieving suppressed numbers.

> [!NOTE]
> Suppressed Numbers exist regardless of whether or not there is a corresponding Contact Number or Contact.

## Check whether or not the company has any Suppressed Numbers

Returns a boolean value (`true`/`false`) whether the Company has any suppressed numbers.

```shell
curl https://api.retreaver.com/suppressed_numbers/check.json?api_key=[api_key]&company_id=1
```

> The above command returns JSON structured like this:

```json
{ "suppressed_numbers_exist": true }
```

Returns true if the Company has any numbers suppressed.

### HTTP Request

`GET https://api.retreaver.com/suppressed_numbers/check.json?api_key=[api_key]&company_id=1`

## Get all Suppressed Numbers for a Company

Get information about all of the numbers that are currently suppressed in a company.

```shell
curl https://api.retreaver.com/suppressed_numbers.json?api_key=[api_key]&company_id=1
```

> The above command returns JSON structured like this:

> [!NOTE]
> The Campaign ID `cid` will be returned only if the Suppressed Number is associated with a Campaign.

```json
[
  {
    "suppressed_number": {
      "id": 18996945,
      "number": "+13213749611",
      "created_at": "2024-09-30T21:09:54.769Z",
      "can_resubscribe": true,
      "company_id": 1,
      "cid": 159
    }
  },
  {
    "suppressed_number": {
      "id": 18996946,
      "number": "+13216065590",
      "created_at": "2024-09-30T21:09:54.769Z",
      "can_resubscribe": true,
      "company_id": 1,
      "cid": 111
    }
  },
  {
    "suppressed_number": {
      "id": 18996947,
      "number": "+13216437667",
      "created_at": "2024-09-30T21:09:54.769Z",
      "can_resubscribe": true,
      "company_id": 1
    }
  }
]
```

### HTTP Request

`GET https://api.retreaver.com/suppressed_numbers.json?api_key=[api_key]&company_id=1`

## Get a specific Suppressed Number

Returns information about the Suppressed Number in the company, by the provided number. The number should be in the format: `+13216065590`.

```shell
curl https://api.retreaver.com/suppressed_numbers/+13216065590.json?api_key=[api_key]&company_id=1
```

> The above command returns JSON structured like this:

> [!NOTE]
> The Campaign ID `cid` will be returned only if the Suppressed Number is associated with a Campaign.

```json
{
  "suppressed_number": {
    "id": 18996946,
    "number": "+13216065590",
    "created_at": "2024-09-30T21:09:54.769Z",
    "can_resubscribe": true,
    "company_id": 1,
    "cid": 111
  }
}
```

### HTTP Request

`GET https://api.retreaver.com/suppressed_numbers/+13216065590.json?api_key=[api_key]&company_id=1`

## Delete a number from the company's Suppressed Numbers

Deletes the provided number from the company's suppressed numbers. The number should be in the format: `+13216065590`.

```shell
curl -X DELETE https://api.retreaver.com/suppressed_numbers/+13216065590.json?api_key=[api_key]&company_id=1
```

### HTTP Request

`DELETE https://api.retreaver.com/suppressed_numbers/+13216065590.json?api_key=[api_key]&company_id=1`

## Create a Suppressed Number for a Company

Adds a number to the company's Suppressed Numbers. The `can_resubscribe` value toggles whether or not the caller can unblock themselves by pressing 7 if there is a "Caller Blocked" Prompt on the Campaign/Number they are calling.

The entire body of the post is optional, simply posting to `https://api.retreaver.com/suppressed_numbers/+13216065590.json?api_key=[api_key]&company_id=1` would block `+13216065590`; `can_resubscribe` is `true` by default. The intended use case is to allow callers to restore contact with a company after choosing to be routed to a "Add caller to suppressed numbers and hang up" routing option.

```shell
curl -s \
    -X POST \
    https://api.retreaver.com/suppressed_numbers/+13216065590.json?api_key=[api_key]&company_id=1 \
    -H "Content-Type: application/json" \
    -d '{"suppressed_number": {"can_resubscribe": false}}'
```

> The above command returns JSON structured like this:

```json
{
  "id": 18996958,
  "company_id": 1,
  "affiliate_id": null,
  "campaign_id": null,
  "number": "+13216065590",
  "created_at": "2024-10-11T08:50:59.981Z",
  "updated_at": "2024-10-11T08:50:59.981Z",
  "can_resubscribe": false
}
```

### HTTP Request

`POST https://api.retreaver.com/suppressed_numbers/+13216065590.json?api_key=[api_key]&company_id=1`

`Content-Type: application/json`

`{"suppressed_number": {"can_resubscribe": false}}`

## Update a Suppressed Number for a Company

By sending a `PUT` request you can update properties such as `can_resubscribe` and `campaign_id` for an already created Suppressed Number. The number should be in the format: `+13216065590`.

```shell
curl -s \
    -X PUT \
    https://api.retreaver.com/suppressed_numbers/+13216065590.json?api_key=[api_key]&company_id=1 \
    -H "Content-Type: application/json" \
    -d '{"suppressed_number": {"can_resubscribe": false}}'
```

### HTTP request

`PUT https://api.retreaver.com/suppressed_numbers/+13216065590.json?api_key=[api_key]&company_id=1`

`Content-Type: application/json`

`{"suppressed_number": {"can_resubscribe": false, "campaign_id": 116}}`

Note: `campaign_id` is the numeric internal Campaign ID, not the campaign `cid`.