POST
Link a registered mandate to its goal. Callback-service auth (consumer-rung). Idempotent on the same mandate; a different mandate on a linked goal is a 409.

Path Parameters

goal_id
string
required

Goal UUID

Body

application/json
mandate_id
string
required

Response

Mandate linked (or already linked)

account_id
string
required
contribution_ratio
object
required
created_at
string
required
currency
enum<string>
required

ISO 4217 three-letter currency codes.

Currently INR only; add variants as the product expands.

Available options:
INR
id
string
required
last_modified_at
string
required
others_accumulated
object
required

Represents a monetary amount with its associated currency

periodicity
string
required
purpose
object
required

What a goal is for. The DB stores this as a single purpose VARCHAR(64) column URN-encoded as <kind>:<payload>:

  • category:<GoalCategory> — a closed category (e.g. category:healthcare).
  • specific:<benefit_entity_id> — one benefit instance; the payload is the benefit_entities.entity_id (validated at create, no DB FK — like Source).

Every kind carries a payload, so a bare kind is always a parse error.

Every entry point (JSON Deserialize, diesel FromSql, FromStr) re-validates so corrupt rows fail loudly.

self_accumulated
object
required

Represents a monetary amount with its associated currency

self_spent
object
required

Represents a monetary amount with its associated currency

sponsor_accumulated
object
required

Represents a monetary amount with its associated currency

sponsor_spent
object
required

Represents a monetary amount with its associated currency

status
enum<string>
required

Goal lifecycle — terminal-vs-live only. ACTIVE from creation; CLOSED = ended at its natural end (term elapsed, e.g. policy expiry); CANCELLED = never went live (e.g. the funding policy was rejected). Whether a goal is running right now is answered by its term (start_time..end_time), not by this status — a goal is ACTIVE even when its term starts in the future. Target-met and spend outcomes are computed, not stored on status.

Available options:
ACTIVE,
CLOSED,
CANCELLED
target_amount
object
required

Represents a monetary amount with its associated currency

target_met
boolean
required
user_id
string
required

A validated 12-digit numeric user identifier.

Every external entry point validates:

  • JSON Deserialize runs [UserId::parse] (outer whitespace trimmed, length and digit-only enforced) via #[serde(try_from = "String")].
  • DB FromSql runs [UserId::parse] on every row read.

Display / Deref<Target = str> / AsRef<str> / Into<String> are derived via derive_more — the inner String is pass-through for every read-only borrow, display, and move-out.

Example:

"012345678901"

end_date
string | null
Example:

"2027-01-15"

mandate_id
string | null
start_date
string | null
Example:

"2026-01-15"