Capabilities

Capabilities are permissions attached to accounts that control what verification flows frameOS runs and what payment methods an account can use. Each capability you request tells frameOS what information to collect during onboarding and which checks to run automatically.

Capabilities must be requested before creating an onboarding session. frameOS uses the set of requested capabilities to determine the exact fields and verifications required for the account.

ENDPOINTS

POST/v1/accounts/:account_id/capabilities

GET/v1/accounts/:account_id/capabilities/:name

GET/v1/accounts/:account_id/capabilities

DELETE/v1/accounts/:account_id/capabilities/:name

Capability types

The table below shows which capabilities are available for each account type.

Capability	Individual	Business	Description
kyc	✓	—	KYC — Identity verification
phone_verification	✓	—	Phone verification — SMS or voice phone verification
kyc_prefill	✓	—	KYC Prefill — Pre-fill KYC from a verified phone number
age_verification	✓	—	Age verification — Age restriction enforcement
address_verification	✓	—	Address verification — Physical address validation
card_verification	✓	—	Card verification — Card verification without a charge
bank_account_verification	✓	—	Bank account verification — Bank account ownership verification
creator_shield	✓	—	Creator Shield — Fraud protection for creators. Must be enabled in frameOS Settings.
geo_compliance	✓	✓	Geocompliance — Location-based compliance rules. Must be enabled in frameOS Settings.
card_send	✓	✓	Accept card payments
card_receive	✓	✓	Payouts — Receive card payouts
bank_account_send	✓	✓	Accept bank account payments
bank_account_receive	✓	✓	Payouts — Receive bank account payouts

Creator Shield and Geocompliance must be activated in frameOS Settings before they can be requested on an account. Requesting these capabilities without enabling them first will result in an error.

Capability dependencies

Requesting certain capabilities automatically includes their dependencies. frameOS resolves the full set and returns all expanded capabilities in the response — you do not need to request dependencies separately.

Requested capability	Also requested automatically
`kyc_prefill`	`kyc`, `phone_verification`
`creator_shield`	`kyc`, `age_verification`

The response from a request capabilities call always returns the full expanded set, including any automatically added dependencies.

The Capability object

Attributes

idstring

Unique identifier for the capability.

objectstring

String representing the object type. Always "capability".

nameenum

The capability type. One of kyc, phone_verification, kyc_prefill, age_verification, address_verification, card_verification, bank_account_verification, creator_shield, geo_compliance, card_send, card_receive, bank_account_send, or bank_account_receive.

account_idstring

The ID of the account this capability belongs to.

statusenum

The current status of the capability. One of pending, active, or disabled.

disabled_reasonnullable string

A description of why the capability is disabled. Present only when status is "disabled".

currently_duearray

An array of field keys still required before the capability can activate. Empty when the capability is already active or when no fields have been partially collected yet. See How currently_due works.

errorsarray

An array of capability error objects describing issues that occurred during requirement verification. Errors are automatically cleared when the associated requirement is verified or waived.

createddatetime

ISO 8601 timestamp of when the capability was created.

updateddatetime

ISO 8601 timestamp of when the capability was last updated.

disablednullable datetime

ISO 8601 timestamp of when the capability was disabled. null if not disabled.

THE CAPABILITY OBJECT

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891",
  "object": "capability",
  "name": "kyc",
  "account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
  "status": "pending",
  "disabled_reason": null,
  "currently_due": [
    "profile.individual.name",
    "profile.individual.address",
    "profile.individual.ssn_last_four"
  ],
  "errors": [],
  "created": "2024-07-15T01:10:05Z",
  "updated": "2024-07-15T01:10:05Z",
  "disabled": null
}

The Capability Error object

When a requirement verification fails, frameOS creates a capability error that describes what went wrong. Errors are nested under the capability they belong to and are automatically removed when the underlying requirement is verified or waived.

Attributes

idstring

Unique identifier for the capability error.

objectstring

String representing the object type. Always "capability_error".

codeenum

A machine-readable error code. See error codes below.

messagenullable string

A human-readable description of the error.

requirement_idstring

The ID of the requirement that produced the error.

createdtimestamp

Unix timestamp of when the error was created.

THE CAPABILITY ERROR OBJECT

{
  "id": "f8a3b1c2-d4e5-6789-abcd-ef1234567890",
  "object": "capability_error",
  "code": "invalid_phone_number",
  "message": "The phone number provided could not be verified",
  "requirement_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "created": 1721003405
}

Capability error codes

Code	Description
`invalid_phone_number`	The phone number provided could not be verified

How `currently_due` works

currently_due lists the specific fields still required before a capability can activate. It is computed dynamically by evaluating what information is already present on the account against the capability's requirements.

When all items in currently_due are cleared — either through direct API updates or a completed onboarding session — the capability activates automatically with no manual action needed.

currently_due is empty in two cases:

The capability is already active
No required fields have been partially collected yet (it reflects only fields that are partially met — meaning some requirements exist but are incomplete)

