Loads records from the blacklist — numbers that opted out of receiving messages or were added to the blacklist by import or via the API.

## API URL

The URL used to send the HTTP requests:

```url
https://portal.bulkgate.com/api/1.0/black-list/load
```

> [!NOTE]
> If the request does not reach its destination, repeat it on the [backup server](https://www.bulkgate.com/en/docs/api-administration-tokens/api-backup-server/) `backup1.bulkgate.com`.

## Supported HTTP methods

- `POST` - `application/json`

```http
POST /api/1.0/black-list/load HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
```

> [!NOTE]
> The API has a quota of `20` requests per day.

## Parameters table

| PARAMETER NAME    | VALUE                                                                                                                                                             | MANDATORY               | DEFAULT VALUE  |
|:------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------|:---------------|
| application_id    | [Application ID](https://www.bulkgate.com/en/docs/api-administration-tokens/api-administration/)                                                                                                                     | **Yes**                 | -              | 
| application_token | [Application authentication token](https://www.bulkgate.com/en/docs/api-administration-tokens/api-tokens/)	                                                                                                          | **Yes**                 | -              |
| from              | Selects entries **from** a specific date. It accepts the [unix timestamp](https://en.wikipedia.org/wiki/Unix_time) or [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. | **Yes**                 | -              |
| to                | Selects entries **to** a specific date. It accepts the [unix timestamp](https://en.wikipedia.org/wiki/Unix_time) or [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.	  | No                      | `now`          |
| campaign_id       | Selects only records for a specific campaign                                                                                                                      | No                      | -              |
| wallet            | Selects only records for a specific wallet                                                                                                                        | No                      | Default wallet |

> [!NOTE]
> The maximal range between `from` and `to` is 30 days.

## Request example

```http-json
POST /api/1.0/black-list/load HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
  "application_id": 451,
  "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
  "campaign_id": "id-bulkgate-000001",
  "wallet": "bg1905014138000023",
  "from": "2018-05-14T18:30:00-01:00",
  "to": "2018-05-15T18:30:00-01:00"
}
```

## Response

**In case of success:**

```json
{
    "data": [
        {
            "key": "198668",
            "id": "198668",
            "wallet": "bg1905014138000023",
            "phone_number": "420777777777",
            "country": "cz",
            "type": "black-list",
            "created": "2018-11-21T15:30:31+01:00",
            "modified": null,
            "source": "web",
            "source_key": null,
            "reason": "I don't want to receive business messages.",
            "campaign_id": "id-bulkgate-000001",
            "application_id": 451,
            "channel": null,
            "tag": null,
            "contact": null
        },
        {
            "key": "198667",
            "id": "198667",
            "wallet": "bg1905014138000023",
            "phone_number": "420777777778",
            "country": "cz",
            "type": "black-list",
            "created": "2018-11-21T15:30:35+01:00",
            "modified": null,
            "source": "import",
            "source_key": "import.csv",
            "reason": null,
            "campaign_id": null,
            "application_id": 451,
            "channel": null,
            "tag": null,
            "contact": null
        }
    ]
}
```

Where:

- **key** and **id** are the record identifier (the same value)
- **phone_number** is the number in the international format
- **type** is either `black-list` or `opt-out`
- **created** and **modified** are the times the record was created and last changed, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
- **source** is how the number got onto the blacklist — `web`, `import`, `api`, `manual` or `auto`
- **source_key** is the identifier of the group the number was added with. For records with `source` = `import` it holds the name of the imported file.
- **reason** is the reason given when the number was blacklisted

**In case of error:**

```json
{
    "type": "invalid_wallet",
    "code": 400,
    "error": "Invalid wallet",
    "detail": null
}
```

```json
{
    "type": "invalid_input_parameters",
    "code": 400,
    "error": "Invalid input parameters",
    "detail": null
}
```

```json
{
    "type": "maximal_date_range_is_30_days",
    "code": 400,
    "error": "Maximal date range is 30 days",
    "detail": null
}
```

```json
{
    "type": "the_daily_quota_has_been_exceeded",
    "code": 400,
    "error": "The daily quota has been exceeded",
    "detail": null
}
```

Where:

- **type** and **error** (description of the error) can be found in the [error types table](https://www.bulkgate.com/en/docs/api-administration-tokens/api-error-types/)
- **code** is the HTTP error code
- **detail** is additional information about the error

### Blacklist API error types

Besides the [general types](https://www.bulkgate.com/en/docs/api-administration-tokens/api-error-types/), the Blacklist API returns its own:

| TYPE                              | WHEN IT HAPPENS                                                |
|:----------------------------------|:-----------------------------------------------------------------|
| `invalid_wallet`                  | The given wallet does not exist or you have no access to it.   |
| `invalid_input_parameters`        | `from` is missing, has an invalid format, or is not older than `to`. |
| `maximal_date_range_is_30_days`   | The range between `from` and `to` is longer than 30 days.      |
| `the_daily_quota_has_been_exceeded`| The request quota is used up.                                 |