Skip to main content
POST

Authorizations

Authorization
string
header
required

OAuth 2.1 authorization code flow with PKCE (S256 only) and exact redirect-URI matching. Clients register by Dynamic Client Registration (/api/oauth/register) or a Client ID Metadata Document. Discovery: /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp. Access tokens last one hour and refresh tokens rotate. Tokens carry the audience https://api.ai2fin.com/mcp and are accepted on /mcp and /api/integrations/v1 only. A request with no scope gets read:transactions write:transactions read:bills write:bills; write:expenses and webhooks:manage must be asked for explicitly.

Scopes

write:transactions

MCP: the write tools. Integration API: POST /transactions and POST /statements.

Headers

Idempotency-Key
string

Optional. 1 to 128 characters of letters, digits, _, ., : or -. Stored in the database for 24 hours per account and endpoint. A completed request with the same key is replayed (200, Idempotency-Replayed: true); a request still in progress with the same key returns 409 IDEMPOTENCY_IN_PROGRESS. A failed request releases its key so a retry runs. A key that does not match the pattern is ignored (the request runs without idempotency).

Maximum string length: 128
Pattern: ^[\w.:-]+$

Body

application/json
description
string
required
Maximum string length: 500
amount
number
required

Non-zero, at most 100,000,000 in magnitude. Negative is money out.

date
string<date-time>
required

ISO 8601, no later than one year ahead.

merchant
string
Maximum string length: 200
category
string
Maximum string length: 100
reference
string
Maximum string length: 200
primaryType
enum<string>
Available options:
income,
expense
isTaxDeductible
boolean

Response

Batch processed (or a replay of an earlier completed request with the same Idempotency-Key)

success
boolean
format
string
received
integer
created
integer
duplicates
integer
skippedPending
integer
skipped
integer
invalid
integer
errors
integer
deferred
integer
results
object[]