SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

OpenAPI Reference

Interactive auto-generated API reference covering every /api/v1 operation with schemas and Try It.

Generated API reference

The authoritative endpoint reference is auto-generated from the codebase and served from cache. It includes every /api/v1 operation, request/response schemas, and a Try It console.

Self-hosted installs serve the interactive reference at /docs/api and its OpenAPI JSON at /docs/api.json. Outside the local environment, sign in as an owner or a user with the Access API Console permission (api.access). Other signed-in users and guests receive 403. Signals Cloud tenants use the hosted documentation; these bundled routes return 404 on Cloud.

Use the guides in this section for authentication, conventions, webhooks, and metering. Use the generated reference for specific endpoints, parameters and response shapes.

Account responses group resource rates under rates, with per_day, per_hour, per_distance and flat as decimal strings. Create and update requests accept the same keys as non-negative integers in minor currency units; an update can supply only the rates being changed. is_location and is_bookable are booleans. The profile object contains typed fields for the account's Company, Venue, Contact or User profile; its field set follows account_type.

Catalogue items use offered_for: "rental"|"sale"|"both" and tracking: "bulk"|"serialised". Availability buffers sit under availability; revenue, costs and tax settings sit under commercial.rental, commercial.sale, commercial.sub_hire and commercial.purchase, together with their expanded references. See catalogue field groups for the nested fields and monetary units.

Rental responses expose string state and status identities. The rental labels lookup lists their display text. Request include=participants to load participants, or include=participants.account to include their accounts. Participants are managed at /api/v1/rentals/{rental}/participants. Action log entries, exports and temporal state are available under /api/v1/action_logs.

Rental phases

Rental reads include phases in rental sequence order. Each entry has key, label, starts_at and ends_at; endpoints can be null. Labels come from the current definition. The order is the rental's own order, independent of later changes to definition defaults.

Create (POST /api/v1/rentals) and update (PATCH /api/v1/rentals/{rental}) accept the same array:

{
  "phases": [
    {
      "key": "delivery",
      "starts_at": "2026-11-04T09:00:00+00:00",
      "ends_at": "2026-11-04T11:00:00+00:00"
    },
    {
      "key": "event",
      "starts_at": "2026-11-05T10:00:00+00:00",
      "ends_at": null
    }
  ]
}
Input Effect
Omit phases on create Create no phase rows.
Omit phases on update Preserve the collection.
"phases": [] Clear the collection.
Supply a non-empty array Atomically replace the entire collection in the supplied order; omitted entries are removed.

This is a replacement contract: omitting an endpoint within a supplied entry sets it to null. phases itself must be a list, not null. Each key must identify a definition and occur only once. An archived definition can remain on a rental already using it, but cannot be newly attached. label is read-only: omit it, or send the exact current definition label. A different label is rejected. Definition presentation and operational settings are edited through the definitions API.

Non-null endpoints require ISO 8601 timestamps including seconds and an explicit Z or numeric offset, such as +01:00. Offset-free timestamps are rejected. Responses normalize to UTC with millisecond precision. End must be at or after start; partial endpoints, equal-bound markers and overlapping phases are allowed. A failed replacement leaves the collection unchanged. Rental authorization, aggregate-version checks and idempotency apply to phase edits.

For a warehouse change across timezones, omitted phases follow the wall-clock-preserving rebase. A supplied phase array remains explicit instants. See rental timezone handling.

Flat rental fields

Rental reads, create requests and header updates use the same flat field names. Ownership is owner_id; use include=owner for the expanded user. Quote expiry is quote_expires_at.

Purpose Fields
Dates starts_at, ends_at, is_open_ended, ordered_at
Billing billing_period_starts_at, billing_period_ends_at, uses_billable_days, billable_days
Outbound transport customer_collects, delivery_address_id, delivery_instructions
Return transport customer_returns, collection_address_id, collection_instructions
Totals subtotal, tax_total, total, agreed_total
Totals by kind rental_total, sale_total, service_total, sub_hire_total, transit_total, loss_damage_total
Base amounts subtotal_base, tax_total_base

The rental dates describe the physical hire window. The billing period can differ from that window. uses_billable_days: false derives duration from dates; true uses a non-negative decimal billable_days. Choosing false clears the captured day count and rejects a non-null day count in the same request. is_open_ended indicates that no fixed return date is planned.

Creating a rental with uses_billable_days: true requires a non-null day count. An update may omit the day count to retain its value, but cannot combine true with a null day count. The generated request schemas express these conditions.

Service lines within a rental creation request require date_source, just as lines added separately do. Their allowed sources are hire_window, delivery, and collection.

customer_collects and customer_returns are booleans. Expanded addresses use include=delivery_address or include=collection_address. These expansions require accounts.contact-pii.view, addresses.view, the addresses:read token ability and access to the address record. Each address ID and instruction value can be null. Omitted update fields retain their values. Grouped request objects are rejected with validation messages naming the replacement fields.

