> For the complete documentation index, see [llms.txt](https://docs.whiteintel.io/whiteintel-api-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.whiteintel.io/whiteintel-api-doc/supplier-security-api/supplier-api.md).

# Supplier API

The Supplier Security API provides programmatic management of your organization's tracked supplier list. It consolidates the three core operations of the Supplier Security module into a single endpoint: listing tracked suppliers with their latest risk snapshot, adding or reactivating a supplier, and removing a supplier by archiving or permanently deleting it.

Each tracked supplier is scoped to your organization and carries a risk snapshot (latest score, grade, score delta, and most recent event) that is refreshed by the platform's scoring pipeline. This endpoint reads and manages that list; it does not trigger scans directly.

All operations are performed against a single endpoint and selected through the `action` parameter.

***

### Endpoint

```
POST https://api.whiteintel.io/supplier_api.php
```

#### Headers

| Header         | Value              |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |

***

### Authentication

Authentication is performed via an API key passed in the request body. Your API key can be retrieved from either the Organizations page or the Profile page on the WhiteIntel platform.

```json
{
  "apikey": "YOUR_API_KEY"
}
```

Requests without a valid API key return `403 Forbidden`. The API key must be attached to an organization; keys that are not associated with an organization return `403 Forbidden` with an explanatory message.

***

### Access Requirements

This endpoint is available to organization accounts. All supplier data is scoped to the organization that owns the API key, and every operation is constrained to that organization's records.

The number of suppliers an organization may actively track is governed by its supplier credit allowance. Each actively tracked supplier consumes one slot from this allowance, and removing a supplier frees its slot. This allowance is enforced independently of the daily API call quota described below.

***

### Rate Limits and Quotas

| Limit Type       | Description                                                                                                                                     |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Request throttle | A short cool-down is enforced between consecutive requests from the same account. Exceeding it returns `429 Too Many Requests`.                 |
| Daily quota      | Each API key is provisioned with a daily request quota. Remaining quota is returned in every dispatched response under `remaining_daily_calls`. |
| Supplier slots   | The active supplier count is capped by the organization's supplier credit allowance. Exceeding it on an add operation returns `403 Forbidden`.  |

Once the daily quota is exhausted, requests return `403 Forbidden` with a quota-exceeded message until the counter resets.

A well-formed, authenticated call consumes one daily quota credit even when the outcome is a no-op, such as adding a supplier that is already tracked or listing a set that returns zero rows. Malformed requests that fail validation before dispatch (for example, a missing domain or an invalid filter value) do not consume a credit. Plan request cadence accordingly.

***

### Actions

The operation is selected by the `action` parameter. It is required and must be one of the following.

| Action   | Description                                                                          |
| -------- | ------------------------------------------------------------------------------------ |
| `list`   | Return the organization's tracked suppliers with filtering, sorting, and pagination. |
| `add`    | Add a new tracked supplier, or reactivate one that was previously archived.          |
| `remove` | Permanently remove a tracked supplier from the list.                                 |

The value `delete` is accepted as an alias for `remove`.

***

### Action: list

Returns a page of tracked suppliers for the organization, with each supplier carrying its latest risk snapshot. Results are filtered, sorted, and paginated according to the parameters below.

#### Request Parameters

| Parameter | Type    | Required | Default  | Description                                                                                   |
| --------- | ------- | -------- | -------- | --------------------------------------------------------------------------------------------- |
| `apikey`  | string  | Yes      | -        | Your WhiteIntel API key.                                                                      |
| `action`  | string  | Yes      | -        | Must be `list`.                                                                               |
| `status`  | string  | No       | `active` | Filter by status. One of `active`, `paused`, `archived`, or `all`.                            |
| `tier`    | string  | No       | -        | Filter by assigned supplier tier. One of `critical`, `high`, `medium`, `low`.                 |
| `search`  | string  | No       | -        | Case-insensitive substring match against `domain` and `display_name`. Maximum 253 characters. |
| `sort`    | string  | No       | `score`  | Sort key. One of `score`, `recent`, `scanned`, `name`, `added`, `updated`.                    |
| `order`   | string  | No       | `desc`   | Sort direction. One of `asc` or `desc`.                                                       |
| `limit`   | integer | No       | `50`     | Page size. Clamped to the range 1 to 200.                                                     |
| `offset`  | integer | No       | `0`      | Row offset for pagination.                                                                    |

The `sort` key selects the ordering field: `score` orders by the latest risk score, `recent` by the most recent event, `scanned` by the last scoring timestamp, `name` by display name, `added` by creation time, and `updated` by last update time. The default sort surfaces the highest-risk suppliers first.

#### Response

```json
{
  "success": true,
  "total": 128,
  "count": 50,
  "limit": 50,
  "offset": 0,
  "suppliers": [
    {
      "id": 4412,
      "domain": "acme.com",
      "display_name": "Acme Corporation",
      "size": "200-500",
      "country": "US",
      "industry": "SaaS",
      "supplier_tier": "high",
      "category": "vendor",
      "status": "active",
      "last_score": 72.5,
      "last_grade": "C",
      "last_score_delta": -3.1,
      "last_scored_at": "2026-06-24 03:15:00",
      "last_event_at": "2026-06-23 18:42:10",
      "last_event_type": "credential_exposure",
      "last_event_summary": "New corporate credentials observed",
      "created_at": "2026-01-10 09:00:00",
      "updated_at": "2026-06-24 03:15:00"
    }
  ],
  "remaining_daily_calls": 487
}
```

| Field                   | Description                                                        |
| ----------------------- | ------------------------------------------------------------------ |
| `total`                 | Total number of suppliers matching the filter, across all pages.   |
| `count`                 | Number of suppliers returned in this page.                         |
| `limit`                 | Effective page size after clamping.                                |
| `offset`                | Offset used for this page.                                         |
| `suppliers`             | Array of supplier objects, each carrying its latest risk snapshot. |
| `remaining_daily_calls` | Daily quota remaining after this call.                             |

***

### Action: add

Adds a new tracked supplier, or reactivates one that was previously archived, refreshing its metadata in the process. The operation is performed under the organization's supplier credit allowance.

#### Request Parameters

| Parameter       | Type   | Required | Default | Description                                                                                              |
| --------------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `apikey`        | string | Yes      | -       | Your WhiteIntel API key.                                                                                 |
| `action`        | string | Yes      | -       | Must be `add`.                                                                                           |
| `domain`        | string | Yes      | -       | The supplier domain. Resolved to its registrable root (for example, `mail.acme.com` becomes `acme.com`). |
| `display_name`  | string | No       | -       | Human-readable supplier name. Maximum 255 characters.                                                    |
| `size`          | string | No       | -       | Free-form organization size label. Maximum 32 characters.                                                |
| `country`       | string | No       | -       | Country label. Maximum 64 characters.                                                                    |
| `industry`      | string | No       | -       | Industry label. Maximum 96 characters.                                                                   |
| `category`      | string | No       | -       | Free-form category label. Maximum 64 characters.                                                         |
| `supplier_tier` | string | No       | -       | Assigned tier. One of `critical`, `high`, `medium`, `low`.                                               |
| `notes`         | string | No       | -       | Free-form notes. Maximum 5000 characters.                                                                |

Optional fields longer than their maximum length are silently truncated to fit. Empty strings are treated as absent.

#### Response

```json
{
  "success": true,
  "action": "added",
  "supplier_id": 4413,
  "domain": "acme.com",
  "used": 41,
  "limit": 100,
  "remaining": 59,
  "remaining_daily_calls": 486
}
```

| Field                   | Description                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------ |
| `action`                | `added` for a new supplier, `reactivated` when a previously archived supplier is restored. |
| `supplier_id`           | Identifier of the created or reactivated supplier.                                         |
| `domain`                | The resolved registrable domain that was tracked.                                          |
| `used`                  | Active supplier slots in use after this operation.                                         |
| `limit`                 | The organization's supplier credit allowance.                                              |
| `remaining`             | Supplier slots remaining after this operation.                                             |
| `remaining_daily_calls` | Daily quota remaining after this call.                                                     |

***

### Action: remove

Permanently removes a supplier from the organization's track list. This operation deletes the supplier record outright and cannot be undone. Removing a supplier frees the slot it occupied in the organization's supplier credit allowance.

A supplier may be identified by `id` (preferred) or by `domain`. If both are provided, `id` takes precedence.

#### Request Parameters

| Parameter | Type    | Required    | Default | Description                                                                          |
| --------- | ------- | ----------- | ------- | ------------------------------------------------------------------------------------ |
| `apikey`  | string  | Yes         | -       | Your WhiteIntel API key.                                                             |
| `action`  | string  | Yes         | -       | Must be `remove` (or its alias `delete`).                                            |
| `id`      | integer | Conditional | -       | Supplier identifier. Required if `domain` is not provided.                           |
| `domain`  | string  | Conditional | -       | Supplier domain, resolved to its registrable root. Required if `id` is not provided. |

#### Response

```json
{
  "success": true,
  "action": "deleted",
  "supplier_id": 4413,
  "used": 40,
  "limit": 100,
  "remaining": 60,
  "remaining_daily_calls": 485
}
```

| Field                   | Description                                                    |
| ----------------------- | -------------------------------------------------------------- |
| `action`                | Always `deleted`. The supplier record was permanently removed. |
| `supplier_id`           | Identifier of the removed supplier.                            |
| `used`                  | Active supplier slots in use after this operation.             |
| `limit`                 | The organization's supplier credit allowance.                  |
| `remaining`             | Supplier slots remaining after this operation.                 |
| `remaining_daily_calls` | Daily quota remaining after this call.                         |

***

### Restricted Domains

Certain domains cannot be tracked and will be rejected on an add operation with `403 Forbidden`. This includes a defined set of government and protected domains. Such requests are blocked before any record is created.

***

### Error Responses

Errors are returned with an appropriate HTTP status code and a JSON body containing `success: false` and an `error` or `message` field.

| Status                      | Condition                                                                                                                                                                                                 |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | Invalid JSON body, missing or invalid `action`, missing or unresolvable `domain`, invalid `supplier_tier`, invalid `status`, invalid `tier`, or a remove request that provides neither `id` nor `domain`. |
| `403 Forbidden`             | Missing or invalid API key, API key not attached to an organization, supplier credit allowance reached on add, a blocked domain, or the daily request quota exhausted.                                    |
| `404 Not Found`             | The specified supplier was not found within the organization, or the organization could not be resolved.                                                                                                  |
| `405 Method Not Allowed`    | The request was not a `POST` with `application/json`.                                                                                                                                                     |
| `409 Conflict`              | The supplier is already actively tracked.                                                                                                                                                                 |
| `429 Too Many Requests`     | The per-account request throttle was exceeded.                                                                                                                                                            |
| `500 Internal Server Error` | An unexpected error occurred while processing the request.                                                                                                                                                |

Selected error bodies:

```json
{ "success": false, "error": "Invalid or missing action.", "allowed": ["list", "add", "remove"] }
```

```json
{ "success": false, "error": "Supplier tracking limit reached for your plan.", "used": 100, "limit": 100, "remaining": 0 }
```

```json
{ "success": false, "error": "This supplier is already being tracked.", "supplier_id": 4413 }
```

```json
{ "success": false, "error": "Daily API request limit exceeded." }
```

***

### Examples

List the ten highest-risk active suppliers:

```bash
curl --location 'https://api.whiteintel.io/supplier_api.php' \
  --header 'Content-Type: application/json' \
  --data '{
    "apikey": "YOUR_API_KEY",
    "action": "list",
    "status": "active",
    "sort": "score",
    "order": "desc",
    "limit": 10,
    "offset": 0
  }'
```

Add a supplier with metadata and a tier:

```bash
curl --location 'https://api.whiteintel.io/supplier_api.php' \
  --header 'Content-Type: application/json' \
  --data '{
    "apikey": "YOUR_API_KEY",
    "action": "add",
    "domain": "acme.com",
    "display_name": "Acme Corporation",
    "industry": "SaaS",
    "country": "US",
    "supplier_tier": "high",
    "notes": "Primary billing vendor"
  }'
```

Remove a supplier by id:

```bash
curl --location 'https://api.whiteintel.io/supplier_api.php' \
  --header 'Content-Type: application/json' \
  --data '{
    "apikey": "YOUR_API_KEY",
    "action": "remove",
    "id": 4413
  }'
```

Remove a supplier by domain:

```bash
curl --location 'https://api.whiteintel.io/supplier_api.php' \
  --header 'Content-Type: application/json' \
  --data '{
    "apikey": "YOUR_API_KEY",
    "action": "remove",
    "domain": "acme.com"
  }'
```