---
title: "Create contact"
method: POST
path: "/platform/v3/contacts"
tags: ["Contacts"]
---

# Create contact

`POST /platform/v3/contacts`

## Request

- Base URL: `https://api.sandbox.bvnk.com`
- URL: `https://api.sandbox.bvnk.com/platform/v3/contacts`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/docs/platform/v3/contacts/post.ts> (a function with typed inputs; its response is checked against the schema)

:::warning Beta
Contacts v3 is in beta and may change as we continue to improve it. Please review the documentation and endpoints carefully, test everything in the sandbox, and reach out to the Solutions team if you need help.
:::

Creates a new contact that can be referenced in payment requests instead of supplying inline party details. Contacts store originator or beneficiary information required for Travel Rule compliance.

A contact can represent either an `INDIVIDUAL` (natural person) or a `COMPANY` (legal entity). Once created, reference the returned `id` as `contactId` when creating payment links, channels, or payouts.

## Request body

- V3CreateContactRequest: Request body for creating or updating a contact.
  - `description` string: A human-readable label for the contact.
  - `category` 'DEFAULT': Contact category.
  - `entity` union, required: Entity details. Use `type` to distinguish between `INDIVIDUAL` and `COMPANY` contacts.
    - V3ContactIndividualEntity: Entity details for an individual (natural person) contact.
      - `type` 'INDIVIDUAL', required: Entity type. Use `INDIVIDUAL` for natural persons.
      - `relationshipType` 'THIRD_PARTY' | 'SELF_OWNED', required: Relationship of the contact to your account. - `THIRD_PARTY`: The contact is a separate entity (e.g., a customer or supplier). - `SELF_OWNED`: The contact represents your own organisation.
      - `firstName` string, required: First name of the individual.
      - `middleName` string: Middle name of the individual. Optional.
      - `lastName` string, required: Last name of the individual.
      - `dateOfBirth` string, date: Date of birth in `YYYY-MM-DD` format.
      - `address` V3ContactAddress: Postal address of the contact.
        - `addressLine1` string: First line of the street address.
        - `addressLine2` string: Second line of the street address. Optional.
        - `city` string: City or locality.
        - `region` string: Region, state, or province.
        - `stateCode` string: If the address is in the US, provide the two-letter state code, for example, NY.
        - `postalCode` string: Postal or ZIP code.
        - `country` string: ISO 3166-1 alpha-2 country code.
    - V3ContactCompanyEntity: Entity details for a company (legal entity) contact.
      - `type` 'COMPANY', required: Entity type. Use `COMPANY` for legal entities.
      - `relationshipType` 'THIRD_PARTY' | 'SELF_OWNED', required: Relationship of the contact to your account. - `THIRD_PARTY`: The contact is a separate entity (e.g., a customer or supplier). - `SELF_OWNED`: The contact represents your own organisation.
      - `legalName` string, required: Registered legal name of the company.
      - `registrationNumber` string: Company registration number.
      - `dateOfIncorporation` string, date: Date of incorporation in `YYYY-MM-DD` format.
      - `address` V3ContactAddress: Postal address of the contact.
        - `addressLine1` string: First line of the street address.
        - `addressLine2` string: Second line of the street address. Optional.
        - `city` string: City or locality.
        - `region` string: Region, state, or province.
        - `stateCode` string: If the address is in the US, provide the two-letter state code, for example, NY.
        - `postalCode` string: Postal or ZIP code.
        - `country` string: ISO 3166-1 alpha-2 country code.

## Response `201`

Contact created

- V3ContactResponse: A contact record.
  - `id` string, uuid: Unique identifier of the contact.
  - `description` string: A human-readable label for the contact.
  - `category` string: Contact category.
  - `entity` union: Entity details of the contact.
    - V3ContactIndividualEntity: Entity details for an individual (natural person) contact.
      - `type` 'INDIVIDUAL', required: Entity type. Use `INDIVIDUAL` for natural persons.
      - `relationshipType` 'THIRD_PARTY' | 'SELF_OWNED', required: Relationship of the contact to your account. - `THIRD_PARTY`: The contact is a separate entity (e.g., a customer or supplier). - `SELF_OWNED`: The contact represents your own organisation.
      - `firstName` string, required: First name of the individual.
      - `middleName` string: Middle name of the individual. Optional.
      - `lastName` string, required: Last name of the individual.
      - `dateOfBirth` string, date: Date of birth in `YYYY-MM-DD` format.
      - `address` V3ContactAddress: Postal address of the contact.
        - `addressLine1` string: First line of the street address.
        - `addressLine2` string: Second line of the street address. Optional.
        - `city` string: City or locality.
        - `region` string: Region, state, or province.
        - `stateCode` string: If the address is in the US, provide the two-letter state code, for example, NY.
        - `postalCode` string: Postal or ZIP code.
        - `country` string: ISO 3166-1 alpha-2 country code.
    - V3ContactCompanyEntity: Entity details for a company (legal entity) contact.
      - `type` 'COMPANY', required: Entity type. Use `COMPANY` for legal entities.
      - `relationshipType` 'THIRD_PARTY' | 'SELF_OWNED', required: Relationship of the contact to your account. - `THIRD_PARTY`: The contact is a separate entity (e.g., a customer or supplier). - `SELF_OWNED`: The contact represents your own organisation.
      - `legalName` string, required: Registered legal name of the company.
      - `registrationNumber` string: Company registration number.
      - `dateOfIncorporation` string, date: Date of incorporation in `YYYY-MM-DD` format.
      - `address` V3ContactAddress: Postal address of the contact.
        - `addressLine1` string: First line of the street address.
        - `addressLine2` string: Second line of the street address. Optional.
        - `city` string: City or locality.
        - `region` string: Region, state, or province.
        - `stateCode` string: If the address is in the US, provide the two-letter state code, for example, NY.
        - `postalCode` string: Postal or ZIP code.
        - `country` string: ISO 3166-1 alpha-2 country code.
  - `createdAt` string, date-time: Timestamp when the contact was created.
  - `updatedAt` string, date-time: Timestamp when the contact was last updated.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `500`: Unexpected Error

## Changes

- **2026-11-06** `c386d436bf2c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/changes/platform/v3/contacts/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)