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.
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.
The account holder's profile. Contains either an individual or business sub-object depending on account type.
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": {},
"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 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": "647b828b-818d-4eab-8266-2311e5da3ffd",
"status": "pending",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "delisa_prosacco@stanton.test",
"ssn_last_four": null,
"name": {
"first_name": "Julius",
"middle_name": null,
"last_name": "Franecki",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1781115861,
"updated": 1781115861,
"livemode": false
},
{
"id": "3509d22d-bebf-4fa7-ae89-41caaf12bce3",
"status": "pending",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "shelly_kerluke@zboncak-erdman.test",
"ssn_last_four": null,
"name": {
"first_name": "Jaime",
"middle_name": null,
"last_name": "Marquardt",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1781115861,
"updated": 1781115861,
"livemode": false
},
{
"id": "25621ebd-157f-40c6-bf79-720ed3704ded",
"status": "pending",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "hettie.barton@anderson.example",
"ssn_last_four": null,
"name": {
"first_name": "Ahmad",
"middle_name": null,
"last_name": "Bins",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1781115861,
"updated": 1781115861,
"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": "5264d3d4-97c3-401d-b5f9-0a5d96bb1956",
"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": 1781115861,
"updated": 1781115861,
"livemode": false
}
Get account
Retrieves an existing account by ID, including its profile and current capability statuses.
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": "d8fb2bce-f950-4ad3-af2c-eb3854661eb2",
"status": "pending",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "kaley_streich@ryan-kuhic.test",
"ssn_last_four": null,
"name": {
"first_name": "Irwin",
"middle_name": null,
"last_name": "Ondricka",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1781115861,
"updated": 1781115861,
"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": "511bc6df-f67e-4720-b0d3-70a99c65ca70",
"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": "Faye",
"middle_name": null,
"last_name": "Gottlieb",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1781115861,
"updated": 1781115862,
"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": "ac16a676-465c-49b4-beac-7832dbc95cc3",
"status": "disabled",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "titus@anderson.example",
"ssn_last_four": null,
"name": {
"first_name": "Rudy",
"middle_name": null,
"last_name": "Pfeffer",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1781115862,
"updated": 1781115862,
"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": "626f9620-9073-4002-9d2e-67480d519802",
"status": "active",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "ahmed@sporer-kiehn.test",
"ssn_last_four": null,
"name": {
"first_name": "Lean",
"middle_name": null,
"last_name": "Corkery",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1781115862,
"updated": 1781115862,
"livemode": false
}
]
}
List account payment methods
Returns a paginated list of payment methods attached to a specific account.
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/a84cfe8a-609f-4655-ace3-0a18db80276c/payment_methods",
"has_more": false,
"prev": null,
"next": null
},
"data": [
{
"id": "610dfb6e-e320-4d28-9cc0-34f56d4381d0",
"customer_id": null,
"account_id": "a84cfe8a-609f-4655-ace3-0a18db80276c",
"billing": null,
"type": "card",
"object": "payment_method",
"created": 1781115862,
"updated": 1781115862,
"livemode": false,
"status": "active",
"card": {
"brand": "visa",
"exp_month": "03",
"exp_year": "31",
"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": "77f52865-fd3b-4483-851f-300284122ffb",
"status": "restricted",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "wilton@mayer.example",
"ssn_last_four": null,
"name": {
"first_name": "Rosalva",
"middle_name": null,
"last_name": "Marquardt",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1781115862,
"updated": 1781115862,
"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": "c143a4bf-7973-46b9-98eb-34d8b26b2585",
"status": "active",
"external_id": null,
"metadata": {},
"payout_payment_method_id": null,
"type": "individual",
"object": "account",
"terms_of_service": null,
"profile": {
"individual": {
"email": "rickie_wilderman@leannon-bartell.example",
"ssn_last_four": null,
"name": {
"first_name": "Meta",
"middle_name": null,
"last_name": "Trantow",
"suffix": null
},
"phone": {
"number": null,
"country_code": null
},
"address": null,
"birthdate": null
}
},
"capabilities": [],
"created": 1781115862,
"updated": 1781115862,
"livemode": false
}