> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stableyard.fi/llms.txt
> Use this file to discover all available pages before exploring further.
# Business verification (KYB)
> Verify a business account through a provider-hosted application to open US bank rails.
A `business` account does not use email verification or individual KYC. It passes one business verification (KYB), hosted by a provider and started through a capability activation.
## What it opens
Business verification opens **US bank rails only**:
| Opens | Capability |
| - | - |
| Linking the company's own US bank, and payouts to it | `linked_bank` |
| A USD on-ramp account | `bank_onramp` |
Other countries are not available to a business. One-time payments to a third party's bank or a local QR still require an `individual` account. See [Universal Payment Account](/universal-payment-account#subjecttype-decides-what-the-account-may-ever-do).
## Before you start
| Requirement | How to meet it |
| - | - |
| Your organization's KYB is approved | `compliance.partnerKyb.status` in `GET /v2/partners/config`. See [Onboarding overview](/concepts/onboarding#partner-kyb-gates-all-fiat) |
| Stableyard has enabled business verification for your banking program | Ask Stableyard. Until then, a business activation is refused |
| The account was created with `subjectType: "business"` | `subjectType` cannot be changed after creation |
| Your app is entitled to the capability you activate | Otherwise the activation returns `403` |
## Start business verification
Activate any capability with `business.legalName`:
```bash theme={null}
curl -X POST https://staging-api-v2.stableyard.fi/v2/accounts/acct_456/capability-activations \
-u "$APP_ID:$APP_SECRET" \
-H "Idempotency-Key: kyb:acct_456" \
-H "Content-Type: application/json" \
-d '{
"capability": "linked_bank",
"country": "US",
"currency": "USD",
"rail": "ach",
"business": { "legalName": "Example Company Ltd" }
}'
```
```json theme={null}
{
"accountId": "acct_456",
"capability": {
"name": "linked_bank",
"status": "submission_pending",
"ready": false,
"nextAction": { "type": "continue_business_verification" },
"updatedAt": "2026-10-01T12:00:00Z"
}
}
```
| Field | Notes |
| - | - |
| `Idempotency-Key` header | Required, 8 to 256 printable characters. Keep it: you send the identical request again to get the link |
| `capability` | Any capability. The approval covers every capability for this business |
| `country`, `currency`, `rail` | A US route, such as `US`, `USD`, `ach` |
| `business.legalName` | 3 to 100 characters. Required on the first activation |
Send `business.legalName` on the first activation only, or when replaying that exact request. A different legal name later is refused; contact Stableyard to correct it.
## Get the hosted link
The status starts at `submission_pending` and `nextAction.type` is `continue_business_verification` while the hosted link is prepared. Send the identical request again, with the same key. Once the link is ready:
```json theme={null}
{
"accountId": "acct_456",
"capability": {
"name": "linked_bank",
"status": "submission_pending",
"ready": false,
"nextAction": { "type": "complete_compliance", "url": "https://…", "expiresAt": "2026-10-01T12:15:00Z" },
"updatedAt": "2026-10-01T12:01:00Z"
}
}
```
The link is returned only by the activation call. `GET /v2/accounts/{accountId}/capabilities` never returns it.
The hosted business link in `nextAction.url` is a credential. Send it only to the company's authorized representative, and never log it or keep it in browser storage.
If the link expires after the application exists, `nextAction.type` becomes `contact_support`: Stableyard support restarts it, not a new activation.
## Next actions for a business
| `nextAction.type` | Do this |
| - | - |
| `continue_business_verification` | Send the original activation again, with the same key, to get the current hosted link |
| `complete_compliance` | Send `url` to the authorized representative before `expiresAt` |
| `contact_support` | Stableyard must act. A new activation does not help |
| `none` | Approved. The capability is active |
The capability's `status` and `ready` follow the same states as any capability, starting at `submission_pending` rather than `action_required`. Use the service only when `ready` is `true`. See [Capability activation](/concepts/capability-activation#statuses).
## Add more capabilities
After approval, activate `bank_onramp` or another capability without `business`. It uses the same approval, so the business does not verify again.
## Errors
| Code | HTTP | When |
| - | - | - |
| `bad_request` | 400 | The first business activation is missing `business.legalName`, or `business` was sent for an individual account or a program without business verification |
| `forbidden` | 403 | Your app is not entitled to this capability |
| `conflict` | 409 | A different business legal name from the one the application was started with |
| `idempotency_conflict` | 409 | The same `Idempotency-Key` with a different body |
| `payment_provider_unavailable` | 503 | No single banking program covers this country, currency, rail and account type (`details.reasonCode`) |
## Webhooks
| Event | Fires when |
| - | - |
| `compliance.approved` | Business verification is approved and the capability is active. Read it before enabling the feature |
| `compliance.rejected` | Refused. Do not retry automatically |
| `compliance.requires_intervention` | Stopped for Stableyard operations review, including when the provider asks for more information |
Poll the activation with the same key while you wait for the hosted link: no event announces it. Every compliance event is listed on [Capability activation](/concepts/capability-activation#webhooks).
## Related
Statuses, next actions and errors for every capability.
Link the company's US bank once `linked_bank` is active.
Issue USD bank details once `bank_onramp` is active.
Every gate between an account and a fiat rail.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.