Request Structure — Proposed Guide

Planned API — Reference Only

Request Structure: A proposed expense creation request would combine an authorized organization context, a JSON representation and an operation…

Overview

A proposed expense creation request would combine an authorized organization context, a JSON representation and an operation identifier. The amount should be expressed in explicit minor units so currency handling is unambiguous.

Key concepts

Keep bearer authorization in a header, content type separate from the body, and an idempotency key separate from the expense identifier. Use a date field for the incurred business date.

Implementation considerations

Validation should distinguish malformed JSON from an invalid field and a forbidden organization. Never include secrets in query parameters or copy them into request logs.

Proposed API behavior

POST /v1/expenses is an illustrative design for this topic. Path and field names may change before implementation. Access would require an authorized organization context and operation-specific permission; no public API or authorization grant is available here.

Illustrative request fields
Name	Type	Description
organization_id	string	Stable fictional organization reference; not a secret and not evidence that a resource exists.
user_id	string	Stable fictional user reference; not a secret and not evidence that a resource exists.
amount_minor	integer	Monetary amount in the documented currency minor unit; 12550 represents USD 125.50, not USD 12,550.
currency	string	Uppercase ISO 4217 currency code. Determine its minor-unit exponent before monetary conversion.
incurred_on	string (date)	Synthetic calendar date in YYYY-MM-DD form; period inclusivity must be defined by the future contract.

Static example requests

Proposed, non-executing request examples

# Proposed request text only; this reserved host is not a live API.
curl -X POST 'https://api.remizen.example/v1/expenses' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: operation_example_123' \
  --data '{
  "organization_id": "org_example_123",
  "user_id": "usr_example_123",
  "amount_minor": 12550,
  "currency": "USD",
  "incurred_on": "2026-01-15"
}'

Fictional response example

201 (proposed example)Static response fixture

Fictional documentation data only. No request was sent, record created, review performed, payment initiated or provider connection activated.

JSON

{
  "data": {
    "organization_id": "org_example_123",
    "amount_minor": 12550,
    "currency": "USD",
    "incurred_on": "2026-01-15",
    "id": "exp_example_123",
    "merchant": "Example Office Supply",
    "status": "draft"
  },
  "meta": {
    "request_id": "req_example_123",
    "reference_only": true
  }
}

Illustrative error case

Review this failure case in context: Validation should distinguish malformed JSON from an invalid field and a forbidden organization. Never include secrets in query parameters or copy them into request logs.

422 (illustrative; final error contracts are undecided)Proposed error fixture

Synthetic diagnostic example. Human-readable messages must not be used as stable programmatic contracts.

JSON

{
  "error": {
    "code": "validation_error",
    "message": "The proposed request structure operation requires review of its input or authorization.",
    "request_id": "req_example_123"
  }
}

Proposed data types

Illustrative field dictionary
Name	Type	Description
organization_id	string	Stable fictional organization reference; not a secret and not evidence that a resource exists.
user_id	string	Stable fictional user reference; not a secret and not evidence that a resource exists.
amount_minor	integer	Monetary amount in the documented currency minor unit; 12550 represents USD 125.50, not USD 12,550.
currency	string	Uppercase ISO 4217 currency code. Determine its minor-unit exponent before monetary conversion.
incurred_on	string (date)	Synthetic calendar date in YYYY-MM-DD form; period inclusivity must be defined by the future contract.
idempotency_key	string	Non-secret proposed operation key for controlled replay; supplied as an illustrative header.

API Versioning

Getting Started

Response Structure