API reference

Supplier risk

What needs a look about each supplier: bank details, sanctions screening and missing documents.

More about this resource

Pleaxy keeps three checks on each of a buyer's suppliers and sums them up as a level: ok, attention or blocked. Bank details: the account each invoice asks to be paid to is kept on file per billing lane, and an invoice that names a new or different account waits for a person's approval before it can be exported for payment. Sanctions screening: when switched on, the supplier's names are screened against the OFAC, EU, UK and UN lists, and payments wait while a possible match is reviewed. Questionnaires: flagged answers and missing documents. These endpoints only read. Approving a bank account and deciding on a screening match are done by a signed-in person in Pleaxy.

List supplier risk

Lists each supplier's risk level and the checks behind it.

GET/v1/workspaces/{regionId}/supplier-risk

Returns

200 OK with the object shown in the response.

More details

Returns every supplier's level with its rows: bank, screening, flaggedAnswers and missingDocuments, each with a state of ok, attention, blocked or none. In this list a screening that isn't flagged shows as none; read one supplier with GetSupplierRisk for its full bank and screening status.

Needs 'view' access to suppliers.

Response fields

  • level"ok" | "attention" | "blocked"

    The most serious state among the rows the workspace counts toward it. blocked means a confirmed sanctions match. It is a level, never a score.

  • bankobject

    The supplier's bank accounts on file: waiting counts the accounts waiting for approval.

  • screeningobject

    The supplier's sanctions screening: its status and when it was last checked. status is off while screening isn't switched on.

  • flaggedAnswersobject

    How many of the supplier's questionnaire answers are flagged for review.

  • missingDocumentsobject

    The labels of the required questionnaire documents the supplier hasn't provided.

Errors

  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/supplier-risk
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/supplier-risk" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
[
   {
      "connectionId": "string",
      "supplierName": "string",
      "level": "ok" | "attention" | "blocked",
      "bank": { "state": "ok" | "attention" | "blocked" | "none", "waiting": number, "status": "none" | "approved" | "waiting" | "changing" },
      "screening": { "state": "ok" | "attention" | "blocked" | "none", "status": "off" | "not_screened" | "clear" | "possible_match" | "confirmed_match", "checkedAt": "string" },
      "flaggedAnswers": { "state": "ok" | "attention" | "blocked" | "none", "count": number },
      "missingDocuments": { "state": "ok" | "attention" | "blocked" | "none", "fields": [ "string" ] }
   }
]

Get supplier risk

Gets one supplier's risk level and the checks behind it.

GET/v1/workspaces/{regionId}/supplier-risk/{connectionId}

Parameters

  • connectionIdstringRequired

    The supplier's connection id in this workspace.

Returns

200 OK with the object shown in the response.

More details

Returns one supplier's risk as ListSupplierRisk does, with bank.status and the screening's status and checkedAt filled in.

Needs 'view' access to suppliers.

Response fields

  • level"ok" | "attention" | "blocked"

    The most serious state among the rows the workspace counts toward it. blocked means a confirmed sanctions match. It is a level, never a score.

  • bankobject

    The supplier's bank accounts on file: waiting counts the accounts waiting for approval.

  • screeningobject

    The supplier's sanctions screening: its status and when it was last checked. status is off while screening isn't switched on.

  • flaggedAnswersobject

    How many of the supplier's questionnaire answers are flagged for review.

  • missingDocumentsobject

    The labels of the required questionnaire documents the supplier hasn't provided.

Errors

  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/supplier-risk/{connectionId}
Request
GET /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/supplier-risk/SC-1A2B3C4D
Response · 200 OK
{
   "connectionId": "SC-1A2B3C4D",
   "supplierName": "Northwind Hosting",
   "level": "attention",
   "bank": { "state": "attention", "waiting": 1, "status": "changing" },
   "screening": { "state": "ok", "status": "clear", "checkedAt": "2026-11-10T06:00:00.000Z" },
   "flaggedAnswers": { "state": "ok", "count": 0 },
   "missingDocuments": { "state": "ok", "fields": [] }
}

List bank accounts to approve

Lists the suppliers' bank accounts waiting for a person's approval.

GET/v1/workspaces/{regionId}/bank-accounts/review

Returns

200 OK with the object shown in the response.

More details

Returns the bank accounts that wait for approval: a billing lane's first account (status unverified), or a change to an approved one (status changing, with pendingChange). Invoices to be paid to them wait until a person approves them.

