BVbvnk
Agreements

Create customer agreements

Changed on

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 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. :::

post/platform/v2/agreements

Request

Headers

Idempotency-Keystring uuid required
Example:1e74002e-74a1-48fd-b707-147c3187a3e1

Client-generated unique identifier for the request in UUID format. Ensures that retried requests are not processed more than once.

Request body

referencestring 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.

countryCodestring 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.

customerNamestring

Display name of the prospective customer. Saved to the customer when it is created.

applicantEmailstring email

Email address of the customer the working set is being prepared for. Required for self-custody wallets.

Response

Agreement working set created

idstring uuid

Unique identifier of the customer.

referencestring

Partner-supplied identifier that scopes the working set.

signingUrlstring

URL where the customer can review and sign the agreements.

Changes

  • c386d436bf2cRevision changes
    • breaking

      added the pattern ^[A-Z]{2}$ to the request property

    • breaking

      removed the success response with the status

    • warning

      the request property's maxLength was set to 36

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new SELF_CUSTODY enum value to the request property

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the success response with the status

  • 97d6c0d2fe2eRevision changes
    • info

      endpoint added