goalsRecord a goal contribution

Record a goal contribution

Records a manual contribution toward a goal. Requires the goals:write scope, writes_enabled, and an Idempotency-Key (a double-fired contribution would otherwise post twice). currency_code defaults to the goal's currency. A goal linked exclusively to excluded accounts returns 404, byte-identical to a nonexistent goal.

curl -X POST "https://api.403fin.io/v1/goals/123e4567-e89b-12d3-a456-426614174000/contributions" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: example_string" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
  "amount": "example_string",
  "currency_code": "example_string",
  "note": "example_string",
  "period_start": "2024-12-25"
}'
{
  "data": {
    "contribution": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "goal_id": "123e4567-e89b-12d3-a456-426614174000",
      "budget_item_id": "123e4567-e89b-12d3-a456-426614174000",
      "amount": "example_string",
      "currency": "example_string",
      "period_start": "2024-12-25",
      "source": "example_string",
      "note": "example_string",
      "detected_at": "2024-12-25T10:00:00Z"
    },
    "progress": {
      "goal_id": "123e4567-e89b-12d3-a456-426614174000",
      "current_amount": "example_string",
      "target_amount": "example_string",
      "remaining_amount": "example_string",
      "progress_pct": "example_string",
      "days_remaining": 42,
      "projected_completion_date": "2024-12-25",
      "monthly_contribution_needed": "example_string",
      "last_contribution_at": "2024-12-25T10:00:00Z",
      "monthly_shortfall": "example_string"
    }
  },
  "pagination": {
    "next_cursor": "example_string",
    "has_more": true
  },
  "redacted_fields": [
    "example_string"
  ],
  "filtered": true
}
POST
/v1/goals/{id}/contributions
POST
Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token
Bearer Tokenstring
Required

An opaque ff_ credential (ff_ak_ / ff_at_) presented as a Bearer token.

An opaque ff_ credential (ff_ak_ / ff_at_) presented as a Bearer token.
API Key (header: X-API-Key)
X-API-Keystring
Required

An opaque ff_ credential presented in the X-API-Key header.

An opaque ff_ credential presented in the X-API-Key header.
path
idstring
Required

The resource UUID.

Format: uuid
Content-Typestring
Required

The media type of the request body

Options: application/json
header
Idempotency-Keystring
Required

A caller-chosen unique key (1-128 chars) that makes the write idempotent. A retry with the SAME key against the SAME operation, resource, and body replays the original response (Idempotency-Replayed: true). The same key with anything different — a changed body, a different endpoint, or a different {id} — is a 409 conflict; a still-in-flight duplicate is 409 with Retry-After. Required on every write. Stored for 24 hours. The key is bound to the target, not only to the payload, so reusing one key across two deletes (which carry no body at all) conflicts rather than replaying the first delete's response.

Min length: 1 • Max length: 128
amountstring
Required

A positive decimal amount string.

currency_codestring

ISO 4217 code. Defaults to the goal's currency when omitted.

period_startstring

The budget period (YYYY-MM-DD, first of month). Defaults to the current month.

Format: date
Request Preview
Response

Response will appear here after sending the request

Authentication

header
Authorizationstring
Required

Bearer token. An opaque ff_ credential (ff_ak_ / ff_at_) presented as a Bearer token.

header
X-API-Keystring
Required

API Key for authentication. An opaque ff_ credential presented in the X-API-Key header.

Path Parameters

idstring
Required

The resource UUID.

Headers

Idempotency-Keystring
Required

A caller-chosen unique key (1-128 chars) that makes the write idempotent. A retry with the SAME key against the SAME operation, resource, and body replays the original response (Idempotency-Replayed: true). The same key with anything different — a changed body, a different endpoint, or a different {id} — is a 409 conflict; a still-in-flight duplicate is 409 with Retry-After. Required on every write. Stored for 24 hours.

The key is bound to the target, not only to the payload, so reusing one key across two deletes (which carry no body at all) conflicts rather than replaying the first delete's response.

Body

application/json
amountstring
Required

A positive decimal amount string.

currency_codestring

ISO 4217 code. Defaults to the goal's currency when omitted.

period_startstring

The budget period (YYYY-MM-DD, first of month). Defaults to the current month.

Responses

dataobject
Required

The result of recording a goal contribution.

paginationstring

Cursor pagination state, present on list endpoints.

redacted_fieldsstring[]

Field ids stripped from the payload by connection scope.

filteredboolean

True when row or aggregate filtering is in effect for this response.