# Create a payee link

`POST /api/v1/payee-links`

Makes a one-time link where a vendor or contractor enters the address they are paid at, recorded in the ledger as `payee_link_created` with `via: "api"` and the key's id. Send `url` to the payee yourself. It is in this answer only, since Vestiarion keeps just its hash, and the answer is sent with `Cache-Control: no-store`. The link works once and expires after 7 days.

The address the payee enters waits for a person in the workspace to confirm it on Counterparties; until then the agent pays nothing to it. Making a link revokes the payee's unused one, so only the newest works. For the same reason this operation keeps no outcome for an `Idempotency-Key`, which would store the link: a repeat makes a new link. A `counterpartyId` the workspace does not hold, or a client's, answers `400`.

Send a [workspace API key](https://www.vestiarion.xyz/docs/get-started/authentication) with read and write access as `Authorization: Bearer <key>`. A read-only key gets `403`.

## Parameters

No parameters.

## Request body

Example, `application/json`:

```json
{
  "counterpartyId": "26d6ffed-356d-474a-8d42-89bc942f6b4e"
}
```

**Fields**

- `counterpartyId` (string, required): The `id` of the vendor or contractor who is to enter the address they are paid at. A client gets no link: the agent never pays one.

## Code samples

```bash
curl "https://www.vestiarion.xyz/api/v1/payee-links" \
  -X POST \
  -H "Authorization: Bearer $VESTIARION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"counterpartyId":"26d6ffed-356d-474a-8d42-89bc942f6b4e"}'
```

## Response

Example, `201` `application/json`:

```json
{
  "data": {
    "id": "0810c2f3-dc6b-487e-aff5-63297ad33813",
    "counterpartyId": "26d6ffed-356d-474a-8d42-89bc942f6b4e",
    "url": "https://www.vestiarion.xyz/payee/vxp_avUyHXYqUlnt1OMB323j4N6Xv3H5lKzjZRNvbm1hfc4",
    "expiresAt": "2026-10-10T15:42:04.28+00:00"
  }
}
```

**Fields**

- `data` (object, required): A one-time link for a payee to enter the address they are paid at. That address waits for a person in the workspace to confirm it before the agent pays to it.
  - `id` (string, required): The link's own id. It is not the link: that is `url`.
  - `counterpartyId` (string, required)
  - `url` (string, required): The one-time page where the payee enters their address. It is in this answer only: Vestiarion keeps just its hash. Send it to the payee yourself.
  - `expiresAt` (string, required): When the link stops working, 7 days after it was made. It also stops once the payee has used it, or a newer link replaces it.

## Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_request` | An 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. |
| 401 | `unauthorized` | No key, or a malformed, unknown or revoked one: "A valid API key is required." |
| 403 | `forbidden` | The 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." |
| 429 | `rate_limited` | Too many requests; wait as long as `Retry-After` says before trying again. |
| 500 | `internal` | An unexpected server error. Implementation details are not exposed. |