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.

{
  "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

{
  "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

{
  "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

{
  "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:

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

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

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

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

---

Examples

List the ten highest-risk active suppliers:

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:

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:

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:

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