GuidesRecipesAPI ReferenceChangelogFAQ
Guides
Start typing to search…

Creating a Counterparty

How do I create a counterparty?

Overview

Counterparties represent external individuals and businesses not registered on the Cybrid Platform. They are used as recipients for transfers, payees for payments, and other financial operations. Create counterparties via the POST /api/counterparties endpoint.

Prerequisites

  • Authentication: Valid OAuth bearer token (bank token or customer token)
  • Required Scope: counterparties:execute
  • Country Support: Country code must be enabled for counterparties in your bank's configuration

Counterparty Ownership Models

Counterparties can be associated with either a bank or a specific customer.

Bank-Scoped Counterparties

  • Created with a bank token without passing customer_guid
  • Accessible to all customers within the bank
  • Ideal for common payees (utility companies, merchants)

Customer-Scoped Counterparties

  • Created with a bank token and passing customer_guid, OR created with a customer token
  • Private to the specific customer
  • Ideal for personal contacts and private payees

Counterparty Types

Individual Counterparties

Natural person counterparty.

Required Fields

  • type: Must be "individual"
  • name.first: First name
  • name.last: Last name
  • address.city: City name
  • address.country_code: ISO 3166-1 alpha-2 country code
ℹ️

Required Fields

The API spec does not specify both city and country as required fields due to the configuration for counterparty addresses - they are required for counterparties.

Optional Fields

  • name.middle: Middle name
  • date_of_birth: Date in ISO 8601 format (YYYY-MM-DD)
  • email_address: Valid email address
  • identification_numbers: Array of identification documents
  • labels: Array of strings for categorization (max 8 labels, 64 chars each)
  • customer_guid: Customer identifier (only when creating with bank token for a specific customer)
  • address.street: Street address
  • address.street2: Secondary address line
  • address.subdivision: ISO 3166-2 subdivision code
  • address.postal_code: Postal/ZIP code
⚠️

Address Requirements

Address field requirements vary by country. Some countries require street, subdivision, and postal_code.

Ensure that postal_code and subdivision fields match the country being specified.

Business Counterparties

Business entity or organization counterparty.

Required Fields

  • type: Must be "business"
  • name.full: Full legal business name
  • address.city: City name
  • address.country_code: ISO 3166-1 alpha-2 country code

Optional Fields

  • aliases: Array of business name aliases (alternate names or DBAs)
  • email_address: Valid email address
  • identification_numbers: Array of business identification documents
  • labels: Array of strings for categorization (max 8 labels, 64 chars each)
  • customer_guid: Customer identifier (only when creating with bank token for a specific customer)
  • address.street: Street address
  • address.street2: Secondary address line
  • address.subdivision: ISO 3166-2 subdivision code
  • address.postal_code: Postal/ZIP code

Request Examples

Creating an Individual Counterparty (Bank-Scoped)

Bank token without customer_guid.

POST /api/counterparties
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "individual",
  "name": {
    "first": "John",
    "middle": "Robert",
    "last": "Smith"
  },
  "date_of_birth": "1990-05-15",
  "address": {
    "street": "123 Main Street",
    "street2": "Apt 4B",
    "city": "New York",
    "subdivision": "NY",
    "postal_code": "10001",
    "country_code": "US"
  },
  "email_address": "[email protected]",
  "identification_numbers": [
    {
      "type": "drivers_license",
      "issuing_country_code": "US",
      "identification_number": "D1234567"
    }
  ],
  "labels": ["verified-payee", "priority"]
}

Creating an Individual Counterparty (Customer-Scoped with Bank Token)

Bank token with customer_guid.

POST /api/counterparties
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "individual",
  "customer_guid": "customer_guid",
  "name": {
    "first": "Jane",
    "last": "Doe"
  },
  "date_of_birth": "1985-03-22",
  "address": {
    "street": "456 Oak Avenue",
    "city": "Los Angeles",
    "subdivision": "CA",
    "postal_code": "90001",
    "country_code": "US"
  },
  "email_address": "[email protected]"
}

Creating an Individual Counterparty (Customer-Scoped with Customer Token)

Customer token (automatically scoped).

POST /api/counterparties
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "individual",
  "name": {
    "first": "Michael",
    "last": "Johnson"
  },
  "address": {
    "street": "789 Pine Street",
    "city": "Chicago",
    "subdivision": "IL",
    "postal_code": "60601",
    "country_code": "US"
  }
}

Creating a Business Counterparty (Bank-Scoped)

Bank token without customer_guid.

POST /api/counterparties
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "business",
  "name": {
    "full": "Acme Corporation"
  },
  "aliases": [
    {
      "full": "Acme Corp"
    },
    {
      "full": "Acme Industries"
    }
  ],
  "address": {
    "street": "1000 Business Park Drive",
    "street2": "Suite 500",
    "city": "San Francisco",
    "subdivision": "CA",
    "postal_code": "94105",
    "country_code": "US"
  },
  "email_address": "[email protected]",
  "identification_numbers": [
    {
      "type": "employer_identification_number",
      "issuing_country_code": "US",
      "identification_number": "12-3456789"
    }
  ],
  "labels": ["vendor", "monthly-billing"]
}

Creating a Business Counterparty (Customer-Scoped)

Customer token or bank token with customer_guid.

POST /api/counterparties
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "business",
  "name": {
    "full": "Tech Solutions Inc"
  },
  "address": {
    "street": "2500 Market Street",
    "city": "Seattle",
    "subdivision": "WA",
    "postal_code": "98101",
    "country_code": "US"
  }
}

Response

The API returns a counterparty object

{
  "guid": "counterparty_guid",
  "type": "individual",
  "state": "storing",
  "bank_guid": "bank_guid",
  "customer_guid": null,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z",
  "labels": ["verified-payee", "priority"],
  "compliance_decisions": []
}
ℹ️

PII Not Returned

Personally Identifiable Information (PII) such as name, address, and date of birth are not returned for security reasons. Use the GET /api/counterparties/:guid endpoint with counterparties:pii:read scope to retrieve PII. Make sure to include the ?include_pii=true parameter.

Best Practices

Choose the Right Ownership Model

Use bank-scoped counterparties for shared/common payees accessible to all customers. Use customer-scoped counterparties for private/personal payees.

Provide Complete Information

  • Include all available address fields to improve verification success rates
  • Add identification numbers when available for faster verification
  • Use valid email addresses to enable communication

Use Labels Effectively

Tag counterparties with meaningful labels for easy filtering and organization. Examples: "vendor", "employee", "monthly-payee", "high-priority"

Verify Country Support

Verify that the country code is enabled in your bank's configuration before creating counterparties. In sandbox environments, all countries are typically supported for testing.

Understand Address Requirements

Different countries have different address requirements. The US, Canada, and UK typically require street, city, subdivision, and postal_code. Some countries may not use subdivision codes or postal codes.

Monitor State Transitions

  • Poll the counterparty state to determine when verification is complete
  • Only use verified counterparties for production transactions
  • Handle rejected states appropriately (prompt user to correct information)

Next Steps

Updated 7 days ago