Accounts

frameOS centers on connected accounts, the merchants and/or the end users who send payments, receive payouts, and complete verification flows on your platform. Create an account with the capabilities you need, prefill the information you already have, and use hosted onboarding to securely collect the rest.

Accounts support two types: individual and business. Individual accounts are used for sole proprietors and end users. Business accounts are for companies and organizations. The type you choose determines which capabilities and verification flows are available.

For a low-code option, use hosted onboarding to generate a session and let Frame collect the required information directly from the account holder.

ENDPOINTS

POST/v1/accounts PATCH/v1/accounts/:id GET/v1/accounts/:id GET/v1/accounts DELETE/v1/accounts/:id

Account types

Type	Use case
individual	Sole proprietors, creators, and end users on marketplaces
business	For companies, organizations, and other entities with a formally registered legal structure.

Most frameOS verification products, including KYC, phone verification, and address verification, are designed for individual accounts.

Business accounts follow a separate verification model. We run KYB on the legal entity while simultaneously onboarding and verifying each owner or controller as an individual in Frame, applying the appropriate KYC and related checks in parallel.

Accounts and capabilities in frameOS

Accounts are the anchor for everything in frameOS. Capabilities define what an account can do — request them when creating the account, and frameOS uses them to determine what information to collect during onboarding and which verification checks to run automatically.

Capability	Description	Account requirement
kyc	KYC — Configurable identity verification flows	Individual account with name, phone, address, DOB, last 4 of SSN
phone_verification	Phone verification — Verify via SMS or voice	Individual account with phone number
kyc_prefill	KYC Prefill — Pre-fill KYC with verified identity data	Individual account with phone number
age_verification	Age verification — Confirm age for restrictions	Individual account with verified KYC and DOB
address_verification	Address verification — Validate physical addresses	Payment method with billing address; ACH also requires verified KYC
card_verification	Card verification — Verify cards without charging	Individual account with a card payment method
bank_account_verification	Bank account verification — Verify bank account ownership	Individual account; must use hosted onboarding session
creator_shield	Creator Shield — Fraud protection for creators	Individual account with verified KYC
geo_compliance	Geocompliance — Location-based rules	Account with Frame.js or mobile SDK initialized
card_send	Accept card payments	Individual or business account
card_receive	Card payouts — Receive payouts to a card	Individual account with verified KYC and card payment method
bank_account_send	Accept bank account payments	Individual or business account
bank_account_receive	Bank account payouts — Receive payouts to a bank account	Individual account with verified KYC and bank account payment method
Billing	Fee plans and invoicing	Any account; fee plan assigned at creation via `billing.fee_plan_id`

See onboarding sessions for how capabilities drive the hosted onboarding flow.

The Account object

Attributes

idstring

Unique identifier for the account.

typeenum

The type of account. One of individual or business.

statusenum

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

external_idnullable string

An optional identifier from your own system. Must be unique per merchant. Useful for linking Frame accounts to records in your platform.

capabilitiesarray

An array of capability objects for this account. Each object includes the capability id, name, status, disabled_reason, currently_due, and disabled.

profileobject

The account holder's profile information. Contains either an individual or business sub-object depending on the account type.

terms_of_servicenullable object

Record of when and how the account holder accepted your platform's terms of service. null if not yet accepted.

metadatadictionary

A set of key-value pairs you can attach to the account for your own reference.

livemodeboolean

true if the account exists in live mode, false if in test mode.

createdtimestamp

Unix timestamp of when the account was created.

THE ACCOUNT OBJECT

