---
title: "Create customer agreements"
method: POST
path: "/platform/v2/agreements"
tags: ["Agreements"]
---

# Create customer agreements

`POST /platform/v2/agreements`

## Request

- Base URL: `https://api.sandbox.bvnk.com`
- URL: `https://api.sandbox.bvnk.com/platform/v2/agreements`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/docs/platform/v2/agreements/post.ts> (a function with typed inputs; its response is checked against the schema)

Create an agreement working set for a prospective customer (before a customer record exists). Identified by a partner-supplied `reference` that must be unique within the caller's account.

After the agreements are accepted, create the customer with [Create customer](/bvnk/api-explorer/endpoints/create-customer-v-2) using the same `reference`. The response includes a hosted `signingUrl` you can share with the applicant to sign the agreements.

Your account must be enabled for the requested customer type and model; otherwise the request is rejected with `403`.

:::warning
Before calling this endpoint, make sure you are not onboarding customers from restricted jurisdictions. For more information, see [BVNK Acceptable Use Policy](https://help.bvnk.com/hc/en-us/articles/11100445499666-BVNK-Acceptable-Use-Policy-Financial-Crime).
:::

## Headers

- `Idempotency-Key` string, uuid, required

## Request body

- object
  - `reference` string, required: Partner-supplied identifier for the agreement working set. Must be unique within the caller's account and will later be used to retrieve, bulk-respond to, or bind the working set to a customer.
  - `useCase` 'STABLECOIN_PAYOUTS' | 'EMBEDDED_STABLECOIN_WALLETS' | 'EMBEDDED_FIAT_ACCOUNTS' | 'SELF_CUSTODY', required: Type of product to which the customer agreement applies.
  - `customerType` 'COMPANY' | 'INDIVIDUAL', required: Type of customer the working set is being prepared for.
  - `countryCode` string, required: Country code of the customer's address in the ISO 3166-1 alpha-2 format.
  - `model` 'EMBEDDED' | 'RELIANCE': Onboarding model. Set to `RELIANCE` for Partner-Managed onboarding to receive the correct agreement set. If omitted, defaults to `EMBEDDED` (BVNK-Managed) only when the account is enabled exclusively for the embedded model. Otherwise, specify the model explicitly.
  - `customerName` string: Display name of the prospective customer. Saved to the customer when it is created.
  - `applicantEmail` string, email: Email address of the customer the working set is being prepared for. Required for self-custody wallets.

## Response `201`

Agreement working set created

- V2PreCustomerAgreementsResponse: Agreement working set returned by the create and list-by-reference endpoints.
  - `id` string, uuid: Unique identifier of the customer.
  - `reference` string: Partner-supplied identifier that scopes the working set.
  - `agreements` V2PreCustomerAgreement[]: Agreements in the working set.
    - `id` string, uuid: Unique identifier of the customer agreement entry.
    - `name` string: Human-readable agreement title.
    - `description` string: Short summary of what the agreement covers.
    - `declinable` boolean: Whether the customer may reject the agreement. When `false`, only `ACCEPT` is valid.
    - `status` 'PENDING' | 'ACCEPTED' | 'REJECTED': Current state of the agreement entry.
    - `respondedAt` string, date-time: Timestamp at which the customer responded. Absent while `status` is `PENDING`.
  - `signingUrl` string: URL where the customer can review and sign the agreements.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Your account is not enabled for the requested customer type or model.
- `409`: Idempotency-Key reused with a different payload, or `reference` is already bound to an existing customer.
- `429`: A request with the same `Idempotency-Key` is still being processed. Retry after it completes.
- `502`: The agreements upstream is temporarily unavailable.

## Changes

- **2026-11-06** `c386d436bf2c`: 2 breaking, 1 warning, 7 info
  - added the pattern `^[A-Z]{2}$` to the request property `countryCode`
  - removed the success response with the status `200`
  - the `reference` request property's maxLength was set to `36`
  - added the new optional request property `applicantEmail`
  - …6 more
- **2026-06-16** `97d6c0d2fe2e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/changes/platform/v2/agreements/post.md)

---

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