For example, create a rental with a fixed billable duration:

{
  "title": "Conference equipment",
  "quote_expires_at": "2026-11-03T17:00:00Z",
  "starts_at": "2026-11-04T09:00:00Z",
  "ends_at": "2026-11-06T17:00:00Z",
  "is_open_ended": false,
  "billing_period_starts_at": "2026-11-04T09:00:00Z",
  "billing_period_ends_at": "2026-11-06T17:00:00Z",
  "uses_billable_days": true,
  "billable_days": "2.00",
  "customer_collects": false,
  "delivery_address_id": null,
  "delivery_instructions": "Use loading bay B",
  "customer_returns": true,
  "collection_address_id": null,
  "collection_instructions": null
}

Responses express totals as decimal strings in currency_code, or null when the captured currency precision cannot be established. subtotal is the amount before tax, tax_total is the tax component, and total includes tax. With tax-exclusive prices, the headline charge amount is subtotal; use total when displaying the tax-inclusive amount. agreed_total is the agreed amount, or null when none is set. The six totals by kind use the flat fields listed above.

Version responses expose the same flat totals. An agreed amount or per-kind breakdown that was not recorded on the version is null. Pricing previews use these flat fields in both totals_before and totals_after. Rental line items expose their surcharge amount as adjustments, a decimal string.

Pricing preview line_changes expose adjustments_before and adjustments_after as nullable integer amounts in minor currency units.

Set or clear a rental's agreed price with POST or DELETE /api/v1/rentals/{rental}/agreed_price. The set request accepts agreed_total and an optional agreed_price_mode (flat_headline or proportional). For a section, use PUT or DELETE /api/v1/rentals/{rental}/sections/{section}/agreed_price; the set request accepts agreed_price. Both use the rentals.edit permission and rentals:write token ability.

Create requests can seed subtotal: an integer represents minor currency units, while a decimal string represents major units. Other totals are calculated, and header updates cannot write totals. Pricing commands recalculate them from lines and their accepted terms.

Filters and sorts use the same flat names, for example filter[starts_at][gte]=2026-11-01T00:00:00Z, filter[uses_billable_days]=true, filter[customer_collects]=true and sort=-starts_at. State and status filters use string identities. Unsupported fields and values return validation errors.

Rental labels lookup

State identities and their display labels are:

state Label
enquiry Enquiry
quote Quote
order Order

Built-in status identities and their display labels are:

status Label
enquiry_unconfirmed Unconfirmed
quote_pencilled Pencilled
quote_held Held
quote_lost Lost
quote_expired Expired
quote_postponed Postponed
order_active Active
order_dispatched Dispatched
order_on_hire On Hire
order_returned Returned
order_checked Checked
order_complete Complete
order_cancelled Cancelled

Rental resources contain the identities without duplicate label fields. GET /api/v1/rental_statuses supplies the current status catalogue: use each row's value as the identity and name as its current label, including tenant-defined statuses. Custom identities remain stable when their labels change. Display labels never replace identities in requests or filters.

Phase definitions

All operations require the user's settings.manage permission. Reads additionally require token ability phase-definitions:read; create, update, preview, archive and restore require phase-definitions:write. Detail paths bind the permanent key, such as delivery.

Method and path Purpose
GET /api/v1/phase_definitions List definitions, including hidden and archived entries.
GET /api/v1/phase_definitions/{key} Read one definition.
POST /api/v1/phase_definitions Create a definition.
PATCH /api/v1/phase_definitions/{key} Update supplied fields, preserving omitted values.
POST /api/v1/phase_definitions/{key}/impact Preview a proposal without writing changes.
POST /api/v1/phase_definitions/{key}/archive Prevent new selection while retaining attached schedules.
POST /api/v1/phase_definitions/{key}/restore Allow new selection again.

Definition responses contain id, ref, key, label, colour, is_visible, blocks_availability, operational_role, default_sequence and nullable archived_at, wrapped in data. Lists also return pagination meta and default to default_sequence, then key. Use filter[field][operator], for example filter[archived][eq]=false or filter[is_visible][eq]=true. Supported sorts are key, label, default_sequence and archived_at, with - for descending. Sorting by archived_at requires offset pagination; combining it with cursor pagination returns 422. Saved-filter IDs are not supported on this list.

Create requires key, label and six-digit hexadecimal colour. Keys start with a lowercase letter and contain lowercase letters, digits or underscores, up to 64 characters. Optional defaults are is_visible=true, blocks_availability=false, operational_role=null and default_sequence=10. A role is outbound_loading, delivery, event, collection or null, unique across definitions. PATCH accepts the same settings except key; keys cannot change. Use archive/restore actions rather than writing archived_at. No definition delete operation is provided.

