---
title: "Add a counterparty"
method: POST
path: "/api/v1/counterparties"
tags: ["Counterparties"]
---

# Add a counterparty

`POST /api/v1/counterparties`

## Request

- Base URL: `https://www.vestiarion.xyz`
- URL: `https://www.vestiarion.xyz/api/v1/counterparties`
- Auth: HTTP bearer

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.

## Headers

- `Idempotency-Key` string

## Request body

- CreateCounterpartyRequest: A counterparty to add. It is screened as one added in the console.
  - `name` string, required: 2 to 160 characters.
  - `role` 'vendor' | 'client' | 'contractor', required: `vendor` or `contractor`, whom the business pays, or `client`, who pays the business.
  - `address` string: 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.
  - `chain` 'ARC-TESTNET' | 'BASE-SEPOLIA' | 'ARB-SEPOLIA' | 'ETH-SEPOLIA' | 'ARC' | 'BASE': The chain the address receives on. Defaults to the workspace's own chain: `ARC-TESTNET` on Arc testnet, `ARC` on Arc mainnet. Only a chain the workspace's network pays on is accepted (on Arc mainnet, `BASE` besides its own), and only a vendor can be paid on another chain than the workspace's own.
  - `jurisdiction` string: Where it is based, up to 80 characters; screening uses it.
  - `paymentLimit` union: The most the agent pays it in one payment, in USDC, with up to 6 decimal places. Required for a vendor or a contractor.
    - string
    - number
  - `noticeEmail` string: Where it is emailed once a payment to it is confirmed.

## Response `201`

Created

- CreateCounterpartyResponse
  - `data` object, required: A vendor, client or contractor, with its risk tier and payment limits.
    - `id` string, required
    - `name` string, required
    - `role` 'vendor' | 'client' | 'contractor', required
    - `address` string, nullable, required
    - `chain` string, nullable, required
    - `jurisdiction` string, nullable, required
    - `riskLevel` 'unscreened' | 'clear' | 'medium' | 'high', required
    - `riskNotes` string, nullable, required
    - `baselinePaymentLimit` number, nullable, required: The business's baseline payment limit for this counterparty.
    - `paymentLimit` number, nullable, required: The current payment limit, derived from the risk tier.
    - `lastScreenedAt` string, nullable, required
    - `performanceScore` number, nullable, required: No history is different from a zero score and remains null.
    - `performanceInputs` object, nullable, required
    - `createdAt` string, required

## Other responses

- `400`: invalid_request
- `401`: unauthorized
- `403`: forbidden
- `409`: conflict
- `429`: rate_limited
- `500`: internal

---

[API](https://skmtc.dev/vestiarion/apis/vestiarion-api.md) · [All operations](https://skmtc.dev/vestiarion/apis/vestiarion-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vestiarion/apis/vestiarion-api/revisions/fd2f589dac9b?raw)