Requests & Responses

This section details the data formats, conventions, and error-handling protocols used by the Billogram API.

Data Types & Conventions

The API uses JSON as the primary data exchange format.

Headers

• For requests with a JSON body: Content-Type: application/json.
• For all requests: Accept: application/json.

Common Data Types

• String: Must be quoted JSON strings.
• Number: Standard JSON numbers used for currency amounts, fees, and interest rates.
• Numeric String: Quoted strings for identifiers that are not mathematical, such as organization numbers, OCR numbers, or postal codes.
• Timestamp: Returned as strings in UTC format. You may encounter:
  • YYYY-MM-DD hh:mm:ss (e.g., in event history).
  • YYYY-MM-DDThh:mm:ss.fraction+00:00 (ISO 8601/RFC 3339).
• Date: Standard ISO 8601 format: YYYY-MM-DD.

Field Naming & Path Notation

While JSON keys are standard, the API uses a path notation (colon-separated) when referencing fields in filters or error messages:

• Nested Objects: contact:email represents the email field within a contact object.
• Arrays: items[0]:price indicates the price of the first item in an array.

Default Values

• Required: These fields must be explicitly provided during resource creation.
• Blank/Null: If a sub-structure is set to null or omitted in an update, it remains unchanged.
• Read-Only: Populated automatically by the API (e.g., id, state, created_at). Providing these in a request may result in a READ_ONLY_PARAMETER error.
• Account Defaults: Many fields (like due_days or interest_rate) use your Billogram account settings if omitted.

Response Envelopes

Successful Responses (2xx)

Successful operations return a consistent JSON envelope:

• status: A string indicator (typically "OK").
• data: The requested resource object or an array of objects.

Error Responses (4xx/5xx)

When an error occurs, the API returns a structured error body:

• status: A machine-readable identifier for programmatic handling (e.g., INVALID_PARAMETER).
• data.message: A human-readable explanation for debugging.
• data.field / data.field_path: Optional fields identifying exactly which parameter caused the error.

Pagination, Filtering & Sorting

Listing resources (e.g., GET /billogram or GET /customer) utilizes a standardized set of query parameters.

Pagination

Results are paged to maintain performance.

• page: Result page number (integer, starts at 1).
• page_size: Results per page (default 25, max 100).

Filtering

To filter results, you must provide the following three parameters:

1. filter_type: How to match. Supported types include field (exact), field-prefix (starts with), field-search (substring), or special (endpoint-specific).
2. filter_field: The specific field to filter on (e.g., state or item_no).
3. filter_value: The value you are searching for.

Example:

GET /billogram?page=1&page_size=100&filter_type=field&filter_field=state&filter_value=Unpaid

Sorting

Sorting is controlled by two parameters that must be provided together:

• order_field: The field to sort by (e.g., created_at).
• order_direction: Either asc (ascending) or desc (descending).

Status Codes & Troubleshooting

Best Practices for Error Handling

1. Programmatic Logic: Use the status field (e.g., INVALID_OBJECT_STATE) to drive application logic.
2. Exponential Backoff: For 5xx errors, retry the request with increasing delays and jitter.
3. Log Context: Always log the status, message, and field_path to drastically reduce troubleshooting time.

Example Error Body:

{
    "status": "INVALID_PARAMETER",
    "data": {
        "message": "The due_date must be later than the invoice_date."
    }
}