Needs 'view' access to invoices. Approving an account, rejecting a change and showing the full numbers are done by a signed-in person in Pleaxy.

Response fields

  • laneKeystring

    The billing lane the account belongs to: one payee and currency of this supplier.

  • detailsobject

    The payment details on file, with the account numbers masked to the last four characters.

  • status"unverified" | "verified" | "changing"

    unverified: the lane's first account, waiting for approval. verified: approved. changing: an invoice named other details, kept in pendingChange until a person approves or rejects them.

  • approvalobject

    How the account was approved. verification is supplier_confirmed, buyer_approved or paid_before, and check.method is how the buyer checked it.

  • historyArray<object>

    The account's most recent events, with the account number masked.

Errors

  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/bank-accounts/review
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/bank-accounts/review" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
[
   {
      "id": "string",
      "connectionId": "string",
      "supplierName": "string",
      "supplierKey": "string",
      "laneKey": "string",
      "payeeName": "string",
      "currency": "string",
      "details": { "method": "bank_transfer" | "wire" | "ach" | "check" | "other", "payeeName": "string", "bankName": "string", "iban": "string", "accountNumber": "string", "bic": "string", "routingNumber": "string", "mailingAddress": "string", "paymentReference": "string", "notes": "string" },
      "status": "unverified" | "verified" | "changing",
      "learnedFrom": { "invoiceId": "string", "side": "buyer" | "supplier" },
      "approval": {
         "verification": "supplier_confirmed" | "buyer_approved" | "paid_before",
         "at": "string",
         "by": { "sub": "string", "name": "string", "side": "buyer" | "supplier" },
         "check": { "method": "call" | "email" | "bank_letter" | "supplier_portal" | "other" | "none", "detail": "string", "note": "string" },
         "invoiceId": "string"
      },
      "pendingChange": { "details": { ... }, "invoiceId": "string", "side": "buyer" | "supplier", "at": "string" },
      "history": [
         { "at": "string", "event": "learned" | "seeded" | "approved" | "change_proposed" | "change_rejected", "masked": "string", "invoiceId": "string", "by": "string" }
      ],
      "version": number,
      "createdAt": "string",
      "updatedAt": "string"
   }
]

List supplier bank accounts

Lists one supplier's bank accounts on file, with how each was approved.

GET/v1/workspaces/{regionId}/bank-accounts/suppliers/{connectionId}

Parameters

  • connectionIdstringRequired

    The supplier's connection id in this workspace.

Returns

200 OK with the object shown in the response.

More details

Returns a supplier's bank accounts on file, one per billing lane (a payee and currency), with each account's status, how it was approved and its last 10 events.

Needs 'view' access to invoices. Approving an account, rejecting a change and showing the full numbers are done by a signed-in person in Pleaxy.

Response fields

  • laneKeystring

    The billing lane the account belongs to: one payee and currency of this supplier.

  • detailsobject

    The payment details on file, with the account numbers masked to the last four characters.

  • status"unverified" | "verified" | "changing"

    unverified: the lane's first account, waiting for approval. verified: approved. changing: an invoice named other details, kept in pendingChange until a person approves or rejects them.

  • approvalobject

    How the account was approved. verification is supplier_confirmed, buyer_approved or paid_before, and check.method is how the buyer checked it.

  • historyArray<object>

    The account's most recent events, with the account number masked.

