Create a Customer

Overview

Use the POST /api/customers endpoint to create a new customer. If using Cybrid Platform for KYC, specify only the customer type (individual or business).

⚠️

Customer GUID is tied to a legal entity

A Cybrid customer GUID represents a specific legal entity and its verified compliance record. If there is a change in ownership or the legal entity, you must create a new customer (new GUID) and complete a full KYB workflow for the new entity. Reusing an existing customer GUID for a new owner or legal entity is not permitted, as compliance records and risk assessments are tied to the original entity.

Creating an Individual Customer

All individual customers must complete Cybrid's KYC process.

{
  "type": "individual"
}

To verify the customer exists, call GET /api/customers to list all customers attached to your bank. The response includes:

{
  "total": 1,
  "page": 0,
  "per_page": 10,
  "objects": [
    {
      "guid": "customer_guid",
      "bank_guid": "bank_guid",
      "type": "individual",
      "created_at": "2022-05-13T13:55:08.460Z",
      "state": "unverified"
    }
  ]
}

Creating a Business Customer

All business customers must complete Cybrid's KYB process.

{
  "type": "business"
}

To verify the customer exists, call GET /api/customers. The response includes:

{
  "total": 1,
  "page": 0,
  "per_page": 10,
  "objects": [
    {
      "guid": "customer_guid",
      "bank_guid": "bank_guid",
      "type": "business",
      "created_at": "2022-05-13T13:55:08.460Z",
      "state": "unverified"
    }
  ]
}

Customer States

A customer progresses through these states:

• storing -- The platform is still storing the customer record.
• unverified -- The platform has stored the customer record and is ready for identity verification.
• verified -- The customer has passed identity verification.
• rejected -- The customer failed identity verification.
• frozen -- The platform has frozen the customer account.

Freezing Customers

Customers may be frozen on the Platform for various reasons. For example, certain ACH return codes such as R16 (bank account frozen) will trigger a workflow that freezes the customer and deletes their associated bank account connection to prevent fraudulent activity. For other administrative returns like R01, the platform will only freeze the customer if they have a negative balance on their platform account. There is no webhook event for customer state changes. To detect a freeze caused by an ACH return, listen for the transfer.completed webhook, check whether transfer_type is funding_return or instant_funding_return, and call GET /api/customers/{customer_guid} with the transfer's customer_guid to check whether the customer's state is frozen. This does not detect freezes that are not caused by a return, such as those for security concerns; to catch every freeze, poll GET /api/customers/{customer_guid}.

A frozen customer cannot initiate trades or transfers, but they can still receive funds. Repaying the negative balance does not automatically unfreeze the customer; to restore normal activity, create a Zendesk ticket to request that the customer be unfrozen.

A negative balance persists until the customer repays it, so a customer frozen this way stays frozen while the debt is outstanding. See Negative customer balances.

After creating a customer, proceed to identity verification.