TruSupplier API

Read and manage your suppliers, run checks, file documents, chase suppliers for what's missing and read your B-BBEE and billing figures from your own systems or an AI assistant.

Base URL

https://app.trusupplier.co.za/api/v1

All requests and responses are JSON (document upload uses multipart/form-data). Times are ISO 8601 in UTC. Money is in South African rand (credits are rand). Lists take limit (1–200, default 50) and offset. Archived suppliers and documents are left out of lists.

The machine-readable OpenAPI 3.1 spec describes every endpoint on this page.

Authentication

Create a key in the app under Settings › API & MCP (owners and admins). The key is shown once: store it in a secret manager. Send it on every request:

Header

Authorization: Bearer ts_test_xxxxxxxxxxxxxxxx

Each key belongs to one company and acts with the access of the person who created it. A key has one or more scopes:

Scope	Allows
`read`	All GET endpoints. Every key has it.
`write`	Add, update and archive suppliers, upload documents, send document requests.
`run_checks`	Quote and start checks that spend credits.

Revoked or expired keys stop working and return 401: immediately for writes, within 30 seconds for reads. A key also stops working if its creator leaves the company. Changes made through the API are recorded in your audit log under the key's prefix.

Errors

Errors use standard HTTP status codes and one JSON shape:

Error body

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key doesn't have the \"run_checks\" scope."
  }
}

Status	Code	Meaning
`400`	`invalid_request`	A parameter is missing or wrong (for example an id that isn't a UUID).
`400`	`invalid_json`	The request body isn't valid JSON.
`400` / `403`	`upload_failed`	The file couldn't be stored.
`401`	`unauthorized`	No key, unknown key, revoked or expired key.
`402`	`insufficient_credits`	Not enough credits to run the checks. `details` has the quote.
`403`	`insufficient_scope` / `forbidden`	The key lacks the scope, or the creator's role doesn't allow it.
`404`	`not_found`	No such record in your company, or no such endpoint.
`409`	`conflict`	A supplier with that registration number already exists.
`413`	`too_large`	File over 10 MB.
`429`	`rate_limited`	Too many requests. Wait for `Retry-After` seconds.
`500`	`server_error`	Something went wrong on our side. Retry later.
`502`	`upstream_error`	The key couldn't be checked just now. Retry later.

Rate limits

Each key can make 120 requests per minute. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). Over the limit you get 429 with Retry-After.

Checks and credits

Checks cost credits from your wallet. POST /checks/run is two steps so nothing is spent by accident:

Without confirm (or confirm: false) you get a quote: cost per supplier, total, your available credits and enough_credits. Nothing is charged.
With "confirm": true the checks start and the cost is reserved, then charged when results come in. Checks a Supplier Bundle already covers aren't charged twice.

Results arrive asynchronously: follow GET /checks/runs and read GET /checks/results. Use GET /checks/types for ids and prices.

MCP server

AI assistants that speak the Model Context Protocol can use the same operations as tools. Every endpoint above is a tool with the name shown next to it (for example list_suppliers, run_checks). Use the same API key and scopes.

Endpoint (Streamable HTTP)

https://app.trusupplier.co.za/mcp

run_checks spends credits only when called with confirm: true; assistants are told to show the quote and ask first. send_requests emails your suppliers. The server is stateless and answers with JSON (no server-sent stream).

Cursor

Settings › MCP › Add new server, or .cursor/mcp.json:

mcp.json