Errors

  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/bank-accounts/suppliers/{connectionId}
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/bank-accounts/suppliers/{connectionId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
[
   {
      "id": "string",
      "connectionId": "string",
      "supplierName": "string",
      "supplierKey": "string",
      "laneKey": "string",
      "payeeName": "string",
      "currency": "string",
      "details": { "method": "bank_transfer" | "wire" | "ach" | "check" | "other", "payeeName": "string", "bankName": "string", "iban": "string", "accountNumber": "string", "bic": "string", "routingNumber": "string", "mailingAddress": "string", "paymentReference": "string", "notes": "string" },
      "status": "unverified" | "verified" | "changing",
      "learnedFrom": { "invoiceId": "string", "side": "buyer" | "supplier" },
      "approval": {
         "verification": "supplier_confirmed" | "buyer_approved" | "paid_before",
         "at": "string",
         "by": { "sub": "string", "name": "string", "side": "buyer" | "supplier" },
         "check": { "method": "call" | "email" | "bank_letter" | "supplier_portal" | "other" | "none", "detail": "string", "note": "string" },
         "invoiceId": "string"
      },
      "pendingChange": { "details": { ... }, "invoiceId": "string", "side": "buyer" | "supplier", "at": "string" },
      "history": [
         { "at": "string", "event": "learned" | "seeded" | "approved" | "change_proposed" | "change_rejected", "masked": "string", "invoiceId": "string", "by": "string" }
      ],
      "version": number,
      "createdAt": "string",
      "updatedAt": "string"
   }
]

Get invoice bank account

Says whether an invoice's payment waits on its supplier's bank account.

GET/v1/workspaces/{regionId}/invoices/{invoiceId}/bank-account

Parameters

  • invoiceIdstringRequired

    The invoice's id, e.g. INV-7F3A9C21.

  • buyerstring

    For a supplier caller, the buyer the invoice belongs to, as in GetInvoice.

Returns

200 OK with the object shown in the response.

More details

Says whether this invoice waits on its supplier's bank account. hold is first_payment when the billing lane's account isn't approved yet, differs_from_file when the invoice names other details than the approved account, and absent when the invoice can be paid. While it holds, the invoice can't be exported for payment; recording a payment made elsewhere and paying through Pleaxy are not held.

Needs 'view' access to invoices. A supplier caller gets hold only.

Response fields

  • hold"first_payment" | "differs_from_file"

    Why the payment waits. Absent when it doesn't.

  • accountobject

    The billing lane's account on file, with the numbers masked to the last four characters.

Errors

  • 404 Not Found - No invoice with this id that the caller can see.
  • 409 Conflict - Supplier callers only. Code INVOICE_ID_AMBIGUOUS: more than one of your buyers holds an invoice from you with this id (ids are unique only within a buyer), so Pleaxy won't guess which one you mean. Nothing is read or changed. The body's buyers lists each buyer's Workspace ID and name: repeat the call with ?buyer=<that Workspace ID>.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/invoices/{invoiceId}/bank-account
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/invoices/{invoiceId}/bank-account" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "hold": "first_payment" | "differs_from_file",
   "account": {
      "id": "string",
      "connectionId": "string",
      "supplierName": "string",
      "supplierKey": "string",
      "laneKey": "string",
      "payeeName": "string",
      "currency": "string",
      "details": { "method": "bank_transfer" | "wire" | "ach" | "check" | "other", "payeeName": "string", "bankName": "string", "iban": "string", "accountNumber": "string", "bic": "string", "routingNumber": "string", "mailingAddress": "string", "paymentReference": "string", "notes": "string" },
      "status": "unverified" | "verified" | "changing",
      "learnedFrom": { "invoiceId": "string", "side": "buyer" | "supplier" },
      "approval": {
         "verification": "supplier_confirmed" | "buyer_approved" | "paid_before",
         "at": "string",
         "by": { "sub": "string", "name": "string", "side": "buyer" | "supplier" },
         "check": { "method": "call" | "email" | "bank_letter" | "supplier_portal" | "other" | "none", "detail": "string", "note": "string" },
         "invoiceId": "string"
      },
      "pendingChange": { "details": { ... }, "invoiceId": "string", "side": "buyer" | "supplier", "at": "string" },
      "history": [
         { "at": "string", "event": "learned" | "seeded" | "approved" | "change_proposed" | "change_rejected", "masked": "string", "invoiceId": "string", "by": "string" }
      ],
      "version": number,
      "createdAt": "string",
      "updatedAt": "string"
   },
   "supplierKey": "string"
}

List screening matches

Lists the suppliers whose sanctions screening has a match to review or a confirmed one.

GET/v1/workspaces/{regionId}/screening/review

Returns

200 OK with the object shown in the response.

More details

Returns the suppliers whose screening status is possible_match or confirmed_match. Payments to them wait, and a supplier with a confirmed match takes no new orders or buyer-entered invoices. The list is empty while screening is off. A match is a resemblance between names for a person to review, not a finding that the supplier is sanctioned.

Needs 'view' access to suppliers. Dismissing or confirming a match is done by a signed-in person in Pleaxy.

Response fields

  • status"not_screened" | "clear" | "possible_match" | "confirmed_match"

    possible_match: at least one match is waiting for a person's review. confirmed_match: a person confirmed that the supplier is the listed party.

  • subjectsArray<object>

    The names that were screened: the supplier's name, an earlier name, and the payees of its bank accounts.

  • listVersionsobject

    The version of each sanctions list the supplier was last screened against.

  • matchesArray<object>

    Each listed entry a screened name resembles: the list, the entry's names, countries and programmes, and the score. state is open until a person dismisses or confirms it, with who decided and why. closed means the entry left the list or no longer matches.