{
  "id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
  "object": "account",
  "type": "individual",
  "status": "active",
  "external_id": "usr_8675309",
  "capabilities": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891",
      "object": "capability",
      "name": "card_send",
      "status": "active",
      "disabled_reason": null,
      "currently_due": [],
      "disabled": null
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567892",
      "object": "capability",
      "name": "kyc",
      "status": "active",
      "disabled_reason": null,
      "currently_due": [],
      "disabled": null
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567893",
      "object": "capability",
      "name": "card_receive",
      "status": "active",
      "disabled_reason": null,
      "currently_due": [],
      "disabled": null
    }
  ],
  "profile": {
    "individual": {
      "email": "marcia@example.com",
      "ssn_last_four": "6789",
      "name": {
        "first_name": "Marcia",
        "middle_name": null,
        "last_name": "Longo",
        "suffix": null
      },
      "phone": {
        "number": "3107484186",
        "country_code": "1"
      },
      "birthdate": null,
      "address": {
        "line_1": "123 Main St",
        "line_2": null,
        "city": "Los Angeles",
        "state": "CA",
        "postal_code": "90001",
        "country": "US"
      }
    }
  },
  "terms_of_service": {
    "token": "tos_v1_2024",
    "accepted": true,
    "accepted_at": "2024-08-24T14:15:22Z"
  },
  "metadata": {},
  "livemode": false,
  "created": 1721010605
}

Create an account

Creates a new account. Pass the account type, any capabilities to request, and known profile information. frameOS validates the profile fields and immediately triggers any capability checks that can be resolved without additional information from the account holder.

For capabilities that require further information — such as KYC — create an onboarding session after account creation to collect the remaining fields.

Parameters

typeenumrequired

The type of account. One of individual or business.

capabilitiesarrayoptional

An array of capability type names to request for the account (e.g. ["kyc", "card_receive"]). Do not pass an object or hash — only an array of strings.

external_idstringoptional

An optional identifier from your own system. Must be unique per merchant.

profileobjectoptional

Profile information for the account holder. Contains either an individual or business sub-object.

terms_of_serviceobjectoptional

Record of the account holder's acceptance of your platform's terms of service.

metadatadictionaryoptional

A set of key-value pairs to attach to the account.

Returns

Returns the newly created account object along with the current status of any requested capabilities.

POST/v1/accounts

curl --request POST \
  --url https://api.framepayments.com/v1/accounts \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "individual",
  "capabilities": ["kyc", "card_receive"],
  "external_id": "usr_8675309",
  "profile": {
    "individual": {
      "email": "marcia@example.com",
      "name": {
        "first_name": "Marcia",
        "last_name": "Longo"
      },
      "phone": {
        "number": "3107484186",
        "country_code": "1"
      }
    }
  },
  "terms_of_service": {
    "accepted_at": "2024-08-24T14:15:22Z",
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0",
    "token": "tos_v1_2024"
  },
  "metadata": {
    "platform_user_id": "u_123"
  }
}'

RESPONSE

{
  "id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
  "object": "account",
  "type": "individual",
  "status": "pending",
  "external_id": "usr_8675309",
  "capabilities": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567892",
      "object": "capability",
      "name": "kyc",
      "status": "pending",
      "disabled_reason": null,
      "currently_due": [],
      "disabled": null
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567893",
      "object": "capability",
      "name": "card_receive",
      "status": "pending",
      "disabled_reason": null,
      "currently_due": [],
      "disabled": null
    }
  ],
  "profile": {
    "individual": {
      "email": "marcia@example.com",
      "ssn_last_four": null,
      "name": {
        "first_name": "Marcia",
        "middle_name": null,
        "last_name": "Longo",
        "suffix": null
      },
      "phone": {
        "number": "3107484186",
        "country_code": "1"
      },
      "birthdate": null,
      "address": null
    }
  },
  "terms_of_service": {
    "token": "tos_v1_2024",
    "accepted": true,
    "accepted_at": "2024-08-24T14:15:22Z"
  },
  "metadata": {
    "platform_user_id": "u_123"
  },
  "livemode": false,
  "created": 1721010605
}

Update an account

Updates an existing account. You can update profile information, metadata, and terms of service acceptance. Updating profile fields required for pending capabilities triggers those checks to re-run automatically.