Preview then apply

For a blocking or operational-role change on a definition already used by rentals:

  1. Send the proposed partial settings to POST /api/v1/phase_definitions/delivery/impact, for example {"blocks_availability": true}. Omitted settings retain their current values.
  2. Review data.rentals (affected rental schedules) and data.assignments (assignments retaining booked dates). Copy data.token.
  3. PATCH the definition with the same proposal plus impact_token:
{
  "blocks_availability": true,
  "impact_token": "<data.token from the impact response>"
}

The token binds the proposal to current definition and rental-schedule evidence, including affected rentals across warehouses. Missing, incorrect or stale evidence returns HTTP 422 with errors.impact. Preview again after a refusal or changed proposal. Applying the change rebuilds affected equipment demand in the same transaction; a failure rolls everything back. Booked assignment dates remain fixed. Presentation-only edits and operational edits on unused definitions can be applied directly. The Rental phases settings guide describes the equivalent web flow.

See Approvals Inbox for inbox filters, expansions and request-changes, and Batch Approvals for bulk refusal codes.

See Privacy cases for account case opening, identity verification, approval, queued execution and retry.

Action request contracts

Resource assignment creation requires exactly one non-null parent: rental_id or rental_project_id. Top-level report schedule creation requires exactly one non-null subject: report_id or board_key. Both contracts allow the unused alternative to be omitted or null; supplying both selections or neither returns 422.

Asset assignment updates use PATCH /api/v1/rentals/{rental}/asset_assignments/{assignment} with an action discriminator. set_flightcase requires flightcase_asset_id; substitute requires new_asset_id; check requires condition (good, damaged, or missing); change_status requires revert_to. The other actions are prepare, revert, clear_flightcase, dispatch, on_hire, and return. Each action accepts its documented fields only. Lifecycle, permissions and warehouse checks apply at execution.

Fulfilment batches use POST /api/v1/rentals/{rental}/fulfilment_batches with stage: allocate|prepare|dispatch|return. Fields from another stage and unexpected fields are rejected. Assignment identifiers must be unique within the batch; allocation entries must select distinct assets. prepared_at, dispatched_at and returned_at require an ISO 8601 timestamp with seconds and a UTC Z or explicit offset. Fractional seconds may contain up to six digits.

Attachment uploads use multipart/form-data with a binary file, attachable_type, and attachable_id. Import uploads also use multipart; a non-null import_plan_id requires a nonempty plan_step_name. The step must exist on that plan, match the upload target and have no active batch.

Workflow resume requests require a 64-character alphanumeric token, status: approved|rejected|expired, and a result value matching the suspended step's contract. An unknown token returns 404; an unavailable token returns 410. Inaccessible availability warehouses return 404. Editing another user's personal availability or rental diary view returns 403.

Organisation view defaults

Read or update the default dashboard layout through /api/v1/settings/dashboard (default_view: briefing, command, board). The /api/v1/settings/scheduling group exposes calendar_default_view (planner, day-first) and activities_default_view (inbox, my-day). These defaults apply until a person saves a personal view choice.

Settings reads require settings.view and settings:read or the matching settings:read:{group} ability. Partial PUT/PATCH writes require settings.manage and settings:write and record changed values in the audit trail. MCP clients can use the same settings operations through execute-endpoint. See the settings registry contract for request examples, defaults and validation.

Document sequences

Read GET /api/v1/document_sequences?filter[warehouse_id][eq]=2&filter[document_type][eq]=invoice with document_templates.view and documents:read. The list is warehouse-scoped, supports offset or cursor pagination, and includes next_number_preview for each sequence.

Update the selected sequence with document_templates.edit and documents:write:

PUT /api/v1/document_sequences/14
Content-Type: application/json

{"prefix":"BILL-","suffix":"","next_number":1001,"padding":5,"include_year":false,"include_month":false,"reset_frequency":"never"}

The resource is abbreviated:

{"data":{"id":14,"warehouse_id":2,"document_type":"invoice","prefix":"BILL-","suffix":"","next_number":1001,"padding":5,"include_year":false,"include_month":false,"reset_frequency":"never","next_number_preview":"BILL-01001"}}

Omitted fields remain unchanged. padding is 1–12, next_number must be positive and fit that width, and prefix/suffix are at most 50 characters. reset_frequency is never, yearly or monthly; yearly requires the year in the format, and monthly requires both year and month. Existing-number collision guards still apply. Changing a sequence affects future numbering, not already issued documents. See Numbering.

Integration contracts

The export includes timestamp and tombstone filters on stored-record lists, cursor inputs and metadata on paginated lists, reusable X-Signals-Units-*/Retry-After headers and the TooManyRequests response. Its top-level OpenAPI 3.1 webhooks section describes each registered event's delivery envelope and signing headers.