Update accounts
Use the account update endpoint to submit or modify information for a connected account.
Most onboarding actions are performed through account updates and related sub-resources.
Update an account
Submit updates using the account endpoint.
POST /v1/accounts/{account_id}
{
"business_profile": {
"name": "ACME Ltd",
"url": "https://example.com"
},
"company": {
"tax_id": "BG123456789"
}
}
Partial updates
Account updates are partial.
- Only the fields included in the request are modified
- Existing values remain unchanged
- Nested objects are merged, not replaced
You do not need to send the full account object. Send only the fields you intend to update.
Relationship to onboarding
Updates are the primary mechanism for satisfying requirements.
Typical flow:
Determine what fields are currently due.
Gather the required information from the user.
Send the data to the API.
Check if additional fields are required.
Side effects of updates
Updating account data may:
- Satisfy existing requirements
- Introduce new requirements
- Trigger verification processes
- Change capability status
An update does not guarantee that a requirement is resolved. Verification may still be required.
Validation
The API validates input data and returns structured errors.
Example error response
{
"error": {
"type": "invalid_request",
"code": "parameter_invalid",
"param": "company.tax_id",
"message": "Invalid tax ID"
}
}
Updating related resources
Some data must be updated through dedicated endpoints:
- Persons →
/v1/accounts/{account_id}/persons - External accounts →
/v1/accounts/{account_id}/external_accounts - Files →
/v1/files
Use the appropriate resource endpoint when updating structured sub-resources.
Idempotency
Account updates should be treated as idempotent operations.
If the same request is submitted multiple times:
- The resulting state should remain consistent
- Duplicate updates should not introduce inconsistencies
Best practices
- Always base updates on the latest account state
- Submit only the fields required to satisfy current requirements
- Handle validation errors at the field level
- Re-fetch the account after updates to confirm state
Summary
Account updates are:
- Partial and field-specific
- The primary mechanism for onboarding
- Closely tied to requirements and verification
- Responsible for driving account state forward
