---
title: "Declare a recurring series Candor has not detected."
method: POST
path: "/v1/recurring"
---

# Declare a recurring series Candor has not detected.

`POST /v1/recurring`

## Request

- Base URL: `https://api.candor.money`
- URL: `https://api.candor.money/v1/recurring`
- Auth: HTTP bearer

Declare a recurring series Candor has not detected, such as a named bill, an annual renewal with one posting, or a payment plan with an end date.

## Headers

- `Idempotency-Key` string, required

## Request body

- RecurringCreateRequest: Record an expected recurring financial series Candor has not detected. The next expected posting date anchors later projections. This records financial expectations; it does not execute payments or schedule agent runs.
  - `label` string, required: Who the payment is to or from, in the user's words.
  - `account_identity_id` string, required: The account the series posts to.
  - `direction` 'outflow' | 'inflow', required: outflow for a bill or subscription, inflow for pay or an expected deposit.
  - `cadence` 'weekly' | 'biweekly' | 'semimonthly' | 'monthly' | 'quarterly' | 'semiannual' | 'annual', required: How often the series posts: weekly, biweekly, semimonthly, monthly, quarterly, semiannual, or annual.
  - `amount_min` string: Inclusive minimum payment as Money text. Supply with amount_max for a variable bill; the range must contain amount. No percentage tolerance is inferred.
  - `amount_max` string: Inclusive maximum payment as Money text. Supply with amount_min in the series currency. Supplying amount alone resets matching to that exact amount.
  - `amount` string, required: Money text for the expected amount, such as "USD 1500.00".
  - `next_expected_date` string, date, required: The next date a financial posting in the series is expected. Later projected postings advance from it.
  - `category` string
  - `cashflow_role` 'income' | 'expense' | 'transfer' | 'debt_payment' | 'refund': Defaults to expense for an outflow and income for an inflow.
  - `ends_at` string, date: The date a finite series ends, for payment plans and similar.
  - `date_tolerance_days` integer: Half-width of the expected window when the biller's habit is known.
  - `approval_note` string: Why the series reads this way. Defaults to the action reason.
  - `approval_source` string
  - `set_by` string

## Response `200`

Envelope with the declared series as it reads, any likely duplicates already on the account, and next actions.

- ResponseEnvelope
  - `schema_version` string, required
  - `generated_at` string, date-time, required
  - `request_id` string, required
  - `status` 'success' | 'partial_success' | 'action_required' | 'error', required
  - `user_message` string: Optional concise user-safe message the calling agent may adapt.
  - `data_freshness` DataFreshness
    - `balances_last_synced_at` string
    - `coverage` 'complete' | 'partial' | 'stale' | 'unavailable', required
    - `holdings_last_synced_at` string
    - `transactions_last_synced_at` string
  - `metadata` object: Response-level protocol metadata such as package compatibility and workspace opening identity or timing. It is not financial workspace data and must not be treated as attention.
    - `view_url` string, uri: Authenticated dashboard destination related to this response. May open a section rather than reproduce the returned records or filters. Per-record view_url values identify exact supported record views. Use returned URLs instead of constructing paths.
  - `warnings` object[], required
  - `errors` AgentError[], required
    - `code` string, required
    - `expires_at` string
    - `idempotency_key` string: Stable key to reuse when retrying this identical logical operation.
    - `message` string, required
    - `recovery_url` string, uri
    - `required_capability` string
    - `retry_after_seconds` integer: Machine-actionable delay before retrying the identical logical operation.
    - `retryable` boolean, required
    - `suggested_command` string
  - `next_actions` AgentAction[], required
    - `intent` string, required
    - `command` string, required
    - `args` object, required
    - `shell` string, required
  - `action` WorkspaceAction
    - `id` string, required
    - `operation` string, required
    - `reason` string, required
    - `root_action_id` string, required
    - `parent_action_id` string
    - `task_key` string
    - `status` 'started' | 'succeeded' | 'refused' | 'failed', required
    - `created_at` string, date-time, required
    - `completed_at` string, date-time
  - `data` object, nullable, required: Operation-specific result data, or null when the request ends in an error.

## Other responses

- `default`: Structured Candor error envelope with machine-readable codes, recovery guidance, and retry timing when applicable.

---

[API](https://skmtc.dev/candor/apis/candor-api.md) · [All operations](https://skmtc.dev/candor/apis/candor-api/llms.txt) · [OpenAPI document](https://skmtc.dev/candor/apis/candor-api/revisions/6c050f72e956?raw)