Skip to main content
POST
/
api
/
accounts
Create Account
curl --request POST \
  --url https://api.example.com/api/accounts \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "encryptedAccountKey": "<string>"
}
'
{
  "success": true,
  "account": {
    "id": "<string>",
    "name": "<string>",
    "owner_id": "<string>",
    "created_at": "<string>"
  },
  "categoriesCopied": {
    "categories": 123,
    "subcategories": 123
  },
  "error": "<string>"
}
Creates a new account with the authenticated user as the owner. Automatically copies default categories and subcategories to the new account. Users can create up to 3 accounts.

​
Authentication

Requires authentication token and CSRF token.

​
Request Body

​
name
string
required
The name of the account. Must be a non-empty string.
​
encryptedAccountKey
string
Encrypted account key for envelope encryption. Used to encrypt sensitive data within the account.

​
Response

​
success
boolean
Indicates if the operation was successful
​
account
object
The created account object
​
categoriesCopied
object
Information about categories copied to the new account

​
Example Request

curl -X POST https://api.example.com/api/accounts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN" \
  -d '{
    "name": "Personal Finances",
    "encryptedAccountKey": "encrypted_key_string_here"
  }'

​
Example Response

{
  "success": true,
  "account": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Personal Finances",
    "owner_id": "user-uuid-here",
    "created_at": "2026-03-05T10:30:00.000Z"
  },
  "categoriesCopied": {
    "categories": 12,
    "subcategories": 48
  }
}

​
Error Responses

​
error
string
Error message describing what went wrong

​
400 Bad Request

{
  "error": "El nombre es requerido"
}
Returned when the account name is missing. 
{
  "error": "Account limit reached"
}
Returned when the user has already created 3 accounts (the maximum allowed).

​
401 Unauthorized

Returned when the authentication token is missing or invalid.

​
403 Forbidden

Returned when the CSRF token is missing or invalid.

​
Notes

  • Each user can create up to 3 accounts
  • Default categories are automatically copied to the new account
  • The user who creates the account becomes the owner with full permissions
  • An account_users entry is automatically created with role owner

Build docs developers (and LLMs) love

Get started for freeTalk to us