> ## 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.

# Activate a regulated capability for an account

> Get a verified account approved for a bank service: the three capabilities, their states and next actions.

A capability is one regulated service for one account, in one country, currency and rail. Identity verification proves who the customer is; activation gets the customer approved for the service by the banking partner behind it.

```bash theme={null}
curl -X POST https://staging-api-v2.stableyard.fi/v2/accounts/acct_123/capability-activations \
  -u "$APP_ID:$APP_SECRET" \
  -H "Idempotency-Key: activate:acct_123:bank_onramp:v1" \
  -H "Content-Type: application/json" \
  -d '{ "capability": "bank_onramp", "country": "US", "currency": "USD", "rail": "ach" }'
```

```json theme={null}
{
  "accountId": "acct_123",
  "capability": {
    "name": "bank_onramp",
    "status": "action_required",
    "ready": false,
    "nextAction": { "type": "complete_compliance", "url": "https://…", "expiresAt": "2026-10-01T12:15:00Z" },
    "updatedAt": "2026-10-01T12:00:00Z"
  }
}
```

Use the service only when `ready` is `true`.

## The three capabilities

| `capability` | What it is for |
| - | - |
| `bank_onramp` | Issuing an [on-ramp account](/concepts/on-ramp-accounts) |
| `linked_bank` | Payouts to the customer's own [linked bank](/concepts/bank-accounts). A `business` account also needs it to link a US bank |
| `bank_payout` | Payouts to an external bank account, where your banking program covers that rail |

The capabilities of one account rest on one banking relationship per banking program. Activate each one you use anyway: each records the customer's consent to that service, and your app must be granted each one.

Each activation also names a `country` (ISO 3166-1 alpha-2), a `currency` (ISO 4217) and a `rail`, such as `ach`. Send `amountAtomic` only when eligibility depends on an amount tier.

## What activation needs first

| Account | Needs |
| - | - |
| `individual` | A verified email and current identity eligibility. See [Email verification](/concepts/email-verification) and [Individual KYC](/concepts/individual-kyc) |
| `business` | Business verification enabled for your banking program. Its first activation carries `business.legalName` |
| Either | Your organization's KYB approved, your app entitled to the capability, and exactly one banking program covering that country, currency, rail and account type |

## Activation is idempotent

`Idempotency-Key` is required, 8 to 256 printable characters. Replaying the identical body with the same key returns the current state of the original action. A changed body with the same key is refused with `409 idempotency_conflict`.

A new key starts a new action. Use one when the customer lost the hosted page: the new link replaces the old one, which stops working.

## The hosted form

For an `individual`, `complete_compliance` carries a one-time link to a Stableyard-hosted page. On it the customer:

1. Confirms a code Stableyard emails to the account's verified address.
2. Supplies only the details their identity verification did not already provide.
3. Reviews and consents to the service.

<Warning>
  `nextAction.url` is a credential. Send it only to the account holder, open it before `expiresAt`, and never log it, cache it or put it in browser storage.
</Warning>

## Statuses

```mermaid theme={null}
stateDiagram-v2
  [*] --> action_required: individual activation
  [*] --> submission_pending: business activation
  action_required --> submission_pending: form completed
  submission_pending --> provider_review
  provider_review --> active
  provider_review --> rejected
  provider_review --> requires_intervention: more information needed
  active --> restricted
  restricted --> active
  active --> closed
  rejected --> [*]
  closed --> [*]
```

| `status` | `ready` | Meaning |
| - | - | - |
| `action_required` | `false` | The account holder has a hosted form to complete |
| `submission_pending` | `false` | The form is complete and the application is queued |
| `provider_review` | `false` | The banking partner is reviewing it |
| `active` | `true` | Approved. The service can be used |
| `restricted` | `false` | Was active, then frozen, suspended or withdrawn by the banking partner |
| `rejected` | `false` | Refused. Do not retry automatically |
| `closed` | `false` | Closed by the banking partner |
| `requires_intervention` | `false` | Stopped for Stableyard operations review |

## Next actions

| `nextAction.type` | Do this |
| - | - |
| `complete_compliance` | Open `url` for the account holder before `expiresAt` |
| `compliance_in_progress` | The link was opened and the form is unfinished. If the customer lost the page, activate again with a new `Idempotency-Key` |
| `wait_for_compliance_review` | Nothing. Wait for `compliance.approved`, or read the capability again |
| `continue_business_verification` | Business only. Send the original activation again to get the current hosted link |
| `contact_support` | Stableyard operations must act. A new activation does not help |
| `none` | Nothing. The capability is active |

## Read every capability

```bash theme={null}
curl https://staging-api-v2.stableyard.fi/v2/accounts/acct_123/capabilities \
  -u "$APP_ID:$APP_SECRET"
```

```json theme={null}
{
  "accountId": "acct_123",
  "capabilities": [
    { "name": "bank_onramp", "status": "active", "ready": true, "nextAction": { "type": "none" }, "updatedAt": "2026-10-02T09:30:00Z" },
    { "name": "linked_bank", "status": "provider_review", "ready": false, "nextAction": { "type": "wait_for_compliance_review" }, "updatedAt": "2026-10-02T09:31:00Z" }
  ]
}
```

An empty `capabilities` array means nothing has been activated on this account. Read `ready` and `nextAction`; never keep an old hosted URL.

## Business accounts

A business passes one hosted business verification, and every capability for it rests on that one approval.

<Steps>
  <Step title="Start it">
    Activate any capability with `business.legalName`. The status starts at `submission_pending` and `nextAction.type` is `continue_business_verification` while the hosted link is prepared.
  </Step>

  <Step title="Get the link">
    Send the identical request again, with the same key. Once the link is ready, `nextAction.type` is `complete_compliance` with a provider-hosted `url` and `expiresAt`. The list endpoint never returns it.
  </Step>

  <Step title="Send it to the representative">
    Only the company's authorized representative. If the link expires after the application exists, `nextAction.type` becomes `contact_support`: Stableyard support restarts it, not a new activation.
  </Step>

  <Step title="Add more capabilities">
    After approval, activate `bank_onramp` or another capability without `business`. It uses the same approval.
  </Step>
</Steps>

Business verification opens US bank rails only. See [Business KYB](/concepts/business-verification).

## Errors

| Code | HTTP | When |
| - | - | - |
| `bad_request` | 400 | `business` was sent for an individual account or a program without business verification, or the first business activation has no `business.legalName` |
| `forbidden` | 403 | Your app is not entitled to this capability |
| `conflict` | 409 | No verified email (`details.nextAction.type: "verify_account_email"`), no current identity approval (`details.nextAction.type: "complete_kyc"`), the account's application needs operations review, or a different business legal name |
| `idempotency_conflict` | 409 | The same 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 | Meaning |
| - | - |
| `compliance.action_required` | The account holder must complete or resume a hosted action. Read the capability for the current link |
| `compliance.submitted` | Consent and evidence were accepted and the application was queued. Not approval |
| `compliance.approved` | The capability is active. Read it before enabling the feature |
| `compliance.rejected` | Refused. Do not retry automatically |
| `compliance.requires_intervention` | Stopped for operations review |

## Related

* [Onboarding overview](/concepts/onboarding): the gates before activation.
* [On-ramp accounts](/concepts/on-ramp-accounts): what `bank_onramp` unlocks.
* [Bank accounts](/concepts/bank-accounts): what `linked_bank` pays out to.
* [Choose your pattern](/white-label/patterns): which capabilities each integration needs.

<Card title="Next: Payments" icon="money-bill-transfer" href="/concepts/payments">
  The Payment object: intent, destinations, frozen snapshots and states.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.