Accounts
Create and manage connected accounts. Accounts represent the merchants or end users on your platform who send payments, receive payouts, and complete verification flows. Create an account with the capabilities you need, prefill any information you already have, and use hosted onboarding to collect the rest.
export FRAME_API_KEY='sk_sandbox_...'
The Account object
Attributes
Unique identifier for the account
Object type identifier. Always account.
Account type. One of individual or business.
Current status. One of pending, active, restricted, or disabled.
An optional identifier from your own system. Must be unique per merchant.
A set of key-value pairs you can attach to the account for your own reference. Merchant-internal — only returned to secret-key requests; omitted for publishable-key responses.
ID of the payment method used for payouts to this account. Merchant-internal — only returned to secret-key requests; omitted for publishable-key responses.
The account holder's profile (PII). Contains either an individual or business sub-object depending on account type. Only returned to secret-key requests, or to an onboarding-session client secret reading its own account; omitted for publishable-key responses.
Capabilities requested for this account. Each object includes name, status, currently_due, and disabled_reason.
Record of when and how the account holder accepted your platform's terms of service. null if not yet accepted.
Ordered onboarding steps for this account. Each step reflects a capability requirement and its current completion status.
Unix timestamp of when the account was created
Unix timestamp of when the account was last updated
true if the account exists in live mode, false if in test mode
{
"id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
"object": "account",
"type": "individual",
"status": "active",
"external_id": "usr_8675309",
"metadata": {},
"payout_payment_method_id": null,
"profile": {
"individual": {
"name": {
"first_name": "Marcia",
"middle_name": null,
"last_name": "Longo",
"suffix": null
},
"email": "marcia@example.com",
"phone": {
"number": "3107484186",
"country_code": "1"
},
"ssn_last_four": "6789",
"birthdate": null,
"address": {
"line_1": "123 Main St",
"line_2": null,
"city": "Los Angeles",
"state": "CA",
"postal_code": "90001",
"country": "US"
}
},
"business": {
"legal_business_name": "Acme Corp",
"doing_business_as": null,
"business_type": "llc",
"email": "billing@acme.com",
"phone": {
"number": "2125550100",
"country_code": "1"
},
"website": "https://acme.com",
"description": null,
"ein": null,
"mcc": "5734",
"naics": "519130",
"same_physical_and_legal_address": true,
"address": {
"line_1": "100 Broadway",
"line_2": "Suite 200",
"city": "New York",
"state": "NY",
"postal_code": "10005",
"country": "US"
},
"physical_address": {
"line_1": "55 Market St",
"line_2": "Floor 3",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
}
}
},
"capabilities": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891",
"object": "capability",
"name": "kyc",
"status": "active",
"disabled_reason": null,
"currently_due": [],
"disabled": null
},
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567892",
"object": "capability",
"name": "card_receive",
"status": "pending",
"disabled_reason": null,
"currently_due": [],
"disabled": null
}
],
"terms_of_service": {
"token": "tos_v1_2024",
"accepted": true,
"accepted_at": "2024-08-24T14:15:22Z"
},
"steps": [
{
"key": "kyc",
"status": "pending",
"label": "Verify your identity",
"fields": [
"individual.name.first_name",
"individual.name.last_name"
],
"currently_due": [
"individual.name.first_name"
]
}
],
"created": 1721010605,
"updated": 1721010605,
"livemode": false
}
List beneficial owners
Returns the beneficial-owner roster for a business account — every individual registered as an owner and/or controller, with their roles, ownership percentage, and verification status. Results include both directly-created owners and invited owners who completed their own details.
Path parameters
The ID of the business account whose roster to list.
Returns
Returns the roster
curl --request GET \
--url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/beneficial_owners \
--header 'Authorization: Bearer API_KEY'
{
"data": [
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "pending",
"object": "beneficial_owner",
"account_id": "00000000-0000-4000-8000-000000000002",
"first_name": "Ignacio",
"middle_name": null,
"last_name": "Kulas",
"suffix": null,
"email": "clint_wilderman@oconnell-mueller.test",
"roles": [
"owner",
"controller"
],
"percent_ownership": 50,
"created": 1745107200,
"updated": 1745107200,
"livemode": false
}
]
}
Create beneficial owner
Adds a beneficial owner to a business account's roster. Pass invite: true to email the owner an invitation to complete their own identity details; when inviting, you only need name, email, and roles. Without an invite, supply the full identity payload directly (phone verification is waived for directly-created owners).
Path parameters
The ID of the business account to add the owner to.
Body parameters
Returns
Returns the new owner
curl --request POST \
--url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/beneficial_owners \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"first_name": "Janet",
"last_name": "Jones",
"email": "janet@example.com",
"roles": [
"owner",
"controller"
]
}'
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "completed",
"object": "beneficial_owner",
"account_id": "00000000-0000-4000-8000-000000000002",
"first_name": "Janet",
"middle_name": null,
"last_name": "Jones",
"suffix": null,
"email": "janet@example.com",
"roles": [
"owner",
"controller"
],
"percent_ownership": 50,
"created": 1745107200,
"updated": 1745107200,
"livemode": false
}
Show beneficial owner
Retrieves a single beneficial owner by ID, scoped to the given business account. Returns the owner's identity details, roles, ownership percentage, and current verification status.
Path parameters
The ID of the business account the owner belongs to.
The ID of the beneficial owner.
Returns
Returns the owner
curl --request GET \
--url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/beneficial_owners/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "pending",
"object": "beneficial_owner",
"account_id": "00000000-0000-4000-8000-000000000002",
"first_name": "Shari",
"middle_name": null,
"last_name": "Daniel",
"suffix": null,
"email": "grisel@hoeger.test",
"roles": [
"owner",
"controller"
],
"percent_ownership": 50,
"created": 1745107200,
"updated": 1745107200,
"livemode": false
}
Update beneficial owner
Updates a beneficial owner's identity details, roles, or ownership percentage. Omitted fields are left unchanged; pass roles to replace the owner's role set.
Blank values for identity fields (email, phone_number, ssn) and address fields are ignored rather than cleared — existing stored values are preserved. Verification status only moves forward: completing an owner's identity details upgrades their status, and updates never downgrade it or trigger a new invitation (use the resend-invite endpoint for that).
Path parameters
The ID of the business account the owner belongs to.
The ID of the beneficial owner to update.
Body parameters
Returns
Returns the updated owner
curl --request PATCH \
--url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/beneficial_owners/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "pending",
"object": "beneficial_owner",
"account_id": "00000000-0000-4000-8000-000000000002",
"first_name": "Janet",
"middle_name": null,
"last_name": "Jones",
"suffix": null,
"email": "janet@example.com",
"roles": [
"owner"
],
"percent_ownership": 40,
"created": 1745107200,
"updated": 1745107200,
"livemode": false
}
Delete beneficial owner
Removes a beneficial owner from the business account's roster. Returns 204 No Content on success; any pending invitation for the owner is invalidated.
Path parameters
The ID of the business account the owner belongs to.
The ID of the beneficial owner to remove.
curl --request DELETE \
--url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/beneficial_owners/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
Resend beneficial owner invite
Re-sends the invitation email to a beneficial owner who was created with invite: true but has not yet completed their identity details. Returns the owner object unchanged.
Path parameters
The ID of the business account the owner belongs to.
The ID of the beneficial owner to re-invite.
Returns
Returns the owner
curl --request POST \
--url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/beneficial_owners/a70cd72f-e74a-40f2-96a2-3f60714aac4a/resend_invite \
--header 'Authorization: Bearer API_KEY'
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "invite_sent",
"object": "beneficial_owner",
"account_id": "00000000-0000-4000-8000-000000000002",
"first_name": "Janet",
"middle_name": null,
"last_name": "Jones",
"suffix": null,
"email": "janet@example.com",
"roles": [
"owner",
"controller"
],
"percent_ownership": null,
"created": 1745107200,
"updated": 1745107200,
"livemode": false
}
Confirm roster
Attests that the beneficial-owner roster for the business account is complete and accurate. Satisfies the account's beneficial_owners_collected onboarding requirement and records the attestation (with request IP and user agent) for compliance. Returns the updated account object.
Fails with a validation error unless the roster has at least one person with the owner role, at least one with the controller role, and a combined ownership percentage of 100% or less. The roster remains editable after confirmation — confirm again after changes; each successful call re-stamps the recorded certification.
Path parameters
The ID of the business account whose roster to confirm.
Returns
Returns the account
curl --request POST \
--url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/beneficial_owners/confirm \
--header 'Authorization: Bearer API_KEY'
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "pending",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "business",
"object": "account",
"terms_of_service": null,
"profile": {
"business": {
"legal_business_name": "Beer-Altenwerth",
"doing_business_as": null,
"business_type": "single_member_llc",
"email": "sammy@kuhn.example",
"website": null,
"description": null,
"ein_last_four": null,
"mcc": null,
"naics": null,
"same_physical_and_legal_address": true,
"phone": {
"number": null,
"country_code": null
},
"address": null,
"physical_address": null
}
},
"capabilities": [],
"created": 1745107200,
"updated": 1745107200,
"livemode": false
}
List accounts
Returns a paginated list of accounts for your platform. Filter by status, type, or external_id to narrow results. Results are returned in reverse chronological order.
Query parameters
Page number for pagination. Defaults to 1.
Number of results per page. Defaults to 10, maximum 100.
Filter by account status. One of active, pending, restricted, or disabled.
Filter by account type. One of individual or business.
Filter by your platform's external identifier.
When true, includes disabled accounts in results. Defaults to false.
Returns
A paginated list of accounts.
curl --request GET \
--url https://api.framepayments.com/v1/accounts \
--header 'Authorization: Bearer API_KEY'
{
"meta": {
"page": 1,
"url": "/v1/accounts?status=",
"has_more": false,
"prev": null,
"next": null
},
"data": [
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "pending",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "alana@price.test",
"ssn_last_four": null,
"name": {
"first_name": "Giuseppe",
"middle_name": null,
"last_name": "Brakus",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1745107200,
"updated": 1745107200,
"livemode": false
},
{
"id": "00000000-0000-4000-8000-000000000002",
"status": "pending",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "bobbye@bruen-lehner.test",
"ssn_last_four": null,
"name": {
"first_name": "Santiago",
"middle_name": null,
"last_name": "Maggio",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1745107200,
"updated": 1745107200,
"livemode": false
},
{
"id": "00000000-0000-4000-8000-000000000003",
"status": "pending",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "jewell@rath-wilkinson.example",
"ssn_last_four": null,
"name": {
"first_name": "Alexandra",
"middle_name": null,
"last_name": "Streich",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1745107200,
"updated": 1745107200,
"livemode": false
}
]
}
Create account
Creates a new account. Pass the account type, any capabilities to request, and known profile information. Frame 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.
Body parameters
Account type. One of individual or business.
Capability names to request for the account (e.g. ["kyc", "card_receive"]). Pass an array of strings — not an array of objects.
An optional identifier from your own system. Must be unique per merchant.
Record of the account holder's acceptance of your platform's terms of service.
A set of key-value pairs to attach to the account for your own reference.
Profile information for the account holder. Contains either an individual or business sub-object.
Returns
Returns the newly created account object along with the current status of any requested capabilities.
curl --request POST \
--url https://api.framepayments.com/v1/accounts \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"type": "individual",
"profile": {
"individual": {
"name": {
"first_name": "Marcia",
"middle_name": null
},
"email": "marcia@example.com"
},
"business": {
"legal_business_name": "Acme Corp",
"doing_business_as": null,
"business_type": "llc",
"email": "billing@acme.com",
"website": "https://acme.com"
}
}
}'
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "pending",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "john.doe@example.com",
"ssn_last_four": null,
"name": {
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1745107200,
"updated": 1745107200,
"livemode": false
}
Get account
Retrieves an existing account by ID, including its profile and current capability statuses.
Can be called with a secret key, or with a publishable key for client-side checkout. The publishable-key response omits profile, metadata, and payout_payment_method_id.
Path parameters
Account ID
Returns
Returns the account object with current capability statuses.
curl --request GET \
--url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "pending",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "rosia.wyman@lakin.test",
"ssn_last_four": null,
"name": {
"first_name": "Alita",
"middle_name": null,
"last_name": "Will",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1745107200,
"updated": 1745107200,
"livemode": false
}
Update 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.
Path parameters
Account ID
Body parameters
An identifier from your own system to associate with the account. Must be unique per merchant.
A set of key-value pairs to attach to the account for your own reference.
Record of the account holder's acceptance of your platform's terms of service.
Updated profile information for the account holder. Contains either an individual or business sub-object.
Returns
Returns the updated account object with current capability statuses.
curl --request PATCH \
--url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "pending",
"external_id": "ext_updated_123",
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "updated@example.com",
"ssn_last_four": null,
"name": {
"first_name": "Tamatha",
"middle_name": null,
"last_name": "Brown",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1745107200,
"updated": 1745107200,
"livemode": false
}
Disable account
Disables an account. Disabled accounts cannot initiate or receive payments and all associated capabilities are suspended. This is a soft delete — the account record is retained. Contact Frame support to re-enable a disabled account.
Path parameters
Account ID
Returns
Returns the disabled account object.
curl --request DELETE \
--url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "disabled",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "lucius.klocko@keebler.test",
"ssn_last_four": null,
"name": {
"first_name": "Emilio",
"middle_name": null,
"last_name": "McGlynn",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1745107200,
"updated": 1745107200,
"livemode": false
}
Search accounts
Search accounts with advanced filters. Supports filtering by email (partial match), external ID, type, status, and creation date range.
Query parameters
Filter by email address (partial match).
Filter by your platform's external identifier.
Filter by account type. One of individual or business.
Filter by account status. One of active, pending, restricted, or disabled.
Return only accounts created before this Unix timestamp.
Return only accounts created after this Unix timestamp.
Returns
A paginated list of matching accounts.
curl --request GET \
--url https://api.framepayments.com/v1/accounts/search \
--header 'Authorization: Bearer API_KEY'
{
"meta": {
"page": 1,
"url": "/v1/accounts/search?status=",
"has_more": false,
"prev": null,
"next": null
},
"data": [
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "active",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "marlon@dickinson.test",
"ssn_last_four": null,
"name": {
"first_name": "Alonzo",
"middle_name": null,
"last_name": "Blick",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1745107200,
"updated": 1745107200,
"livemode": false
}
]
}
List account payment methods
Returns a paginated list of payment methods attached to a specific account.
Can be called with a secret key, or with a publishable key for client-side checkout.
Path parameters
Account ID
Returns
A paginated list of payment methods for the account.
curl --request GET \
--url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/payment_methods \
--header 'Authorization: Bearer API_KEY'
{
"meta": {
"page": 1,
"url": "/v1/accounts/00000000-0000-4000-8000-000000000001/payment_methods",
"has_more": false,
"prev": null,
"next": null
},
"data": [
{
"id": "00000000-0000-4000-8000-000000000002",
"customer_id": null,
"account_id": "00000000-0000-4000-8000-000000000001",
"billing": null,
"type": "card",
"object": "payment_method",
"created": 1745107200,
"updated": 1745107200,
"livemode": false,
"status": "active",
"card": {
"brand": "visa",
"exp_month": "09",
"exp_year": "30",
"issuer": null,
"currency": null,
"segment": null,
"type": null,
"last_four": "4242"
}
}
]
}
Restrict account
Restricts an account, preventing it from initiating or receiving payments. The account record is retained and can be unrestricted. Use this for temporary holds — use disable for permanent deactivation.
Path parameters
Account ID
Returns
Returns the restricted account object.
curl --request POST \
--url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/restrict \
--header 'Authorization: Bearer API_KEY'
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "restricted",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "bridgette@runte-stark.test",
"ssn_last_four": null,
"name": {
"first_name": "Henry",
"middle_name": null,
"last_name": "King",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1745107200,
"updated": 1745107200,
"livemode": false
}
Unrestrict account
Removes a restriction from an account, restoring it to its previous active state and re-enabling payments.
Path parameters
Account ID
Returns
Returns the account object with its restriction removed.
curl --request POST \
--url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/unrestrict \
--header 'Authorization: Bearer API_KEY'
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "active",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "clement_wyman@muller-mills.example",
"ssn_last_four": null,
"name": {
"first_name": "Shanelle",
"middle_name": null,
"last_name": "Walsh",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1745107200,
"updated": 1745107200,
"livemode": false
}