Parameters

external_idstringoptional

An identifier from your own system to associate with the account. Must be unique per merchant.

profileobjectoptional

Updated profile information for the account holder. Contains either an individual or business sub-object.

terms_of_serviceobjectoptional

Record of the account holder's acceptance of your platform's terms of service.

metadatadictionaryoptional

Updated metadata key-value pairs.

Returns

Returns the updated account object with current capability statuses.

PATCH/v1/accounts/:id

curl --request PATCH \
  --url https://api.framepayments.com/v1/accounts/7b03bf26-6394-4ee8-b56a-d38635bd14b1 \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "profile": {
    "individual": {
      "name": {
        "first_name": "Riley",
        "last_name": "Morgan"
      }
    }
  }
}'

RESPONSE

{
  "id": "7b03bf26-6394-4ee8-b56a-d38635bd14b1",
  "object": "account",
  "type": "individual",
  "status": "pending",
  "external_id": "usr_8675309",
  "capabilities": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567892",
      "object": "capability",
      "name": "kyc",
      "status": "pending",
      "disabled_reason": null,
      "currently_due": [],
      "disabled": null
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567893",
      "object": "capability",
      "name": "card_receive",
      "status": "pending",
      "disabled_reason": null,
      "currently_due": [],
      "disabled": null
    }
  ],
  "profile": {
    "individual": {
      "email": "riley@example.com",
      "ssn_last_four": null,
      "name": {
        "first_name": "Riley",
        "middle_name": null,
        "last_name": "Morgan",
        "suffix": null
      },
      "phone": {
        "number": "3107484186",
        "country_code": "1"
      },
      "birthdate": null,
      "address": null
    }
  },
  "terms_of_service": null,
  "metadata": {
    "platform_user_id": "u_123"
  },
  "livemode": false,
  "created": 1721010605
}

Retrieve an account

Retrieves an existing account by ID, including its profile and current capability statuses.

Parameters

No parameters.

Returns

Returns the account object with current capability statuses.

GET/v1/accounts/:id

curl --request GET \
  --url https://api.framepayments.com/v1/accounts/7b03bf26-6394-4ee8-b56a-d38635bd14b1 \
  --header 'Authorization: Bearer API_KEY'

RESPONSE

{
  "id": "7b03bf26-6394-4ee8-b56a-d38635bd14b1",
  "object": "account",
  "type": "individual",
  "status": "pending",
  "external_id": "usr_8675309",
  "capabilities": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567892",
      "object": "capability",
      "name": "kyc",
      "status": "active",
      "disabled_reason": null,
      "currently_due": [],
      "disabled": null
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567893",
      "object": "capability",
      "name": "card_receive",
      "status": "pending",
      "disabled_reason": null,
      "currently_due": [],
      "disabled": null
    }
  ],
  "profile": {
    "individual": {
      "email": "riley@example.com",
      "ssn_last_four": null,
      "name": {
        "first_name": "Riley",
        "middle_name": null,
        "last_name": "Morgan",
        "suffix": null
      },
      "phone": {
        "number": "3107484186",
        "country_code": "1"
      },
      "birthdate": null,
      "address": null
    }
  },
  "terms_of_service": null,
  "metadata": {
    "platform_user_id": "u_123"
  },
  "livemode": false,
  "created": 1721010605
}

List all accounts

Returns a paginated list of accounts for your platform.

Parameters

statusstringoptional

Filter by account status. One of active, pending, or disabled.

typestringoptional

Filter by account type. One of individual or business.

external_idstringoptional

Filter by your platform's external identifier.

per_pageintegeroptional

Number of results to return. Defaults to 10, maximum 100.

pageintegeroptional

Page offset for pagination.

Returns

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

GET/v1/accounts

curl --request GET \
  --url 'https://api.framepayments.com/v1/accounts?type=individual&status=active' \
  --header 'Authorization: Bearer API_KEY'

