---
title: "Create Counterparty"
method: POST
path: "/counterparties"
tags: ["Counterparties"]
---

# Create Counterparty

`POST /counterparties`

## Request

- Base URL: `https://api.sandbox.zeptopayments.com`
- URL: `https://api.sandbox.zeptopayments.com/counterparties`
- Auth: HTTP bearer

Creates a counterparty, optionally with payment accounts.

Identity and account ownership verification evidence is optional. Zepto
stores the evidence provided without attempting to validate it.

## Request body

- PaytoCounterpartyRequest
  - `uid` string, required: A supplied unique ID, unique within your account
  - `client_id` string, uuid: The ID of the client the counterparty belongs to. Supply the sub-client's ID for counterparties of agreements initiated on its behalf.
  - `identity` PaytoCounterpartyIdentity, required: The verifiable identity of the counterparty, separate from any of their payment accounts
    - `legal_name` string, required: The legal name of the person or organisation as verified by KYC
    - `verification` object, nullable: Evidence that the counterparty's identity has been verified.
      - `type` 'third_party_provider', required
      - `provider` string: The KYC provider that performed the verification. Required for third_party_provider.
      - `reference` string: The provider's reference for the verification result
      - `verified_at` string, date-time
  - `payment_accounts` PaytoCounterpartyPaymentAccount[]
    - `uid` string, required: A supplied unique ID, unique within your account
    - `party_name` string, required: Name by which the account holder is known and which is usually used to identify them. HTML name entities are not allowed. Agreements, amendments and payments that reference this payment account must name the party with this exact name, ignoring case, in the debtor or creditor ultimate_party_name. When an agreement is uplifted with add_identification, the payment account is matched against the debtor ultimate_party_name already on the agreement.
    - `account_identifier` PaytoAccountIdentifier, required: An identifier representing the parties account
      - `type` 'bban' | 'alias_phone' | 'alias_email' | 'alias_abn' | 'alias_organisation_identifier', required
      - `value` union, required
        - string: A branch code (BSB) and account number separated with a hyphen
        - string: A PayID email alias
        - string: A PayID phone alias. e.g. +61-411222333
        - string: A PayID ABN alias
        - string: A PayID organisation identifier alias
    - `verification` object, nullable: Evidence that this account is owned by the verified identity of the counterparty.
      - `type` 'zepto_validate' | 'alias_resolution' | 'third_party_provider', required
      - `provider` string: The provider that performed the verification. Required for third_party_provider, and not allowed for zepto_validate or alias_resolution, where Zepto performed the check.
      - `reference` string: The reference for the verification result: a Zepto Validate uid, the PayID alias whose display name was resolved for alias_resolution, or the provider's reference.
      - `verified_at` string, date-time
  - `metadata` PaytoMetadata, nullable: Use for your custom data. A place to store any miscellaneous information your system may need in regards to the record you are creating. This will be included in associated webhook payloads under the `resource_metadata` key. Nested values (i.e., objects and arrays) are not allowed. The maximum size of this parameter is 2kb.

## Response `201`

successful

- object
  - `data` PaytoCounterpartyResponse, required
    - `uid` string, required: A supplied unique ID, unique within your account
    - `identity` PaytoCounterpartyIdentity, required: The verifiable identity of the counterparty, separate from any of their payment accounts
      - `legal_name` string, required: The legal name of the person or organisation as verified by KYC
      - `verification` object, nullable: Evidence that the counterparty's identity has been verified.
        - `type` 'third_party_provider', required
        - `provider` string: The KYC provider that performed the verification. Required for third_party_provider.
        - `reference` string: The provider's reference for the verification result
        - `verified_at` string, date-time
    - `payment_accounts` PaytoCounterpartyPaymentAccount[], required
      - `uid` string, required: A supplied unique ID, unique within your account
      - `party_name` string, required: Name by which the account holder is known and which is usually used to identify them. HTML name entities are not allowed. Agreements, amendments and payments that reference this payment account must name the party with this exact name, ignoring case, in the debtor or creditor ultimate_party_name. When an agreement is uplifted with add_identification, the payment account is matched against the debtor ultimate_party_name already on the agreement.
      - `account_identifier` PaytoAccountIdentifier, required: An identifier representing the parties account
        - `type` 'bban' | 'alias_phone' | 'alias_email' | 'alias_abn' | 'alias_organisation_identifier', required
        - `value` union, required
          - string: A branch code (BSB) and account number separated with a hyphen
          - string: A PayID email alias
          - string: A PayID phone alias. e.g. +61-411222333
          - string: A PayID ABN alias
          - string: A PayID organisation identifier alias
      - `verification` object, nullable: Evidence that this account is owned by the verified identity of the counterparty.
        - `type` 'zepto_validate' | 'alias_resolution' | 'third_party_provider', required
        - `provider` string: The provider that performed the verification. Required for third_party_provider, and not allowed for zepto_validate or alias_resolution, where Zepto performed the check.
        - `reference` string: The reference for the verification result: a Zepto Validate uid, the PayID alias whose display name was resolved for alias_resolution, or the provider's reference.
        - `verified_at` string, date-time
    - `metadata` PaytoMetadata, nullable, required: Use for your custom data. A place to store any miscellaneous information your system may need in regards to the record you are creating. This will be included in associated webhook payloads under the `resource_metadata` key. Nested values (i.e., objects and arrays) are not allowed. The maximum size of this parameter is 2kb.
    - `client_id` string, uuid, required: The client this counterparty belongs to
    - `created_at` string, date-time, required

## Other responses

- `400`: bad request
- `401`: unauthorized
- `403`: forbidden
- `409`: conflict
- `422`: unprocessable entity
- `500`: Internal Server Error

---

[API](https://skmtc.dev/zeptopayments/apis/zepto-payto-api.md) - [All operations](https://skmtc.dev/zeptopayments/apis/zepto-payto-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zeptopayments/apis/zepto-payto-api/revisions/dfc64507b23c?raw)