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.

nameobject

Object containing first_name, middle_name, last_name, and suffix.

emailstring

The individual's email address.

phoneobject

Object containing number and country_code.

birthdatenullable string

Date of birth in YYYY-MM-DD format. Required for KYC and age verification.

ssn_last_fournullable string

Last four digits of the Social Security Number. The full SSN is accepted during onboarding and stored encrypted — only the last four digits are returned via the API.

addressnullable object

Residential address containing line_1, line_2, city, state_or_province, postal_code, and country.

legal_business_namestringoptional

The registered legal name of the business.

doing_business_asnullable stringoptional

The business's trade name, if different from its legal name.

business_typestringoptional

The business entity type (e.g. llc, corporation, sole_proprietorship).

emailstringoptional

Business email address.

phoneobjectoptional

Object containing number and country_code.

websitenullable stringoptional

The business's website URL.

descriptionnullable stringoptional

A description of the business.

einnullable stringoptional

Employer Identification Number. Stored encrypted — only the last four digits are returned via the API.

mccnullable stringoptional

Merchant Category Code.

naicsnullable stringoptional

NAICS industry classification code.

addressobjectoptional

Business address containing line_1, line_2, city, state_or_province, postal_code, and country.

terms_of_servicenullable object

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

tokennullable string

The token identifying the version of terms accepted.

acceptedboolean

true if the account holder has accepted the terms of service.

accepted_atnullable datetime

ISO 8601 timestamp of when the terms were 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_or_province": "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.

nameobjectoptional

Object containing first_name, middle_name (optional), last_name, and suffix (optional).

emailstringrequired

The individual's email address.

phoneobjectoptional

Object containing number and country_code.

ssnstringoptional

Full 9-digit Social Security Number. Stored encrypted — only the last four digits are returned via the API.

ssn_last_fourstringoptional

Last four digits of the SSN, if the full SSN is not available.

addressobjectoptional

Object containing line_1, line_2 (optional), city, state_or_province, postal_code, and country.

birthdatestringoptional

Date of birth in YYYY-MM-DD format.

kyc_prefillobjectoptional

Records that KYC data was pre-filled, with confirmed_at, ip_address, and user_agent.

legal_business_namestringrequired

The registered legal name of the business.

business_typestringrequired

The business entity type.

emailstringrequired

Business email address.

phoneobjectoptional

Object containing number and country_code.

dbastringoptional

The business's trade name (doing business as), if different from its legal name.

websitestringoptional

The business's website URL.

descriptionstringoptional

A description of the business.

einstringoptional

9-digit Employer Identification Number. Stored encrypted.

mccstringoptional

Merchant Category Code.

naicsstringoptional

NAICS industry classification code.

addressobjectoptional

Object containing line_1, line_2 (optional), city, state_or_province, postal_code, and country.

terms_of_serviceobjectoptional

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

accepted_atdatetimeoptional

ISO 8601 timestamp of when the terms were accepted.

ip_addressstringoptional

IP address of the account holder at the time of acceptance.

user_agentstringoptional

User agent string from the account holder's browser at the time of acceptance.

tokenstringoptional

An optional token identifying the specific version of terms accepted.

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.

nameobjectoptional

Object containing first_name, middle_name (optional), last_name, and suffix (optional).

emailstringoptional

The individual's email address.

phoneobjectoptional

Object containing number and country_code.

birthdatestringoptional

Date of birth in YYYY-MM-DD format.

ssnstringoptional

Full 9-digit Social Security Number. Stored encrypted — only the last four digits are returned via the API.

ssn_last_fourstringoptional

Last four digits of the SSN, if the full SSN is not available.

addressobjectoptional

Object containing line_1, line_2 (optional), city, state_or_province, postal_code, and country.

kyc_prefillobjectoptional

Records that KYC data was pre-filled, with confirmed_at, ip_address, and user_agent.

legal_business_namestringoptional

The registered legal name of the business.

business_typestringoptional

The business entity type.

emailstringoptional

Business email address.

phoneobjectoptional

Object containing number and country_code.

dbastringoptional

The business's trade name (doing business as), if different from its legal name.

websitestringoptional

The business's website URL.

descriptionstringoptional

A description of the business.

einstringoptional

9-digit Employer Identification Number. Stored encrypted.

mccstringoptional

Merchant Category Code.

naicsstringoptional

NAICS industry classification code.

addressobjectoptional

Object containing line_1, line_2 (optional), city, state_or_province, postal_code, and country.

terms_of_serviceobjectoptional

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

accepted_atdatetimeoptional

ISO 8601 timestamp of when the terms were accepted.

ip_addressstringoptional

IP address of the account holder at the time of acceptance.

user_agentstringoptional

User agent string from the account holder's browser at the time of acceptance.

tokenstringoptional

An optional token identifying the specific version of terms accepted.

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_or_province": "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_or_province": "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

Accounts

Account types

Accounts and capabilities in frameOS

The Account object

Attributes

Individual profile attributes

Business profile attributes

Terms of service attributes

Create an account

Parameters

Individual parameters

Business parameters

Terms of service parameters

Returns

Update an account

Parameters

Individual parameters

Business parameters

Terms of service parameters

Returns

Retrieve an account

Parameters

Returns

List all accounts

Parameters

Returns

Disable an account

Parameters

Returns

Next steps