RESPONSE

{
  "meta": {
    "page": 1,
    "has_more": true,
    "next": 2,
    "prev": null,
    "url": "/v1/accounts"
  },
  "data": [
    {
      "id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
      "object": "account",
      "type": "individual",
      "status": "active",
      "external_id": "usr_8675309",
      "capabilities": [
        {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891",
          "object": "capability",
          "name": "card_send",
          "status": "active",
          "disabled_reason": null,
          "currently_due": [],
          "disabled": null
        },
        {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567892",
          "object": "capability",
          "name": "kyc",
          "status": "active",
          "disabled_reason": null,
          "currently_due": [],
          "disabled": null
        }
      ],
      "profile": {
        "individual": {
          "email": "marcia@example.com",
          "ssn_last_four": "6789",
          "name": {
            "first_name": "Marcia",
            "middle_name": null,
            "last_name": "Longo",
            "suffix": null
          },
          "phone": {
            "number": "3107484186",
            "country_code": "1"
          },
          "birthdate": "1982-07-19",
          "address": {
            "line_1": "123 Main St",
            "line_2": null,
            "city": "Los Angeles",
            "state": "CA",
            "postal_code": "90001",
            "country": "US"
          }
        }
      },
      "terms_of_service": {
        "token": "tos_v1_2024",
        "accepted": true,
        "accepted_at": "2024-08-24T14:15:22Z"
      },
      "metadata": {},
      "livemode": false,
      "created": 1721010605
    },
    {
      "id": "7b03bf26-6394-4ee8-b56a-d38635bd14b1",
      "object": "account",
      "type": "individual",
      "status": "active",
      "external_id": null,
      "capabilities": [
        {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567894",
          "object": "capability",
          "name": "kyc",
          "status": "pending",
          "disabled_reason": null,
          "currently_due": [],
          "disabled": null
        },
        {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567895",
          "object": "capability",
          "name": "card_send",
          "status": "pending",
          "disabled_reason": null,
          "currently_due": [],
          "disabled": null
        }
      ],
      "profile": {
        "individual": {
          "email": "riley@example.com",
          "ssn_last_four": null,
          "name": {
            "first_name": "Riley",
            "middle_name": null,
            "last_name": "Morgan",
            "suffix": null
          },
          "phone": {
            "number": "3107484186",
            "country_code": "1"
          },
          "birthdate": null,
          "address": null
        }
      },
      "terms_of_service": null,
      "metadata": {},
      "livemode": false,
      "created": 1720924205
    }
  ]
}

Disable an account

Disables an account. Disabled accounts cannot initiate or receive payments and all associated capabilities are suspended. Contact Frame support to re-enable a disabled account.

Parameters

No parameters.

Returns

Returns the disabled account object.

DELETE/v1/accounts/:id

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

RESPONSE

{
  "id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
  "object": "account",
  "type": "individual",
  "status": "disabled",
  "external_id": "usr_8675309",
  "capabilities": [],
  "profile": {
    "individual": {
      "email": "marcia@example.com",
      "ssn_last_four": "6789",
      "name": {
        "first_name": "Marcia",
        "middle_name": null,
        "last_name": "Longo",
        "suffix": null
      },
      "phone": {
        "number": "3107484186",
        "country_code": "1"
      },
      "birthdate": null,
      "address": {
        "line_1": "123 Main St",
        "line_2": null,
        "city": "Los Angeles",
        "state": "CA",
        "postal_code": "90001",
        "country": "US"
      }
    }
  },
  "terms_of_service": {
    "token": "tos_v1_2024",
    "accepted": true,
    "accepted_at": "2024-08-24T14:15:22Z"
  },
  "metadata": {},
  "livemode": false,
  "created": 1721010605
}

Next steps

Onboarding Sessions — Use hosted sessions to collect identity and verification data
KYC — Identity verification for individual accounts
Billing — Assign fee plans and manage invoicing for accounts