Common values include profile.individual.name, profile.individual.address, profile.individual.ssn_last_four, and profile.individual.birthdate.

Request capabilities

Requests one or more capabilities for an account. Capability dependencies are resolved automatically — for example, requesting kyc_prefill also creates kyc and phone_verification capabilities.

Requesting an already-active capability is a no-op. The endpoint returns 201 when at least one new capability was created, and 200 when all requested capabilities already existed.

Parameters

capabilitiesarrayrequired

An array of capability names to request (e.g. ["kyc", "card_receive"]).

Returns

Returns an array of capability objects wrapped in a data key, including any automatically added dependencies.

POST/v1/accounts/:account_id/capabilities

curl --request POST \
  --url https://api.framepayments.com/v1/accounts/99c6b0da-2570-42a7-838a-5eaa318b07df/capabilities \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "capabilities": ["kyc_prefill"]
}'

RESPONSE

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891",
      "object": "capability",
      "name": "kyc",
      "account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
      "status": "pending",
      "disabled_reason": null,
      "currently_due": [],
      "errors": [],
      "created": "2024-07-15T01:10:05Z",
      "updated": "2024-07-15T01:10:05Z",
      "disabled": null
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567892",
      "object": "capability",
      "name": "phone_verification",
      "account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
      "status": "pending",
      "disabled_reason": null,
      "currently_due": [],
      "errors": [],
      "created": "2024-07-15T01:10:05Z",
      "updated": "2024-07-15T01:10:05Z",
      "disabled": null
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567893",
      "object": "capability",
      "name": "kyc_prefill",
      "account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
      "status": "pending",
      "disabled_reason": null,
      "currently_due": [],
      "errors": [],
      "created": "2024-07-15T01:10:05Z",
      "updated": "2024-07-15T01:10:05Z",
      "disabled": null
    }
  ]
}

Retrieve a capability

Retrieves a single capability by name for the given account.

Parameters

account_idstringrequired

The ID of the account.

namestringrequired

The name of the capability to retrieve (e.g. kyc).

Returns

Returns the capability object.

GET/v1/accounts/:account_id/capabilities/:name

curl --request GET \
  --url https://api.framepayments.com/v1/accounts/99c6b0da-2570-42a7-838a-5eaa318b07df/capabilities/kyc \
  --header 'Authorization: Bearer API_KEY'

RESPONSE

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891",
  "object": "capability",
  "name": "kyc",
  "account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
  "status": "pending",
  "disabled_reason": null,
  "currently_due": [
    "profile.individual.name",
    "profile.individual.address",
    "profile.individual.ssn_last_four"
  ],
  "errors": [],
  "created": "2024-07-15T01:10:05Z",
  "updated": "2024-07-15T01:10:05Z",
  "disabled": null
}

List all capabilities

Returns all capabilities for the given account.

Parameters

account_idstringrequired

The ID of the account.

Returns

A dictionary with a data property containing an array of capability objects.

GET/v1/accounts/:account_id/capabilities

curl --request GET \
  --url https://api.framepayments.com/v1/accounts/99c6b0da-2570-42a7-838a-5eaa318b07df/capabilities \
  --header 'Authorization: Bearer API_KEY'

RESPONSE

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891",
      "object": "capability",
      "name": "kyc",
      "account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
      "status": "active",
      "disabled_reason": null,
      "currently_due": [],
      "errors": [],
      "created": "2024-07-15T01:10:05Z",
      "updated": "2024-07-15T02:30:00Z",
      "disabled": null
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567892",
      "object": "capability",
      "name": "card_receive",
      "account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
      "status": "pending",
      "disabled_reason": null,
      "currently_due": [
        "profile.individual.name",
        "profile.individual.address",
        "profile.individual.ssn_last_four"
      ],
      "errors": [],
      "created": "2024-07-15T01:10:05Z",
      "updated": "2024-07-15T01:10:05Z",
      "disabled": null
    }
  ]
}

Disable a capability

Disables a capability for an account. If disabling the capability leaves the account with no active capabilities, the account is automatically restricted.

If the capability is already disabled, the request returns 200 with no state change.

Parameters

account_idstringrequired

The ID of the account.

namestringrequired

The name of the capability to disable (e.g. kyc).

Returns

Returns the disabled capability object.

DELETE/v1/accounts/:account_id/capabilities/:name

curl --request DELETE \
  --url https://api.framepayments.com/v1/accounts/99c6b0da-2570-42a7-838a-5eaa318b07df/capabilities/kyc \
  --header 'Authorization: Bearer API_KEY'

RESPONSE

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891",
  "object": "capability",
  "name": "kyc",
  "account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
  "status": "disabled",
  "disabled_reason": "capability_disabled_by_platform",
  "currently_due": [],
  "errors": [],
  "created": "2024-07-15T01:10:05Z",
  "updated": "2024-07-15T03:45:00Z",
  "disabled": "2024-07-15T03:45:00Z"
}