Errors

  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/screening/review
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/screening/review" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
[
   {
      "connectionId": "string",
      "supplierKey": "string",
      "supplierName": "string",
      "status": "not_screened" | "clear" | "possible_match" | "confirmed_match",
      "checkedAt": "string",
      "listVersions": { "ofac": "string", "eu": "string", "uk": "string", "un": "string" },
      "subjects": [ { "role": "name" | "former_name" | "payee", "name": "string" } ],
      "countries": [ "string" ],
      "matches": [
         {
            "id": "string",
            "entryId": "string",
            "list": "ofac" | "eu" | "uk" | "un" | "jurisdiction",
            "entryName": "string",
            "matchedName": "string",
            "subject": { "role": "name" | "former_name" | "payee", "name": "string" },
            "score": number,
            "countryMismatch": boolean,
            "entry": { "kind": "entity" | "individual" | "other", "names": [ "string" ], "countries": [ "string" ], "programmes": [ "string" ], "listedOn": "string" },
            "state": "open" | "dismissed" | "confirmed" | "closed",
            "foundAt": "string",
            "decidedAt": "string",
            "decidedBy": { "sub": "string", "name": "string" },
            "reason": "string",
            "closedReason": "entry_removed" | "no_longer_matches"
         }
      ],
      "history": [ { "at": "string", "event": "screened" | "dismissed" | "confirmed" | "reopened" | "closed", "matchId": "string", "by": "string" } ],
      "version": number
   }
]

Get supplier screening

Gets one supplier's sanctions screening and its matches.

GET/v1/workspaces/{regionId}/screening/suppliers/{connectionId}

Parameters

  • connectionIdstringRequired

    The supplier's connection id in this workspace.

Returns

200 OK with the object shown in the response.

More details

Returns whether screening is switched on and, when the supplier has been screened, its screening: the names screened, the list versions and each match with its state.

Needs 'view' access to suppliers. Dismissing or confirming a match is done by a signed-in person in Pleaxy.

Response fields

  • enabledboolean

    Whether sanctions screening is switched on.

  • status"not_screened" | "clear" | "possible_match" | "confirmed_match"

    possible_match: at least one match is waiting for a person's review. confirmed_match: a person confirmed that the supplier is the listed party.

  • subjectsArray<object>

    The names that were screened: the supplier's name, an earlier name, and the payees of its bank accounts.

  • listVersionsobject

    The version of each sanctions list the supplier was last screened against.

  • matchesArray<object>

    Each listed entry a screened name resembles: the list, the entry's names, countries and programmes, and the score. state is open until a person dismisses or confirms it, with who decided and why. closed means the entry left the list or no longer matches.

Errors

  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/screening/suppliers/{connectionId}
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/screening/suppliers/{connectionId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "enabled": boolean,
   "screening": {
      "connectionId": "string",
      "supplierKey": "string",
      "supplierName": "string",
      "status": "not_screened" | "clear" | "possible_match" | "confirmed_match",
      "checkedAt": "string",
      "listVersions": { "ofac": "string", "eu": "string", "uk": "string", "un": "string" },
      "subjects": [ { "role": "name" | "former_name" | "payee", "name": "string" } ],
      "countries": [ "string" ],
      "matches": [
         {
            "id": "string",
            "entryId": "string",
            "list": "ofac" | "eu" | "uk" | "un" | "jurisdiction",
            "entryName": "string",
            "matchedName": "string",
            "subject": { "role": "name" | "former_name" | "payee", "name": "string" },
            "score": number,
            "countryMismatch": boolean,
            "entry": { "kind": "entity" | "individual" | "other", "names": [ "string" ], "countries": [ "string" ], "programmes": [ "string" ], "listedOn": "string" },
            "state": "open" | "dismissed" | "confirmed" | "closed",
            "foundAt": "string",
            "decidedAt": "string",
            "decidedBy": { "sub": "string", "name": "string" },
            "reason": "string",
            "closedReason": "entry_removed" | "no_longer_matches"
         }
      ],
      "history": [ { "at": "string", "event": "screened" | "dismissed" | "confirmed" | "reopened" | "closed", "matchId": "string", "by": "string" } ],
      "version": number
   }
}
Talk to us