> ## Documentation Index > Fetch the complete documentation index at: https://www.finta.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create rule > Saves a company automation rule and returns its complete definition. Requires API access: Manage and Accounting setup: Manage. Historical application additionally requires Transactions: Manage, rechecked at execution. apply_to_existing_transactions is a strict boolean defaulting to true; false saves a future-only rule. A 201 confirms saving, not completion of historical application. Requested work is saved durably and recovered after enqueue failures. No public job, polling endpoint, or Idempotency-Key is required. The application flag is never returned as saved state. Historical eligibility is approved uncategorized transactions; department actions additionally consider missing-department transactions and never replace assigned departments. Existing priority, automation limits and rollback behavior apply. Accounting-date offsets apply only on import; mixed rules can apply other actions historically. No bulk transaction cap or split exclusion applies. A pending run is cancelled by a successful edit or delete before it starts. Running work is serialized against edits/deletes; callers can retry a busy mutation. Failed historical application does not delete the saved rule. There is no feature flag. Exact duplicates in the same company return 409 rule_already_exists with the accessible existing rule ID in the message, without another run. Condition and action order and case-insensitive text condition casing do not distinguish definitions; the application flag does not distinguish them. After an uncertain response, an identical retry may return that conflict: retrieve the existing rule instead of requesting another run. Different actions are not exact duplicates. Unknown keys, legacy write fields, null actions, wrong types, reversed ranges and unsupported combinations return 400. Unavailable references return 404 without revealing foreign resources. ## OpenAPI ````yaml /openapi.yaml post /rules openapi: 3.0.3 info: title: Finta API version: '1.0' description: > The Finta API provides programmatic access to your company's financial data, including transactions, journal entries, categories, financial reports, and the team directory. ## Authentication Each API key is scoped to a single company. There is no company ID parameter. The key already knows which company it belongs to. If you have access to multiple companies, create a separate key for each. A key acts as its owner; it does not have a separate permission snapshot. The owner must currently have **API access: Manage**, plus the permission required by the endpoint: | Endpoint | Required permission | |----------|---------------------| | `GET /company` | Company: View | | `GET /team` | Team & access: View | | `DELETE /team/invitations/{id}` | Team & access: Manage; target-management limits apply. No additional Growth/RBAC gate. | | `POST /team/invitations/{id}/resend` | Team & access: Manage; target-management limits apply. No additional Growth/RBAC gate. | | `PATCH /team/invitations/{id}` | Team & access: Manage; RBAC and active/trialing Growth required, with grant and target limits. | | `POST /team/invitations` | Team & access: Manage; requested grants must also be allowed for the person and plan. | | `GET /categories`, `GET /departments`, `GET /rules`, `GET /rules/{id}` | Accounting setup: View | | `DELETE /rules/{id}` | Accounting setup: Manage and Transactions: Manage, including absent retries | | `GET /integrations` | Integrations: View | | `GET /reports/*` | Reports: View | | `GET /accounts`, `GET /cards`, `GET /transactions`, `GET /transactions/{id}` | Transactions: View | | `POST /transactions/bulk/update`, `GET /jobs/{id}` | Transactions: Manage | | `PATCH /transactions/{id}`, `POST /accounts`, `POST /transaction_uploads` | Transactions: Manage | | `GET /journal_entries`, `GET /journal_entries/{id}`, `GET /aggregations/total`, `GET /aggregations/totals`, `GET /parties/merchants` | Reports: View | Permission changes apply to the next request. Removing API access permanently revokes the owner's active keys for that company; restoring access requires creating a new key. Authenticate by including your API key in the `Authorization` header: ``` Authorization: Bearer finta_... ``` ### Key prefix convention Every Finta credential is prefixed so it can be recognized at a glance in logs, error messages, and secret scanners. Today there is one credential type and its prefix is `finta_`. As additional credential or token types are introduced (for example restricted keys or webhook signing secrets), each will have its own distinct prefix that stacks on the brand prefix (e.g. `finta__...`). Treat the prefix as load-bearing: do not strip it before sending, and do not assume a missing or unknown prefix is still a Finta credential. ## Rate Limits The API enforces two independent limits. Both surface as `429 Too Many Requests`, but they are distinct error codes with different retry guidance. ### Per-minute burst limit Authenticated requests are limited to **6,000 requests per 60 seconds** (100 per second) per API key. Unauthenticated requests (missing or invalid key) are limited to **120 requests per 60 seconds** per IP address. The window is **fixed**, not rolling. Each 60-second wall-clock interval is its own counter; all requests within that interval share it, and the counter resets to 0 in a single step at the next boundary. Available budget jumps from `0` back to the full bucket size (`6000` for authenticated API keys, `120` for unauthenticated IP buckets) instantaneously at the boundary, rather than aging out one slot at a time. Trust `X-RateLimit-Reset` for the exact reset timestamp. Successful responses and burst-limit rejections include the following headers. Do not assume they are present on other errors: early authentication, authorization, and monthly-limit rejections can omit them. This describes existing header behavior, not a new quota policy. | Header | Description | |--------|-------------| | `X-RateLimit-Limit` | Maximum requests per window (`6000` for authenticated requests, `120` for unauthenticated). | | `X-RateLimit-Remaining` | Requests remaining in the current window. | | `X-RateLimit-Reset` | Unix timestamp when the window resets. | On a 429 for this case, an additional header is included: | Header | Description | |--------|-------------| | `Retry-After` | Number of seconds until the next request is safe. | The error body is `type: rate_limit_error` / `code: rate_limit_exceeded`. **Retry guidance:** This case is retryable. Honor `Retry-After` as the minimum wait, then apply exponential backoff with jitter for any retries beyond the first (cap at a few minutes; abandon after a small number of attempts to avoid retry storms). Do not retry tighter than `Retry-After`. ### Monthly per-company limit Each company has a monthly cap on total API calls, independent of the per-minute burst: | Plan | Monthly cap | |------|-------------| | Formation | 10 | | Startup | 300 | | Growth | 30,000 | Counts reset at **midnight Pacific Time (US & Canada)** on the 1st of each month. This is the Finta application's configured time zone; the cap is computed in that zone, not in UTC. Consumers in other time zones should convert the local-midnight Pacific boundary to their own clock; note that the absolute UTC offset shifts by one hour twice a year for daylight saving (PST is UTC-8, PDT is UTC-7). Blocked requests are not counted toward the limit. The error body is `type: limit_error` / `code: monthly_limit_exceeded`, and the `message` field includes the reset date in human-readable form. **Retry guidance:** This case is **not retryable in the short term.** No `Retry-After` header is sent, deliberately, because the only meaningful remediation is to upgrade the plan (Settings -> Plans at app.finta.com) or wait until the 1st of the next month. Naive retry loops should branch on `error.code` and stop retrying when they see `monthly_limit_exceeded`. SDKs that auto-retry on 429 should look at `error.code` (or the absence of `Retry-After`) before re-issuing. A temporary company limit override, set by Finta support for the current month, may change the allowance and the wording of the monthly-limit message. It applies to every user and API key in the company. The error code and no-short-term-retry rule remain unchanged. ## Pagination List endpoints use cursor-based pagination. Pass `limit` to control page size (default 100, max 500). To fetch the next page, pass `starting_after` with the `next_cursor` value from the previous response. Responses include `object: "list"`, `url` (the canonical path of the collection, relative to the API host), `has_more` (whether more results exist), `next_cursor` (an opaque value to pass unchanged as `starting_after`), and `data` (the page of items). ## Amounts Every monetary field in the API follows two non-negotiable rules: 1. **Integer cents.** Monetary values are integers, never floats and never formatted strings. `$499.00` is `49900`. `$1,500.00` is `150000`. Divide by 100 to get dollars. This avoids floating-point precision errors in financial calculations. 2. **`_cents` suffix.** The field name always ends in `_cents` (e.g. `amount_cents`, `balance_cents`, `total_cents`, `net_income_cents`, `change_in_cash_cents`, `cash_cents`). If a field name does not end in `_cents`, it is not a monetary value. These rules apply to every monetary field across every endpoint (transactions, journal entries, income statement, balance sheet, cash flow). There are no exceptions and there is no "summary" or "display" sibling field that returns the same amount in dollars or as a string. If you encounter a field that appears to hold a monetary value but does not end in `_cents`, or whose value is not an integer, treat it as a bug and report it. Sign conventions: - **Income statement**: revenue/income amounts are positive, expense amounts are negative. Summing every section's `total_cents` yields net income without sign-flipping. - **Balance sheet**: `balance_cents` carries the natural-sign cumulative balance for that account at the report date. - **Cash flow**: `amount_cents` is positive for cash inflows and negative for cash outflows. ## Errors Errors return a consistent JSON structure: ```json { "error": { "type": "invalid_request_error", "code": "resource_missing", "message": "The requested resource was not found.", "doc_url": "https://www.finta.com/docs/api-reference/errors#resource_missing" } } ``` ### Status codes | Status | Meaning | |--------|---------| | `200 OK` | Request succeeded. | | `201 Created` | A new resource was created, such as an invitation, an account, or a transaction upload draft. | | `400 Bad Request` | Request was malformed or had invalid parameters. | | `401 Unauthorized` | The bearer credential is missing, malformed, or unrecognized. The fix is to obtain a valid API key. | | `403 Forbidden` | The API key is valid, but the caller does not have permission to access the resource. The fix is to regain the required company or product-area access. See the `Forbidden` response component for the specific codes. | | `404 Not Found` | The requested resource, or the endpoint itself, does not exist. Unknown or renamed paths (for example an old hyphenated report path like `/reports/income-statement` instead of `/reports/income_statement`) return this same envelope with `type: invalid_request_error` and `code: resource_missing`, as JSON, regardless of the `Accept` header. | | `422 Unprocessable Entity` | Invitation data failed validation, for example an invalid email or a conflicting invitation or existing teammate. | | `429 Too Many Requests` | Either the per-minute burst rate limit (retryable, with `Retry-After`) or the monthly per-company API call limit (not retryable in the short term, no `Retry-After`). Branch on `error.code` to distinguish the two and avoid retry storms on monthly exhaustion. See the Rate Limits section for the full retry guidance. | | `5xx` | An unexpected error on Finta's side. Retry with exponential backoff. | The `error.type` and `error.code` fields are stable identifiers safe to switch on programmatically. The `error.message` is human-readable and may change without notice. servers: - url: https://app.finta.com/api/v1 description: Production security: - bearerAuth: [] tags: - name: Company description: Retrieve company metadata - name: Team description: Retrieve company members and manage invitations - name: Categories description: List your chart of accounts categories - name: Rules description: Company automation rule definitions. - name: Departments description: List the departments available to the authenticated company - name: Integrations description: List the authenticated company's integrations and their connection status - name: Aggregations description: >- Compute totals for one category and its descendants, as a single figure or grouped by merchant or month - name: Transactions description: > Transactions are what your bank shows you: a single line like "AWS charged you $499." Most API consumers want transactions. For accounting-level detail, see Journal Entries. Amounts are in cents (e.g. `amount_cents: 49900` = $499.00). - name: Journal Entries description: > Journal entries are the accounting records that transactions create. A single $499 AWS charge becomes two journal entries: debit Software $499, credit Cash $499 (double-entry bookkeeping). Use journal entries when you need accounting-level detail. Amounts are in cents (e.g. `amount_cents: 49900` = $499.00). - name: Parties description: Discover observed counterparties for category-scoped financial queries. - name: Reports description: > Financial statements: income statement, balance sheet, and cash flow. Each report returns the complete statement for a single period. You cannot filter to one category or request multiple periods in one call. paths: /rules: post: tags: - Rules summary: Create rule description: >- Saves a company automation rule and returns its complete definition. Requires API access: Manage and Accounting setup: Manage. Historical application additionally requires Transactions: Manage, rechecked at execution. apply_to_existing_transactions is a strict boolean defaulting to true; false saves a future-only rule. A 201 confirms saving, not completion of historical application. Requested work is saved durably and recovered after enqueue failures. No public job, polling endpoint, or Idempotency-Key is required. The application flag is never returned as saved state. Historical eligibility is approved uncategorized transactions; department actions additionally consider missing-department transactions and never replace assigned departments. Existing priority, automation limits and rollback behavior apply. Accounting-date offsets apply only on import; mixed rules can apply other actions historically. No bulk transaction cap or split exclusion applies. A pending run is cancelled by a successful edit or delete before it starts. Running work is serialized against edits/deletes; callers can retry a busy mutation. Failed historical application does not delete the saved rule. There is no feature flag. Exact duplicates in the same company return 409 rule_already_exists with the accessible existing rule ID in the message, without another run. Condition and action order and case-insensitive text condition casing do not distinguish definitions; the application flag does not distinguish them. After an uncertain response, an identical retry may return that conflict: retrieve the existing rule instead of requesting another run. Different actions are not exact duplicates. Unknown keys, legacy write fields, null actions, wrong types, reversed ranges and unsupported combinations return 400. Unavailable references return 404 without revealing foreign resources. operationId: createRule requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RuleCreate' example: conditions: - field: merchant operator: contains value: Cursor actions: merchant: Cursor AI apply_to_existing_transactions: true responses: '201': description: Saved rule; historical application may still be queued. content: application/json: schema: $ref: '#/components/schemas/Rule' '400': description: Invalid input. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthenticated. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Missing operation permission or API access. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Unavailable reference. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Exact duplicate; message includes the existing rule ID. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Existing API rate or usage limit. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- An existing duplicate has not received a public ID yet. Retry after the ID rollout completes; no extra rule or historical request is created. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: RuleCreate: type: object additionalProperties: false required: - conditions - actions properties: conditions: type: array minItems: 1 description: >- Nonempty flat AND list. Repeated fields are allowed; all constraints must match. items: $ref: '#/components/schemas/RuleWriteCondition' actions: allOf: - $ref: '#/components/schemas/RuleActions' - type: object properties: merchant: maxLength: 40 description: >- Nonempty supported subset. Explicit nulls are rejected. Categories must be selectable and departments assignable; nonzero offsets cannot accompany Asset categories. apply_to_existing_transactions: type: boolean default: true description: >- Create-only switch requesting asynchronous historical application. False saves for future matching only. A saved response does not confirm execution completed. Rule: type: object additionalProperties: false required: - id - object - conditions - actions description: >- The complete saved company automation definition. IDs are stable opaque rule_ identifiers, including for historical rules. No public condition IDs, priority, enable state, or historical application status are exposed. The create-time application flag is not response state. properties: id: type: string pattern: ^rule_[A-Za-z0-9]+$ object: type: string enum: - rule conditions: type: array minItems: 1 description: >- Flat AND conditions; repeated fields express multiple constraints. Text matches are case-insensitive. items: $ref: '#/components/schemas/RuleCondition' actions: $ref: '#/components/schemas/RuleActions' Error: type: object required: - error properties: error: type: object required: - type - code - message - doc_url properties: type: type: string enum: - authentication_error - permission_error - invalid_request_error - rate_limit_error - limit_error - api_error description: >- The error category. `authentication_error` (401) means the bearer credential was missing, malformed, or unrecognized. `permission_error` (403) means the credential was valid but the caller is not allowed to access the resource. `invalid_request_error` covers invalid parameters, unavailable resources, invitation validation failures, and requests that conflict with current state (409). `rate_limit_error` is for per-minute burst limits (retry shortly). `limit_error` is for monthly API call limits per company (upgrade or wait for reset). `api_error` denotes an operation failure on the server (500), or temporarily unavailable rule definitions (503 rules_not_ready). Retry with exponential backoff; persistent 503 errors require operator attention. code: type: string enum: - invalid_api_key - user_inactive - user_removed_from_company - company_closed - subscription_required - staging_access_denied - insufficient_permission - resource_missing - parameter_missing - category_update_failed - transaction_update_failed - rate_limit_exceeded - monthly_limit_exceeded - invalid_date_range - invalid_date - invalid_request - idempotency_key_conflict - plan_upgrade_required - feature_disabled - invitation_invalid - invitation_create_failed - permissions_update_failed - invitation_resend_failed - invitation_revoke_failed - integration_not_connectable - integration_already_connected - connect_link_in_progress - connect_link_failed - rules_not_ready - rule_already_exists - rule_busy - rule_deletion_failed - account_create_failed - upload_committed - upload_commit_failed description: A specific error code. message: type: string description: A human-readable description of the error. doc_url: type: string format: uri description: A link to documentation about this error. example: https://www.finta.com/docs/api-reference/errors#invalid_api_key param: type: string nullable: true description: The parameter that caused the error, if applicable. RuleWriteCondition: description: >- merchant matches the assigned merchant name; description matches the transaction description. account_id and card_id must be accessible exact stable identities. Legacy account and card_name text conditions are read-only compatibility fields and are rejected on create. Combined account/card references require a provable relationship; incompatible or unverifiable pairs are rejected. transaction_type currently represents transfer only; it is not the public transaction resource's standard/transfer/split enum. Signed amount_cents uses integer cents without absolute values or currency conversion. greater_than means >=, less_than means <=, and between includes both bounds, minimum first. Signed amounts express inflow/outflow constraints; there is no separate direction field. Consumers must handle legacy text fields and should tolerate future supported condition variants. oneOf: - type: object additionalProperties: false required: - field - operator - value properties: field: type: string enum: - merchant - description operator: type: string enum: - equals - contains value: type: string minLength: 1 - type: object additionalProperties: false required: - field - operator - value properties: field: type: string enum: - account_id operator: type: string enum: - equals value: type: string pattern: ^acct_[A-Za-z0-9]+$ - type: object additionalProperties: false required: - field - operator - value properties: field: type: string enum: - card_id operator: type: string enum: - equals value: type: string pattern: ^card_[A-Za-z0-9]+$ - type: object additionalProperties: false required: - field - operator - value properties: field: type: string enum: - transaction_type operator: type: string enum: - equals value: type: string enum: - transfer - type: object additionalProperties: false required: - field - operator - value properties: field: type: string enum: - amount_cents operator: type: string enum: - equals - greater_than - less_than value: type: integer - type: object additionalProperties: false required: - field - operator - value properties: field: type: string enum: - amount_cents operator: type: string enum: - between value: type: array minItems: 2 maxItems: 2 items: type: integer RuleActions: type: object additionalProperties: false minProperties: 1 description: >- Only configured actions are present; absent actions are omitted rather than null. category_id and department_id preserve the saved reference's public ID, including legacy references that may no longer be selectable for a new rule. Reading a rule performs no actions. Accounting-date offsets are relative to the original transaction date on import, and do not apply historically. Nonzero offsets cannot be combined with Asset category actions. properties: merchant: type: string minLength: 1 description: Assigned merchant name. category_id: type: string pattern: ^cat_[A-Za-z0-9]+$ description: Saved category reference; categories are created separately. department_id: type: string pattern: ^dept_[A-Za-z0-9]+$ description: Saved department reference. spread: type: integer minimum: 2 maximum: 36 description: Number of months over which to spread the transaction. accounting_date_offset_months: type: integer minimum: -24 maximum: 24 description: >- Months before (negative) or after (positive) the original transaction date on import; zero means the original date. RuleCondition: description: >- merchant matches the assigned merchant name; description matches the transaction description. account_id and card_id match exact stable identities, never display names. Legacy account and card_name are compatibility text fields; duplicate names and contains can match multiple sources. Their original stored text is preserved. transaction_type currently represents transfer only; it is not the public transaction resource's standard/transfer/split enum. Signed amount_cents uses integer cents without absolute values or currency conversion. greater_than means >=, less_than means <=, and between includes both bounds, minimum first. Signed amounts express inflow/outflow constraints; there is no separate direction field. Consumers must handle legacy text fields and should tolerate future supported condition variants. oneOf: - type: object additionalProperties: false required: - field - operator - value properties: field: type: string enum: - merchant - description - account - card_name operator: type: string enum: - equals - contains value: type: string minLength: 1 - type: object additionalProperties: false required: - field - operator - value properties: field: type: string enum: - account_id operator: type: string enum: - equals value: type: string pattern: ^acct_[A-Za-z0-9]+$ - type: object additionalProperties: false required: - field - operator - value properties: field: type: string enum: - card_id operator: type: string enum: - equals value: type: string pattern: ^card_[A-Za-z0-9]+$ - type: object additionalProperties: false required: - field - operator - value properties: field: type: string enum: - transaction_type operator: type: string enum: - equals value: type: string enum: - transfer - type: object additionalProperties: false required: - field - operator - value properties: field: type: string enum: - amount_cents operator: type: string enum: - equals - greater_than - less_than value: type: integer - type: object additionalProperties: false required: - field - operator - value properties: field: type: string enum: - amount_cents operator: type: string enum: - between value: type: array minItems: 2 maxItems: 2 items: type: integer securitySchemes: bearerAuth: type: http scheme: bearer description: API key prefixed with `finta_` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.