Declare a recurring series Candor has not detected.

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.

post/v1/recurring

Request

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

Headers

Idempotency-Keystring required

Stable opaque identity for one logical POST. Reuse only with the same method, path, actor, and body for transport retries. A completed receipt replays its original result, including a refusal; changed input with the same key is rejected. After a refused action and access recovery, use a new key for the new attempt. Follow retryable and recovery guidance if the operation is still running or its outcome is unknown.

Request body

labelstring required

Who the payment is to or from, in the user's words.

account_identity_idstring 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_minstring

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_maxstring

Inclusive maximum payment as Money text. Supply with amount_min in the series currency. Supplying amount alone resets matching to that exact amount.

amountstring required

Money text for the expected amount, such as "USD 1500.00".

next_expected_datestring date required

The next date a financial posting in the series is expected. Later projected postings advance from it.

categorystring
cashflow_role'income' | 'expense' | 'transfer' | 'debt_payment' | 'refund'

Defaults to expense for an outflow and income for an inflow.

ends_atstring date

The date a finite series ends, for payment plans and similar.

date_tolerance_daysinteger

Half-width of the expected window when the biller's habit is known.

approval_notestring

Why the series reads this way. Defaults to the action reason.

approval_sourcestring
set_bystring

Response

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

schema_versionstring required
generated_atstring date-time required
request_idstring required
status'success' | 'partial_success' | 'action_required' | 'error' required
user_messagestring

Optional concise user-safe message the calling agent may adapt.

warningsobject[] required
dataobject nullable required

Operation-specific result data, or null when the request ends in an error.

Changes

No recorded changes to this operation across all 1 revision of this API.