Skip to content
VestiarionDocs

API reference

Add a counterparty

POST/api/v1/counterparties

Adds a vendor, contractor or client, checked by the rules of the console's form and screened as one added there: the answer's riskLevel is the screening's verdict, or unscreened when screening could not finish. It is recorded in the ledger as create_counterparty with via: "api" and the key's id.

An address added through the API waits for a person. The agent pays nothing to it until an owner, admin or approver confirms it on Counterparties, so a key can add records but cannot point the agent's payments at a new address.

Send a workspace API key with read and write access as Authorization: Bearer …. A read-only key gets 403.

Parameters

  • Idempotency-Keystringoptionalin: header

    Makes a retry safe: up to 255 printable ASCII characters, unique to the record being added, such as its id in your own system. A repeat with the same key and the same body within 24 hours gets the first answer back, with Idempotent-Replayed: true, and adds nothing. The same key with a different body answers 409.

Request body

Example
application/json
{
  "name": "API Test Vendor",
  "role": "vendor",
  "address": "0x6b3A4C65f362b818bb7FD6f999477A03CE07e51a",
  "paymentLimit": "1"
}
Fields
  • namestring

    2 to 160 characters.

  • rolestring

    vendor or contractor, whom the business pays, or client, who pays the business.

    One ofvendorclientcontractor

  • addressstring · optional

    Where the agent pays it. An address added through the API waits for a person in the workspace to confirm it on Counterparties; until then the agent pays nothing to it.

  • chainstring · optional

    The chain the address receives on. Defaults to ARC-TESTNET; only a vendor can be paid on another chain.

    One ofARC-TESTNETBASE-SEPOLIAARB-SEPOLIAETH-SEPOLIA

  • jurisdictionstring · optional

    Where it is based, up to 80 characters; screening uses it.

  • paymentLimitstring | number · optional

    The most the agent pays it in one payment, in USDC, with up to 6 decimal places. Required for a vendor or a contractor.

  • noticeEmailstring · optional

    Where it is emailed once a payment to it is confirmed.

Try it

Try it is off for operations that add records: run the sample with your own key.

Code samples

cURL
curl "https://www.vestiarion.xyz/api/v1/counterparties" \
  -X POST \
  -H "Authorization: Bearer $VESTIARION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-vendor-1042" \
  -d '{"name":"API Test Vendor","role":"vendor","address":"0x6b3A4C65f362b818bb7FD6f999477A03CE07e51a","paymentLimit":"1"}'

Response

Example
201 · application/json
{
  "data": {
    "id": "6b361405-cfda-4400-a286-364b561911ce",
    "name": "API Test Vendor",
    "role": "vendor",
    "address": "0x6b3A4C65f362b818bb7FD6f999477A03CE07e51a",
    "chain": "ARC-TESTNET",
    "jurisdiction": null,
    "riskLevel": "clear",
    "riskNotes": "OpenSanctions returned no matching entity",
    "baselinePaymentLimit": 1,
    "paymentLimit": 1,
    "lastScreenedAt": "2026-10-03T10:15:29.759+00:00",
    "performanceScore": null,
    "performanceInputs": null,
    "createdAt": "2026-10-03T10:15:26.865688+00:00"
  }
}
Fields
  • dataobject

    A vendor, client or contractor, with its risk tier and payment limits.

    14 fields in data
    • idstring
    • namestring
    • rolestring

      One ofvendorclientcontractor

    • addressstring · nullable
    • chainstring · nullable
    • jurisdictionstring · nullable
    • riskLevelstring

      One ofunscreenedclearmediumhigh

    • riskNotesstring · nullable
    • baselinePaymentLimitnumber · nullable

      The business's baseline payment limit for this counterparty.

    • paymentLimitnumber · nullable

      The current payment limit, derived from the risk tier.

    • lastScreenedAtstring · nullable
    • performanceScorenumber · nullable

      No history is different from a zero score and remains null.

    • performanceInputsobject · nullable
    • createdAtstring

Errors

StatusCodeWhen
400invalid_requestAn invalid limit or cursor, a filter value outside its allowed values, or a request body that does not validate. The message names the parameter or the field, and lists the accepted values.
401unauthorizedNo key, or a malformed, unknown or revoked one: "A valid API key is required."
403forbiddenThe key's scopes do not cover this route: "This key cannot do that." Or, on a write, the person who created the key can no longer add records: "This key's issuer can no longer add records in this workspace."
409conflictThe Idempotency-Key was already used for a different request, or the first request with it is still being handled.
429rate_limitedToo many requests; wait as long as Retry-After says before trying again.
500internalAn unexpected server error. Implementation details are not exposed.