{
  "mcpServers": {
    "trusupplier": {
      "url": "https://app.trusupplier.co.za/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop

Settings › Developer › Edit config (claude_desktop_config.json). Uses the mcp-remote bridge, so Node.js must be installed:

claude_desktop_config.json

{
  "mcpServers": {
    "trusupplier": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.trusupplier.co.za/mcp",
        "--header",
        "Authorization:${TRUSUPPLIER_AUTH}"
      ],
      "env": {
        "TRUSUPPLIER_AUTH": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Other clients

Point any Streamable HTTP client at the endpoint with the header Authorization: Bearer YOUR_API_KEY. Test it with the MCP Inspector:

Terminal

npx @modelcontextprotocol/inspector --cli https://app.trusupplier.co.za/mcp \
  --transport http --header "Authorization: Bearer $TRUSUPPLIER_API_KEY" \
  --method tools/list

Authentication

GET/api/v1/me

Check your key

Scope read

Request

curl "https://app.trusupplier.co.za/api/v1/me" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY"

Response 200

{
  "data": {
    "company_id": "\u2026",
    "key_prefix": "ts_test_xxxxxxxxxxxxxxxx",
    "scopes": [
      "read",
      "write"
    ]
  }
}

Suppliers

GET/api/v1/suppliers

List suppliers

List your company's suppliers (archived ones are hidden). Filter by name search or registration number.

Scope read · MCP tool list_suppliers

Parameter	Description
`q` query	Search legal or trading name
`registration_no` query	Exact company registration number, e.g. 2015/123456/07
`limit` query	Max rows, 1-200 (default 50)
`offset` query	Rows to skip (default 0)

Request

curl "https://app.trusupplier.co.za/api/v1/suppliers?q=mokoena&limit=20" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY"

Response 200

{
  "data": [
    {
      "id": "8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10",
      "legal_name": "Mokoena Logistics (Pty) Ltd",
      "trading_name": "Mokoena Freight",
      "registration_no": "2015/123456/07",
      "vat_no": "4123456789",
      "status": "active",
      "compliance_state": "compliant",
      "kyb_state": "verified",
      "bbbee_level": "2",
      "bbbee_valid_to": "2027-03-31",
      "enterprise_type": "QSE",
      "black_ownership_pct": 100,
      "black_women_ownership_pct": 51,
      "industry_id": "49",
      "company_status": "In Business",
      "website": "https://www.example.co.za",
      "physical_address": "12 Example Street, Johannesburg, 2000",
      "annual_spend": 1250000,
      "aml_result": null,
      "bank_check_result": null,
      "source": "api",
      "date_created": "2026-10-01T08:12:44.000Z",
      "date_updated": "2026-10-20T14:03:10.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

POST/api/v1/suppliers

Add a supplier

Add a supplier. Fails with 409 if a supplier with the same registration number already exists. Does not run any paid checks. Scope: write.

Scope write · MCP tool create_supplier

Parameter	Description
`legal_name` body · string required	Registered company name
`trading_name` body · string	Trading name
`registration_no` body · string	Company registration number
`vat_no` body · string	VAT number
`website` body · string	Website
`physical_address` body · string	Address
`annual_spend` body · number	Annual spend with this supplier (ZAR)

Request

curl -X POST "https://app.trusupplier.co.za/api/v1/suppliers" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"legal_name": "Mokoena Logistics (Pty) Ltd", "registration_no": "2015/123456/07", "vat_no": "4123456789", "annual_spend": 1250000}'

Response 201

{
  "data": {
    "id": "8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10",
    "legal_name": "Mokoena Logistics (Pty) Ltd",
    "trading_name": "Mokoena Freight",
    "registration_no": "2015/123456/07",
    "vat_no": "4123456789",
    "status": "active",
    "compliance_state": "compliant",
    "kyb_state": "verified",
    "bbbee_level": "2",
    "bbbee_valid_to": "2027-03-31",
    "enterprise_type": "QSE",
    "black_ownership_pct": 100,
    "black_women_ownership_pct": 51,
    "industry_id": "49",
    "company_status": "In Business",
    "website": "https://www.example.co.za",
    "physical_address": "12 Example Street, Johannesburg, 2000",
    "annual_spend": 1250000,
    "aml_result": null,
    "bank_check_result": null,
    "source": "api",
    "date_created": "2026-10-01T08:12:44.000Z",
    "date_updated": "2026-10-20T14:03:10.000Z"
  }
}

GET/api/v1/suppliers/{id}

Get a supplier

One supplier's profile and compliance status.

Scope read · MCP tool get_supplier

Parameter	Description
`id` path required	Supplier id (UUID)

Request

curl "https://app.trusupplier.co.za/api/v1/suppliers/8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY"

Response 200

{
  "data": {
    "id": "8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10",
    "legal_name": "Mokoena Logistics (Pty) Ltd",
    "trading_name": "Mokoena Freight",
    "registration_no": "2015/123456/07",
    "vat_no": "4123456789",
    "status": "active",
    "compliance_state": "compliant",
    "kyb_state": "verified",
    "bbbee_level": "2",
    "bbbee_valid_to": "2027-03-31",
    "enterprise_type": "QSE",
    "black_ownership_pct": 100,
    "black_women_ownership_pct": 51,
    "industry_id": "49",
    "company_status": "In Business",
    "website": "https://www.example.co.za",
    "physical_address": "12 Example Street, Johannesburg, 2000",
    "annual_spend": 1250000,
    "aml_result": null,
    "bank_check_result": null,
    "source": "api",
    "date_created": "2026-10-01T08:12:44.000Z",
    "date_updated": "2026-10-20T14:03:10.000Z"
  }
}

PATCH/api/v1/suppliers/{id}

Update a supplier

Change a supplier's basic details. Only the fields you send change. Scope: write.

Scope write · MCP tool update_supplier

Parameter	Description
`id` path required	Supplier id
`legal_name` body · string	Registered name
`trading_name` body · string	Trading name
`registration_no` body · string	Registration number
`vat_no` body · string	VAT number
`website` body · string	Website
`physical_address` body · string	Address
`postal_address` body · string	Postal address
`annual_spend` body · number	Annual spend (ZAR)

Request

curl -X PATCH "https://app.trusupplier.co.za/api/v1/suppliers/8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trading_name": "Mokoena Freight", "annual_spend": 1400000}'

Response 200

{
  "data": {
    "id": "8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10",
    "legal_name": "Mokoena Logistics (Pty) Ltd",
    "trading_name": "Mokoena Freight",
    "registration_no": "2015/123456/07",
    "vat_no": "4123456789",
    "status": "active",
    "compliance_state": "compliant",
    "kyb_state": "verified",
    "bbbee_level": "2",
    "bbbee_valid_to": "2027-03-31",
    "enterprise_type": "QSE",
    "black_ownership_pct": 100,
    "black_women_ownership_pct": 51,
    "industry_id": "49",
    "company_status": "In Business",
    "website": "https://www.example.co.za",
    "physical_address": "12 Example Street, Johannesburg, 2000",
    "annual_spend": 1250000,
    "aml_result": null,
    "bank_check_result": null,
    "source": "api",
    "date_created": "2026-10-01T08:12:44.000Z",
    "date_updated": "2026-10-20T14:03:10.000Z"
  }
}

GET/api/v1/suppliers/by-registration/{registration_no}

Find a supplier by registration number

Look up a supplier by company registration number (slashes optional, e.g. 2015/123456/07 or 201512345607).

Scope read · MCP tool get_supplier_by_registration

Parameter	Description
`registration_no` path required	Company registration number

Request

curl "https://app.trusupplier.co.za/api/v1/suppliers/by-registration/2015%2F123456%2F07" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY"

Response 200

{
  "data": {
    "id": "8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10",
    "legal_name": "Mokoena Logistics (Pty) Ltd",
    "trading_name": "Mokoena Freight",
    "registration_no": "2015/123456/07",
    "vat_no": "4123456789",
    "status": "active",
    "compliance_state": "compliant",
    "kyb_state": "verified",
    "bbbee_level": "2",
    "bbbee_valid_to": "2027-03-31",
    "enterprise_type": "QSE",
    "black_ownership_pct": 100,
    "black_women_ownership_pct": 51,
    "industry_id": "49",
    "company_status": "In Business",
    "website": "https://www.example.co.za",
    "physical_address": "12 Example Street, Johannesburg, 2000",
    "annual_spend": 1250000,
    "aml_result": null,
    "bank_check_result": null,
    "source": "api",
    "date_created": "2026-10-01T08:12:44.000Z",
    "date_updated": "2026-10-20T14:03:10.000Z"
  }
}

POST/api/v1/suppliers/{id}/archive

Archive a supplier

Archive (soft-delete) a supplier. It disappears from lists; history is kept. Scope: write.

Scope write · MCP tool archive_supplier

Parameter	Description
`id` path required	Supplier id

Request

curl -X POST "https://app.trusupplier.co.za/api/v1/suppliers/8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10/archive" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY"

Response 200

{
  "data": {
    "id": "8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10",
    "archived": true
  }
}

Checks

GET/api/v1/checks/types

List check types and prices

Checks you can run on a supplier, with the price in credits (ZAR), plus your available credit balance.

Scope read · MCP tool list_check_types

Request

curl "https://app.trusupplier.co.za/api/v1/checks/types" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY"

Response 200

{
  "data": [
    {
      "id": "K16",
      "name": "Supplier Bundle",
      "price": 180,
      "is_bundle": true
    },
    {
      "id": "K1",
      "name": "Company registration (CIPC)",
      "price": 45,
      "is_bundle": false
    }
  ],
  "available_credits": 2350
}

POST/api/v1/checks/run

Run checks (costs credits)

Run checks on suppliers. COSTS CREDITS. Without confirm=true this only returns a quote (cost, balance, whether you have enough) and charges nothing. Show the quote to the user and only call again with confirm=true once they agree. Needs the run_checks scope. Scope: run_checks.

Scope run_checks · MCP tool run_checks

Parameter	Description
`supplier_ids` body · array required	Supplier ids
`check_types` body · array required	Check type ids from list_check_types
`confirm` body · boolean	true = start the checks and spend the credits. Omit or false = quote only.

Request

curl -X POST "https://app.trusupplier.co.za/api/v1/checks/run" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"supplier_ids": ["8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10"], "check_types": ["K16"], "confirm": true}'

Response 202

{
  "data": {
    "confirmed": true,
    "suppliers": [
      {
        "id": "8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10",
        "legal_name": "Mokoena Logistics (Pty) Ltd"
      }
    ],
    "checks": [
      {
        "id": "K16",
        "name": "Supplier Bundle",
        "price": 180
      }
    ],
    "cost_per_supplier": 180,
    "total_cost": 180,
    "available_credits": 2350,
    "enough_credits": true,
    "started": 1
  }
}

GET/api/v1/checks/results

List check results

Finished check results, newest first. Filter by supplier.

Scope read · MCP tool list_check_results

Parameter	Description
`supplier_id` query	Only this supplier
`check_type_id` query	Only this check type
`limit` query	Max rows, 1-200 (default 50)
`offset` query	Rows to skip (default 0)

Request

curl "https://app.trusupplier.co.za/api/v1/checks/results?supplier_id=8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY"

Response 200

{
  "data": [
    {
      "id": "0b9e6f12-7c3a-4e8d-9a51-2f6c8d4e1b73",
      "supplier_id": "8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10",
      "check_type_id": "K1",
      "result": "pass",
      "checked_at": "2026-10-20T14:02:58.000Z",
      "expires_at": "2027-10-20T14:02:58.000Z",
      "mode": "fresh",
      "scheduled_check_id": null
    }
  ]
}

GET/api/v1/checks/results/{id}

Get a check result

One check result including the provider's detailed answer.

Scope read · MCP tool get_check_result

Parameter	Description
`id` path required	Check result id

Request

curl "https://app.trusupplier.co.za/api/v1/checks/results/8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY"

Response 200

{
  "data": {
    "id": "0b9e6f12-7c3a-4e8d-9a51-2f6c8d4e1b73",
    "supplier_id": "8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10",
    "check_type_id": "K1",
    "result": "pass",
    "checked_at": "2026-10-20T14:02:58.000Z",
    "expires_at": "2027-10-20T14:02:58.000Z",
    "mode": "fresh",
    "scheduled_check_id": null,
    "raw_result": {
      "status": "In Business"
    }
  }
}

GET/api/v1/checks/runs

List check runs

Checks that were requested and their status (requested, running, done, failed).

Scope read · MCP tool list_check_runs

Parameter	Description
`supplier_id` query	Only this supplier
`limit` query	Max rows, 1-200 (default 50)
`offset` query	Rows to skip (default 0)

Request

curl "https://app.trusupplier.co.za/api/v1/checks/runs" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY"

Response 200

{
  "data": [
    {
      "id": "5e2d7b10-4a6c-4f1e-8d3b-9c0a1e2f3b4c",
      "supplier_id": "8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10",
      "check_type_id": "K16",
      "status": "done",
      "reason": "manual",
      "due_at": "2026-10-20T14:00:00.000Z",
      "check_result_id": "0b9e6f12-7c3a-4e8d-9a51-2f6c8d4e1b73",
      "date_created": "2026-10-20T13:59:41.000Z"
    }
  ]
}

Documents

GET/api/v1/documents

List documents

Supplier documents (certificates, letters, statements) on file.

Scope read · MCP tool list_documents

Parameter	Description
`supplier_id` query	Only this supplier
`limit` query	Max rows, 1-200 (default 50)
`offset` query	Rows to skip (default 0)

Request

curl "https://app.trusupplier.co.za/api/v1/documents?supplier_id=8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY"

Response 200

{
  "data": [
    {
      "id": "c41e9a70-1f2b-4d8e-a3c6-5b7e0d9f2a18",
      "supplier_id": "8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10",
      "evidence_type_id": "bbbee_certificate",
      "doc_type_label": "B-BBEE certificate",
      "display_name": "bbbee-2026.pdf",
      "original_filename": "bbbee-2026.pdf",
      "status": "accepted",
      "result": "pass",
      "valid_from": "2026-04-01",
      "expires_on": "2027-03-31",
      "classification_status": "classified",
      "date_created": "2026-10-02T09:00:00.000Z"
    }
  ]
}

POST/api/v1/documents

Upload a document

Upload a supplier document (PDF or image, max 10 MB). REST: multipart/form-data with 'file'. MCP: send content_base64 and filename. The document is filed on the supplier and read automatically. Scope: write.

Scope write · MCP tool upload_document

Parameter	Description
`file` body · file required	PDF or image, up to 10 MB
`supplier_id` body · string required	Supplier id
`evidence_type_id` body · string	Document type id, if known. When set, the document is filed as submitted
`filename` body · string	File name to store, e.g. bbbee.pdf (defaults to the uploaded file name)

Request

curl -X POST "https://app.trusupplier.co.za/api/v1/documents" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY" \
  -F "supplier_id=8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10" \
  -F "evidence_type_id=bbbee_certificate" \
  -F "file=@bbbee-2026.pdf"

Response 201

{
  "data": {
    "id": "c41e9a70-1f2b-4d8e-a3c6-5b7e0d9f2a18",
    "supplier_id": "8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10",
    "evidence_type_id": "bbbee_certificate",
    "doc_type_label": null,
    "display_name": "bbbee-2026.pdf",
    "original_filename": "bbbee-2026.pdf",
    "status": "submitted",
    "result": null,
    "valid_from": null,
    "expires_on": null,
    "classification_status": null,
    "date_created": "2026-10-20T14:10:00.000Z"
  }
}

GET/api/v1/documents/{id}

Get a document

One document's details and the fields read from it. Download the file itself with GET /documents/{id}/file (REST only).

Scope read · MCP tool get_document

Parameter	Description
`id` path required	Document id

Request

curl "https://app.trusupplier.co.za/api/v1/documents/c41e9a70-1f2b-4d8e-a3c6-5b7e0d9f2a18" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY"

Response 200

{
  "data": {
    "id": "c41e9a70-1f2b-4d8e-a3c6-5b7e0d9f2a18",
    "supplier_id": "8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10",
    "doc_type_label": "B-BBEE certificate",
    "status": "accepted",
    "expires_on": "2027-03-31",
    "extracted_fields": {
      "level": "2"
    }
  }
}

GET/api/v1/documents/{id}/file

Download a document file

Download the document file itself. The response is the file (binary) with a Content-Disposition: attachment header, not JSON. REST only.

Scope read

Parameter	Description
`id` path required	Document id

Request

curl "https://app.trusupplier.co.za/api/v1/documents/c41e9a70-1f2b-4d8e-a3c6-5b7e0d9f2a18/file" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY" \
  -o document.pdf

Requests

GET/api/v1/requests

List document requests

Document requests sent to suppliers and their status (queued, sent, opened, submitted, expired).

Scope read · MCP tool list_requests

Parameter	Description
`supplier_id` query	Only this supplier
`status` query	Only this status
`limit` query	Max rows, 1-200 (default 50)
`offset` query	Rows to skip (default 0)

Request

curl "https://app.trusupplier.co.za/api/v1/requests?status=sent" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY"

Response 200

{
  "data": [
    {
      "id": "7a1d3e5f-2b4c-4d6e-8f9a-0b1c2d3e4f5a",
      "supplier_id": "8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10",
      "status": "sent",
      "reason": "missing_documents",
      "sent_at": "2026-10-21T07:30:00.000Z",
      "expires_at": "2026-11-04T07:30:00.000Z",
      "used_at": null,
      "chase_step": 0,
      "date_created": "2026-10-21T07:29:58.000Z"
    }
  ]
}

POST/api/v1/requests/send

Send document requests

Email each supplier one request for everything they still owe (outstanding required documents). This sends real emails to the suppliers' contacts. Scope: write.

Up to 200 suppliers per call. The key's creator must be an owner, admin or compliance officer (otherwise 403). In the response, sent counts requests sent, no_email suppliers with no contact email, nothing suppliers with nothing outstanding, and recent suppliers skipped because a request went out in the last 2 minutes. test is true when email delivery is in test mode.

Scope write · MCP tool send_requests

Parameter	Description
`supplier_ids` body · array required	Supplier ids
`reminder` body · boolean	true = send as a reminder

Request

curl -X POST "https://app.trusupplier.co.za/api/v1/requests/send" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"supplier_ids": ["8f1c2a4e-3b7d-4c55-9e21-6a0d4f7b9c10"], "reminder": false}'

Response 200

{
  "data": {
    "ok": true,
    "sent": 1,
    "no_email": 0,
    "nothing": 0,
    "recent": 0,
    "test": false
  }
}

B-BBEE

GET/api/v1/bbbee/summary

B-BBEE summary

Your suppliers grouped by B-BBEE level, with spend per level and how many certificates are expired or missing.

Scope read · MCP tool get_bbbee_summary

Request

curl "https://app.trusupplier.co.za/api/v1/bbbee/summary" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY"

Response 200

{
  "data": {
    "suppliers": 42,
    "total_spend": 18400000,
    "by_level": {
      "level_1": {
        "suppliers": 6,
        "spend": 5200000
      },
      "level_2": {
        "suppliers": 9,
        "spend": 4100000
      },
      "unknown": {
        "suppliers": 7,
        "spend": 900000
      }
    },
    "certificates_expired": 3,
    "level_unknown": 7,
    "black_owned_51": 18,
    "black_women_owned_30": 9
  }
}

Billing

GET/api/v1/billing/balance

Credit balance

Your credit wallet: balance, amount reserved for running checks, and what's available.

Scope read · MCP tool get_balance

Request

curl "https://app.trusupplier.co.za/api/v1/billing/balance" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY"

Response 200

{
  "data": {
    "balance": 2500,
    "reserved": 150,
    "available": 2350,
    "currency": "ZAR",
    "low_balance_threshold": 200,
    "auto_topup_enabled": false
  }
}

GET/api/v1/billing/transactions

Credit transactions

Credit wallet transactions (top-ups, check charges), newest first.

Scope read · MCP tool list_transactions

Parameter	Description
`limit` query	Max rows, 1-200 (default 50)
`offset` query	Rows to skip (default 0)

Request

curl "https://app.trusupplier.co.za/api/v1/billing/transactions?limit=20" \
  -H "Authorization: Bearer $TRUSUPPLIER_API_KEY"

Response 200

{
  "data": [
    {
      "id": "e3c19b2d-6f4a-4b8c-9d1e-2a3b4c5d6e7f",
      "type": "debit",
      "amount": -180,
      "reason": "check K16",
      "ref": null,
      "balance_after": 2320,
      "scheduled_check_id": "5e2d7b10-4a6c-4f1e-8d3b-9c0a1e2f3b4c",
      "check_result_id": null,
      "date_created": "2026-10-20T14:03:00.000Z"
    }
  ]
}