Skip to main content
POST
/
api
/
transactions
Create Transaction
curl --request POST \
  --url https://api.example.com/api/transactions \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_id": "<string>",
  "date": "<string>",
  "description_encrypted": "<string>",
  "amount_encrypted": "<string>",
  "amount_sign": "<string>",
  "subcategory_id": "<string>",
  "bank_category_encrypted": "<string>",
  "bank_subcategory_encrypted": "<string>",
  "description": "<string>",
  "amount": 123,
  "bank_category": "<string>",
  "bank_subcategory": "<string>"
}
'
{
  "success": true,
  "transaction": {
    "id": "<string>",
    "account_id": "<string>",
    "date": "<string>",
    "subcategory_id": {},
    "description": "<string>",
    "amount": 123,
    "description_encrypted": "<string>",
    "amount_encrypted": "<string>",
    "amount_sign": "<string>",
    "bank_category": {},
    "bank_subcategory": {},
    "created_at": "<string>"
  },
  "error": "<string>"
}

​
Overview

This endpoint creates a new transaction for a specified account. It supports both encrypted and unencrypted transaction data to accommodate the application’s end-to-end encryption feature.

​
Authentication

Requires a valid authentication token. The transaction will be created for the authenticated user.

​
Request Body

The API accepts two formats: encrypted or unencrypted. The presence of description_encrypted determines which validation schema is used.
​
account_id
string
required
UUID of the account where the transaction will be created
​
date
string
required
Transaction date in YYYY-MM-DD format. Cannot be a future date.
​
description_encrypted
string
required
Encrypted transaction description. Must be a non-empty string containing the encrypted data.
​
amount_encrypted
string
required
Encrypted transaction amount. Must be a non-empty string containing the encrypted data.
​
amount_sign
string
required
Indicates whether the transaction is income or expense.
​
subcategory_id
string
UUID of the subcategory to assign to this transaction. Can be null.
​
bank_category_encrypted
string
Encrypted bank-assigned category (for imported transactions). Can be null.
​
bank_subcategory_encrypted
string
Encrypted bank-assigned subcategory (for imported transactions). Can be null.

​
Unencrypted Format (Legacy)

​
account_id
string
required
UUID of the account where the transaction will be created
​
date
string
required
Transaction date in YYYY-MM-DD format. Cannot be a future date.
​
description
string
required
Transaction description. Must be between 3 and 60 characters.
​
amount
number
required
Transaction amount. Must be a positive number. Use subcategory to indicate expense vs income.
​
subcategory_id
string
UUID of the subcategory to assign to this transaction. Can be null.
​
bank_category
string
Bank-assigned category (for imported transactions). Maximum 100 characters.
​
bank_subcategory
string
Bank-assigned subcategory (for imported transactions). Maximum 100 characters.

​
Response

​
success
boolean
Indicates whether the transaction was created successfully
​
transaction
object
The created transaction object

​
Examples

​
Encrypted Transaction Request

curl -X POST https://api.example.com/api/transactions \
  -H "Content-Type: application/json" \
  -H "Cookie: token=your-auth-token" \
  -d '{
    "account_id": "123e4567-e89b-12d3-a456-426614174000",
    "date": "2026-03-01",
    "description_encrypted": "U2FsdGVkX1+xxx...",
    "amount_encrypted": "U2FsdGVkX1+yyy...",
    "amount_sign": "negative",
    "subcategory_id": "987fcdeb-51a2-43f1-b789-123456789abc"
  }'

​
Encrypted Transaction Response

{
  "success": true,
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "account_id": "123e4567-e89b-12d3-a456-426614174000",
    "date": "2026-03-01T00:00:00.000Z",
    "description_encrypted": "U2FsdGVkX1+xxx...",
    "amount_encrypted": "U2FsdGVkX1+yyy...",
    "amount_sign": "negative",
    "subcategory_id": "987fcdeb-51a2-43f1-b789-123456789abc",
    "bank_category_encrypted": null,
    "bank_subcategory_encrypted": null,
    "created_at": "2026-03-05T10:30:00.000Z"
  }
}

​
Unencrypted Transaction Request

curl -X POST https://api.example.com/api/transactions \
  -H "Content-Type: application/json" \
  -H "Cookie: token=your-auth-token" \
  -d '{
    "account_id": "123e4567-e89b-12d3-a456-426614174000",
    "date": "2026-03-01",
    "description": "Grocery shopping at Whole Foods",
    "amount": 125.50,
    "subcategory_id": "987fcdeb-51a2-43f1-b789-123456789abc"
  }'

​
Unencrypted Transaction Response

{
  "success": true,
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "account_id": "123e4567-e89b-12d3-a456-426614174000",
    "date": "2026-03-01T00:00:00.000Z",
    "description": "Grocery shopping at Whole Foods",
    "amount": 125.50,
    "subcategory_id": "987fcdeb-51a2-43f1-b789-123456789abc",
    "bank_category": null,
    "bank_subcategory": null,
    "created_at": "2026-03-05T10:30:00.000Z"
  }
}

​
Error Responses

​
success
boolean
Always false for errors
​
error
string
Error message describing what went wrong

​
Common Errors

  • 400 Bad Request: Invalid parameters (e.g., invalid UUID, missing required fields, future date)
  • 401 Unauthorized: Missing or invalid authentication token
  • 404 Not Found: Account not found or user doesn’t have access

​
Example Error Response

{
  "success": false,
  "error": "account_id debe ser un UUID válido"
}

​
Notes

  • CSRF protection is enforced for this endpoint
  • The description field is sanitized before storage to prevent XSS attacks
  • When using encrypted format, the client is responsible for encrypting sensitive data
  • The amount_sign field is required for encrypted transactions to enable server-side calculations without decryption
  • Dates in the future are rejected by validation

Build docs developers (and LLMs) love

Get started for freeTalk to us