Quickstart

Prefer the terminal? The visor CLI does these steps with visor auth login and visor tx add.

Create a token

Open Settings > Connected apps in Visor and find the Personal API card.

Give the token a name you will recognize, such as Spending spreadsheet.
Choose what the token can do. Choose Read and record transactions, because this quickstart records an expense.
Choose how long it is valid: 30, 90 (default), or 365 days. Never expires is also available, but a token with an expiry is safer.
Select Create token and copy the value that starts with visor_pat_.

Visor shows the token only once. Store it in a password manager or a secret store. If you lose it, revoke it and create a new one.

Store the token in an environment variable

export VISOR_TOKEN="visor_pat_..."

Keep the token out of source code, URLs, and logs.

List your spaces

curl https://api.visorfinance.app/v1/spaces \
  --header "Authorization: Bearer $VISOR_TOKEN" \
  --header "Accept: application/json"

The response lists every space you own or were invited to:

{
  "data": [
    {
      "id": "6f1c2a9e-1d7b-4c55-9a3e-2b8f0c4d5e61",
      "name": "Pessoal",
      "type": "personal",
      "default": true,
      "role": "owner"
    }
  ]
}

Use a space id to scope later requests to that space.

Find an account and a category

Replace SPACE_ID with an id from the previous step:

curl https://api.visorfinance.app/v1/spaces/SPACE_ID/accounts \
  --header "Authorization: Bearer $VISOR_TOKEN"

curl https://api.visorfinance.app/v1/spaces/SPACE_ID/categories \
  --header "Authorization: Bearer $VISOR_TOKEN"

Copy the id of the account that paid the expense, and the id of its category. A system category has a stable key, such as category.food_and_drinks, so a script can find it by key. See Spaces and reference data.

Record an expense

curl https://api.visorfinance.app/v1/spaces/SPACE_ID/transactions \
  --request POST \
  --header "Authorization: Bearer $VISOR_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 2026-10-01-padaria" \
  --data '{
    "account_id": "ACCOUNT_ID",
    "category_id": "CATEGORY_ID",
    "description": "Padaria",
    "amount": "42.90",
    "type": "debit",
    "transacted_at": "2026-10-01T08:30:00-03:00"
  }'

The response is 201 Created with the new transaction. The amount is a decimal string, and the transaction takes the currency of its account:

{
  "data": {
    "id": "9c1e4b2a-7d3f-4e8a-b6c5-1a2b3c4d5e6f",
    "account_id": "ACCOUNT_ID",
    "category_id": "CATEGORY_ID",
    "tag_ids": [],
    "amount": "42.90",
    "type": "debit",
    "currency_code": "BRL",
    "source": "manual",
    "status": "posted",
    "ignored": false,
    "description": "Padaria",
    "merchant_name": null,
    "notes": null,
    "transacted_at": "2026-10-01T11:30:00Z",
    "created_at": "2026-10-01T11:31:02Z",
    "updated_at": "2026-10-01T11:31:02Z"
  }
}

Retry safely

Send the same request again with the same Idempotency-Key. Visor does not record a second expense: it returns the expense it already has, with the header idempotent-replayed: true. Your script can retry a timeout without creating duplicates. See Idempotency.

See it in Visor

Open Transactions in Visor. The expense is in the account and the space you chose.

Next steps

Export your history and edit transactions in Transactions.
Find categories and tags in Spaces and reference data.
Read how authentication and scopes work.
Handle errors and rate limits in your client.

Get started

Essentials

Next steps

​Next steps

Next steps