Understanding Your Account

Before you build, it helps to understand who you are in the CAPAY model and what clientId means for you. This one concept determines how almost every endpoint behaves.

Where you sit

CAPAY has two kinds of API user: Program Manager (PM) and Client. This portal is for Clients. As a Client, you act for yourself and, optionally, for underlying customers you manage.

Terminology: Client vs Customer

In the CA system, these two terms have distinct meanings:

• Client — you, the direct API integrator. You have a login to the Client Portal and hold your own institutional account.
• Customer — the end customers you serve. In the Client Portal they appear under the "Customers" section. Each Customer is a separate entity in the CA system.

Both Clients and Customers are assigned a unique clientId by the system. Despite the name, a Customer's clientId works exactly the same way — it uniquely identifies that Customer across all API operations. There is no separate customerId.

What clientId means in API calls

clientId is an optional parameter on many endpoints. For a Client, it selects whose context the operation runs in:

clientId	Acting entity
Omitted	Yourself (your own institutional account)
Provided	The Customer identified by that clientId

So the same call — create a beneficiary, make a payment, query balances — applies to you when clientId is absent, and to a specific Customer when it is present.

info

This is the mirror image of the Program Manager model, where clientId is required to name a managed client. As a Client you default to yourself, and only supply clientId when acting for an underlying Customer.

Underlying customers

If your business serves end customers, you can represent each of them as a Customer in the CA system. Create and manage them through the /clients endpoints:

Action	Endpoint
Create a business customer	POST /clients/business
Create a personal customer	POST /clients/personal
List customers	GET /clients/businesses · GET /clients/personal
Get / update / delete	.../business/{id} · .../personal/{id}

Once created, pass the customer's clientId to operate on their behalf—for example to create beneficiaries they own, or to make payments funded from their Sub-Account.

Customer status

Status	Meaning
PENDING APPROVAL	Created, awaiting activation
ACTIVE	Ready to transact
INACTIVE	Not currently usable
SUSPENDED	Blocked from transacting

Next steps

• Account Structure & Fund Flow — how your House and Sub-Accounts hold and move money.
• Beneficiaries — how ownership of a beneficiary is decided by clientId.