List policy invoices

get

https://sandbox.uk.rootplatform.com/v1/insurance/policies/{policy_id}/invoices

Retrieve the invoices raised against a policy, newest first. The total number of matching invoices is returned in the X-Total-Count response header.

Invoicing is opt-in per organization: unless the invoicing feature flag is enabled for your organization this endpoint returns 403.

Path Params

policy_id

string

required

Must be a UUID. The unique identifier of the policy.

Query Params

status

array of objects

Narrow the list to the given invoice statuses, e.g. ?status=open to list the invoices on a policy that are finalised but not yet paid, or ?status=open,paid for several. By default invoices across all statuses are returned.

status

Allowed:

string

length ≤ 200

Case-insensitive contains-match on the invoice reference. Maximum 200 characters.

total

integer

Exact match on the invoice total, given as the amount the recipient sees (a positive figure for a charge) in the currency's minor units.

from

date

Only return invoices dated on or after this ISO 8601 date (UTC). Invoices are matched on invoice_date. An invoice without one is matched on the day it was created, which for an invoice raised before invoice_date existed can differ from the date printed on its document. Must not be after to.

date

Only return invoices dated on or before this ISO 8601 date.

line_item_search

string

length between 3 and 200

Free-text search across the descriptions of the invoice's line items, which is where a job reference appears. Returns every invoice with at least one matching line. Minimum 3 characters, maximum 200; a shorter term is rejected with a 400, since it would match most of a policy's ledger. Leading and trailing whitespace is trimmed before the term is measured, and an empty term is ignored rather than rejected.

payment_id

uuid

Only return the invoice this payment is linked to. A payment funds at most one invoice, so the response holds at most one invoice, and is empty when the payment is not linked to any invoice on this policy. Combines with the other filters, so ?payment_id=...&status=open returns the linked invoice only while it is still open. Must be a UUID; an empty value is ignored. An invoice can carry several payment links (a failed payment and its retry, say), and linked_payment on the response is the most recent one, so it may name a different payment from the one filtered on.

page_size

integer

1 to 100

Defaults to 30

The maximum number of items that will be contained in a single page, between 1 and 100 (inclusive).

page

integer

≥ 1

Defaults to 1

The page number of the entities to fetch. Must be a minimum of 1.

Responses

400

Validation error. Examples: from is after to, line_item_search is shorter than 3 characters, or page exceeds 200.

403

Invoicing is not enabled for the organization, or the caller is missing the invoices:read permission.

Language

Credentials

Basic

base64

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Success