> ## Documentation Index > Fetch the complete documentation index at: https://docs.zivio.com/llms.txt > Use this file to discover all available pages before exploring further. # List Invoices > Retrieve a paginated list of invoices. Use filters to narrow results. ## Filtering Use the `filter[]` parameter to filter results. Multiple filters are combined with AND logic. ### Basic Examples ``` # Equality (implicit) GET /api/v4/invoices?filter[status]=draft # Multiple values (implicit IN) GET /api/v4/invoices?filter[status]=draft,paid # With explicit operator GET /api/v4/invoices?filter[created_at][gte]=2024-01-01 # Range query GET /api/v4/invoices?filter[total][between]=1000000,5000000 # Multiple filters (AND) GET /api/v4/invoices?filter[status]=draft&filter[total][gte]=1000000 ``` ### Available Attributes | Attribute | Type | Operators | Permitted Values | |-----------|------|-----------|------------------| | approved_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | approved_by_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | cis_amount_due | money | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | cis_contractor | boolean | `eq`, `not_eq` | - | | cis_deductible | money | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | cis_deduction_total | money | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | cis_rate_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | cis_subcontractor | boolean | `eq`, `not_eq` | - | | client_due_on | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | client_payment_terms_in_days | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | created_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | credit_note_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | credit_note_reason | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | dated_on | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | description | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | due_on | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | external_id | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | external_provider | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | is_credit_note | boolean | `eq`, `not_eq` | - | | level_1_approved_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | level_1_approved_by_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | line_item_sheet_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | manual_client_tax_type_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | milestone_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | net_total | money | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | paid_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | payment_terms_in_days | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | project_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | reference_number | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | rejected_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | rejected_by_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | rejected_reason | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | self_bill | boolean | `eq`, `not_eq` | - | | sent_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | status | string | `eq`, `not_eq`, `in`, `not_in` | `draft`, `unpaid`, `paid`, `level_1_approved`, `approved`, `rejected` | | subtype | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | tax_total | money | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | total | money | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | type | string | `eq` | `invoice`, `credit_note`, `all` | | updated_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | vatable | boolean | `eq`, `not_eq` | - | ### Custom Fields This resource supports custom field filtering using `cf[key]` syntax: ``` # Equality GET /api/v4/invoices?cf[priority]=high # With operator GET /api/v4/invoices?cf[department][in]=engineering,design # Check existence GET /api/v4/invoices?cf[priority][exists]= # Negation GET /api/v4/invoices?cf[priority][not_eq]=low ``` ### OR Conditions Use `or[group]` to combine filter groups with OR logic. Filters within a group are ANDed: ``` # Simple OR GET /api/v4/invoices?or[1][status]=unpaid&or[2][status]=draft # Complex OR (status=unpaid AND total>=1000000) OR (status=draft) GET /api/v4/invoices?or[1][status]=unpaid&or[1][total][gte]=1000000&or[2][status]=draft ``` ## Sorting Use `sort[]` to order results. Default direction is ascending. ``` # Ascending (implicit) GET /api/v4/invoices?sort[created_at]= # Descending GET /api/v4/invoices?sort[created_at]=desc # Combined with filters GET /api/v4/invoices?filter[status]=draft&sort[created_at]=desc ``` ## OpenAPI ````yaml /api-reference/v4/openapi.json get /invoices openapi: 3.1.0 info: title: API V4 version: '4' description: >- OAuth 2.0 secured API. Obtain an access token using client credentials to access protected endpoints. The regional endpoints listed below serve every Zivio organisation, so each request — including the token request — must carry a `zivio-tenant-id` header identifying yours. Requests without it are rejected with a 404 before any token is checked. contact: name: API Support email: support@zivio.com servers: - url: https://api.zivio.net/api/v4 description: Global API Router - url: https://api.eu.zivio.net/api/v4 description: EU Data Region - url: https://api.uk.zivio.net/api/v4 description: UK Data Region - url: https://api.us.zivio.net/api/v4 description: US Data Region security: - oauth2: [] tenantId: [] paths: /invoices: get: tags: - Invoices summary: List Invoices description: >- Retrieve a paginated list of invoices. Use filters to narrow results. ## Filtering Use the `filter[]` parameter to filter results. Multiple filters are combined with AND logic. ### Basic Examples ``` # Equality (implicit) GET /api/v4/invoices?filter[status]=draft # Multiple values (implicit IN) GET /api/v4/invoices?filter[status]=draft,paid # With explicit operator GET /api/v4/invoices?filter[created_at][gte]=2024-01-01 # Range query GET /api/v4/invoices?filter[total][between]=1000000,5000000 # Multiple filters (AND) GET /api/v4/invoices?filter[status]=draft&filter[total][gte]=1000000 ``` ### Available Attributes | Attribute | Type | Operators | Permitted Values | |-----------|------|-----------|------------------| | approved_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | approved_by_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | cis_amount_due | money | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | cis_contractor | boolean | `eq`, `not_eq` | - | | cis_deductible | money | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | cis_deduction_total | money | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | cis_rate_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | cis_subcontractor | boolean | `eq`, `not_eq` | - | | client_due_on | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | client_payment_terms_in_days | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | created_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | credit_note_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | credit_note_reason | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | dated_on | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | description | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | due_on | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | external_id | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | external_provider | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | is_credit_note | boolean | `eq`, `not_eq` | - | | level_1_approved_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | level_1_approved_by_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | line_item_sheet_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | manual_client_tax_type_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | milestone_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | net_total | money | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | paid_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | payment_terms_in_days | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | project_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | reference_number | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | rejected_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | rejected_by_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | rejected_reason | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | self_bill | boolean | `eq`, `not_eq` | - | | sent_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | status | string | `eq`, `not_eq`, `in`, `not_in` | `draft`, `unpaid`, `paid`, `level_1_approved`, `approved`, `rejected` | | subtype | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | tax_total | money | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | total | money | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | type | string | `eq` | `invoice`, `credit_note`, `all` | | updated_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | vatable | boolean | `eq`, `not_eq` | - | ### Custom Fields This resource supports custom field filtering using `cf[key]` syntax: ``` # Equality GET /api/v4/invoices?cf[priority]=high # With operator GET /api/v4/invoices?cf[department][in]=engineering,design # Check existence GET /api/v4/invoices?cf[priority][exists]= # Negation GET /api/v4/invoices?cf[priority][not_eq]=low ``` ### OR Conditions Use `or[group]` to combine filter groups with OR logic. Filters within a group are ANDed: ``` # Simple OR GET /api/v4/invoices?or[1][status]=unpaid&or[2][status]=draft # Complex OR (status=unpaid AND total>=1000000) OR (status=draft) GET /api/v4/invoices?or[1][status]=unpaid&or[1][total][gte]=1000000&or[2][status]=draft ``` ## Sorting Use `sort[]` to order results. Default direction is ascending. ``` # Ascending (implicit) GET /api/v4/invoices?sort[created_at]= # Descending GET /api/v4/invoices?sort[created_at]=desc # Combined with filters GET /api/v4/invoices?filter[status]=draft&sort[created_at]=desc ``` operationId: getInvoices parameters: - name: page in: query schema: type: integer default: 1 description: Page number for pagination - name: limit in: query schema: type: integer default: 20 maximum: 100 description: Number of results per page (max 100) - name: filter[] in: query style: deepObject explode: true schema: type: object description: >- Filterable attributes: **integer** (operators: eq, not_eq, in, not_in, gt, gte, lt, lte, between): approved_by_id, cis_rate_id, client_payment_terms_in_days, credit_note_id, id, level_1_approved_by_id, line_item_sheet_id, manual_client_tax_type_id, milestone_id, payment_terms_in_days, project_id, rejected_by_id **datetime** (operators: eq, not_eq, gt, gte, lt, lte, between): approved_at, client_due_on, created_at, dated_on, due_on, level_1_approved_at, paid_at, rejected_at, sent_at, updated_at **string** (operators: eq, not_eq, in, not_in): credit_note_reason, description, external_id, external_provider, reference_number, rejected_reason, status (one of: draft = saved by supplier, not yet submitted to client; unpaid = submitted, awaiting initial approval; paid = paid by client; level_1_approved = passed first-level approval, awaiting final approval; approved = fully approved, awaiting payment; rejected = rejected by client), subtype, type (one of: invoice = all invoice types except credit notes; credit_note = credit notes only; all = every invoice type (default)) **boolean** (operators: eq, not_eq): cis_contractor, cis_subcontractor, is_credit_note, self_bill, vatable **money** (operators: eq, not_eq, in, not_in, gt, gte, lt, lte, between): cis_amount_due, cis_deductible, cis_deduction_total, net_total, tax_total, total Note: money values are in minor currency units (e.g. pence for GBP). Use 1000000 for £10,000.00. Note: `like` is a case-insensitive substring match — pass the bare term (filter[title][like]=redesign). Do not add % wildcards; they are not needed. examples: equality: summary: Simple equality value: status: draft multiple_values: summary: Multiple values (implicit IN) value: status: draft,paid with_operator: summary: With explicit operator value: created_at: gte: '2024-01-01' range: summary: Range query value: total: between: 1000000,5000000 - name: or[group] in: query style: deepObject explode: true schema: type: object description: >- OR condition groups. Filters within a group are ANDed; groups are ORed. **Syntax**: `or[group_key][]=value` or `or[group_key][][operator]=value` **Examples**: - Simple OR: `or[1][state]=draft&or[2][state]=pending` - Complex: `or[1][state]=draft&or[1][budget][gte]=50000&or[2][state]=closed` - With custom fields: `or[1][cf][priority]=high&or[2][state]=pending` Group keys can be any string (1, 2, a, b, etc.) - they just need to be unique. examples: simple_or: summary: Simple OR value: '1': status: unpaid '2': status: draft complex_or: summary: Complex OR with AND within groups value: '1': status: unpaid total: gte: '1000000' '2': status: draft - name: cf[key] in: query style: deepObject explode: true schema: type: object description: >- Custom field filters using concise syntax. **Syntax**: - Equality: `cf[key]=value` - With operator: `cf[key][operator]=value` **Operators**: eq (default), not_eq, in, not_in, contains, not_contains, exists, not_exists **Examples**: - `cf[priority]=high` - exact match - `cf[department][in]=eng,design` - matches any - `cf[priority][not_eq]=low` - not equal - `cf[notes][contains]=urgent` - contains text - `cf[legacy_field][exists]=` - field exists (value ignored) - `cf[deprecated][not_exists]=` - field does not exist examples: equality: summary: Simple equality value: priority: high with_operator: summary: With IN operator value: department: in: eng,design exists: summary: Check existence value: priority: exists: '' - name: or[group][cf][key] in: query style: deepObject explode: true schema: type: object description: >- Custom field filters within OR condition groups. **Syntax**: `or[group][cf][key]=value` or `or[group][cf][key][operator]=value` **Example**: `or[1][cf][priority]=high&or[2][state]=pending` - name: sort[] in: query style: deepObject explode: true schema: type: object description: >- Sort results by attribute. Direction defaults to ascending. **Syntax**: `sort[]=` (ascending) or `sort[]=desc` (descending) **Sortable attributes**: approved_at, approved_by_id, cis_amount_due, cis_contractor, cis_deductible, cis_deduction_total, cis_rate_id, cis_subcontractor, client_due_on, client_payment_terms_in_days, created_at, credit_note_id, credit_note_reason, dated_on, description, due_on, external_id, external_provider, id, is_credit_note, level_1_approved_at, level_1_approved_by_id, line_item_sheet_id, manual_client_tax_type_id, milestone_id, net_total, paid_at, payment_terms_in_days, project_id, reference_number, rejected_at, rejected_by_id, rejected_reason, self_bill, sent_at, status, subtype, tax_total, total, type, updated_at, vatable **Examples**: - Ascending: `sort[created_at]=` or `sort[created_at]=asc` - Descending: `sort[created_at]=desc` examples: ascending: summary: Ascending (implicit) value: created_at: '' descending: summary: Descending value: created_at: desc responses: '200': description: List of invoices content: application/json: schema: type: object properties: invoices: type: array items: $ref: '#/components/schemas/Invoice' examples: success: summary: Successful response with invoices value: invoices: - id: 101 external_id: EXT-1001 external_provider: Example external_provider description: Complete redesign of corporate website with modern UX status: unpaid project_summary: >- Website Redesign Project - Complete redesign of corporate website with modern UX vatable: true reference_number: INV-20240001 self_bill: false subtype: standard type: credit_note client: null client_org: null supplier: id: 101 name: Acme Corporation email: user1@example.com vetting_status: PASSED tax_number: Example tax_number tax_registered: true milestone_id: 501 line_item_sheet_id: 501 sent_at: '2024-01-16T10:30:00+00:00' dated_on: '2024-01-16' due_on: '2024-01-16' client_due_on: '2024-01-16' payment_terms_in_days: 30 client_payment_terms_in_days: 30 paid_at: '2024-01-16T10:30:00+00:00' is_credit_note: false credit_note_id: 501 credit_note_reason: null manual_client_tax_type: id: 101 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 101 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' net_total: cents: 150000 currency: GBP tax_total: cents: 150000 currency: GBP total: cents: 150000 currency: GBP cis_amount_due: cents: 150000 currency: GBP cis_deductible: cents: 150000 currency: GBP cis_deduction_total: cents: 150000 currency: GBP cis_rate: id: 101 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 101 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' cis_contractor: null cis_subcontractor: null invoice_items: - id: 101 external_id: EXT-1001 external_provider: Example external_provider invoice_id: 501 description: >- Complete redesign of corporate website with modern UX billing_start: '2024-01-16' billing_end: '2024-01-16' unit_type: Example unit_type milestone_id: 501 line_item_sheet_id: 501 unit_cost: cents: 150000 currency: GBP quantity: '1500.00' discount: 1500 net_total_price: null tax_total: cents: 150000 currency: GBP tax_rate: '1500.00' total_price: null cis_type: id: 101 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 101 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' tax_type: id: 101 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 101 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' manual_client_tax_type: null invoice_item_taxes: - id: 101 invoice_item_id: 501 tax_type: null tax_rate: '1500.00' tax_amount: cents: 150000 currency: GBP sales_tax_amount: cents: 150000 currency: GBP ccy: GBP position: 101 created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' - id: 102 invoice_item_id: 502 tax_type: null tax_rate: '1500.00' tax_amount: cents: 300000 currency: GBP sales_tax_amount: cents: 300000 currency: GBP ccy: GBP position: 102 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' manual_tax_type: id: 101 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 101 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' - id: 102 external_id: EXT-1002 external_provider: Example external_provider invoice_id: 502 description: Native iOS and Android application billing_start: '2024-01-17' billing_end: '2024-01-17' unit_type: Example unit_type milestone_id: 502 line_item_sheet_id: 502 unit_cost: cents: 300000 currency: GBP quantity: '1500.00' discount: 1500 net_total_price: null tax_total: cents: 300000 currency: GBP tax_rate: '1500.00' total_price: null cis_type: id: 102 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 102 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' tax_type: id: 102 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 102 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' manual_client_tax_type: null invoice_item_taxes: - id: 102 invoice_item_id: 502 tax_type: null tax_rate: '1500.00' tax_amount: cents: 300000 currency: GBP sales_tax_amount: cents: 300000 currency: GBP ccy: GBP position: 102 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' - id: 103 invoice_item_id: 503 tax_type: null tax_rate: '1500.00' tax_amount: cents: 450000 currency: GBP sales_tax_amount: cents: 450000 currency: GBP ccy: GBP position: 103 created_at: '2024-01-18T10:30:00+00:00' updated_at: '2024-01-18T10:30:00+00:00' created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' manual_tax_type: id: 102 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 102 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' approved_at: '2024-01-16T10:30:00+00:00' approved_by: id: 101 first_name: Demo last_name: User email: user1@example.com org_id: 501 org_name: Acme Corporation level_1_approved_at: '2024-01-16T10:30:00+00:00' level_1_approved_by: id: 101 first_name: Demo last_name: User email: user1@example.com org_id: 501 org_name: Acme Corporation rejected_at: '2024-01-16T10:30:00+00:00' rejected_by: id: 101 first_name: Demo last_name: User email: user1@example.com org_id: 501 org_name: Acme Corporation rejected_reason: null custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' project: id: 101 title: Website Redesign Project description: >- Complete redesign of corporate website with modern UX - id: 102 external_id: EXT-1002 external_provider: Example external_provider description: Native iOS and Android application status: paid project_summary: >- Website Redesign Project - Complete redesign of corporate website with modern UX vatable: true reference_number: INV-20240002 self_bill: false subtype: standard type: all client: null client_org: null supplier: id: 102 name: Global Services Ltd email: user2@example.com vetting_status: FAILED tax_number: Example tax_number tax_registered: true milestone_id: 502 line_item_sheet_id: 502 sent_at: '2024-01-17T10:30:00+00:00' dated_on: '2024-01-17' due_on: '2024-01-17' client_due_on: '2024-01-17' payment_terms_in_days: 30 client_payment_terms_in_days: 30 paid_at: '2024-01-17T10:30:00+00:00' is_credit_note: false credit_note_id: 502 credit_note_reason: null manual_client_tax_type: id: 102 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 102 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' net_total: cents: 300000 currency: GBP tax_total: cents: 300000 currency: GBP total: cents: 300000 currency: GBP cis_amount_due: cents: 300000 currency: GBP cis_deductible: cents: 300000 currency: GBP cis_deduction_total: cents: 300000 currency: GBP cis_rate: id: 102 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 102 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' cis_contractor: null cis_subcontractor: null invoice_items: - id: 102 external_id: EXT-1002 external_provider: Example external_provider invoice_id: 502 description: Native iOS and Android application billing_start: '2024-01-17' billing_end: '2024-01-17' unit_type: Example unit_type milestone_id: 502 line_item_sheet_id: 502 unit_cost: cents: 300000 currency: GBP quantity: '1500.00' discount: 1500 net_total_price: null tax_total: cents: 300000 currency: GBP tax_rate: '1500.00' total_price: null cis_type: id: 102 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 102 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' tax_type: id: 102 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 102 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' manual_client_tax_type: null invoice_item_taxes: - id: 102 invoice_item_id: 502 tax_type: null tax_rate: '1500.00' tax_amount: cents: 300000 currency: GBP sales_tax_amount: cents: 300000 currency: GBP ccy: GBP position: 102 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' - id: 103 invoice_item_id: 503 tax_type: null tax_rate: '1500.00' tax_amount: cents: 450000 currency: GBP sales_tax_amount: cents: 450000 currency: GBP ccy: GBP position: 103 created_at: '2024-01-18T10:30:00+00:00' updated_at: '2024-01-18T10:30:00+00:00' created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' manual_tax_type: id: 102 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 102 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' - id: 103 external_id: EXT-1003 external_provider: Example external_provider invoice_id: 503 description: Native iOS and Android application billing_start: '2024-01-18' billing_end: '2024-01-18' unit_type: Example unit_type milestone_id: 503 line_item_sheet_id: 503 unit_cost: cents: 450000 currency: GBP quantity: '1500.00' discount: 1500 net_total_price: null tax_total: cents: 450000 currency: GBP tax_rate: '1500.00' total_price: null cis_type: id: 103 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 103 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-18T10:30:00+00:00' updated_at: '2024-01-18T10:30:00+00:00' tax_type: id: 103 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 103 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-18T10:30:00+00:00' updated_at: '2024-01-18T10:30:00+00:00' manual_client_tax_type: null invoice_item_taxes: - id: 103 invoice_item_id: 503 tax_type: null tax_rate: '1500.00' tax_amount: cents: 450000 currency: GBP sales_tax_amount: cents: 450000 currency: GBP ccy: GBP position: 103 created_at: '2024-01-18T10:30:00+00:00' updated_at: '2024-01-18T10:30:00+00:00' - id: 104 invoice_item_id: 504 tax_type: null tax_rate: '1500.00' tax_amount: cents: 600000 currency: GBP sales_tax_amount: cents: 600000 currency: GBP ccy: GBP position: 104 created_at: '2024-01-19T10:30:00+00:00' updated_at: '2024-01-19T10:30:00+00:00' created_at: '2024-01-18T10:30:00+00:00' updated_at: '2024-01-18T10:30:00+00:00' manual_tax_type: id: 103 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 103 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-18T10:30:00+00:00' updated_at: '2024-01-18T10:30:00+00:00' approved_at: '2024-01-17T10:30:00+00:00' approved_by: id: 102 first_name: Jane last_name: Smith email: user2@example.com org_id: 502 org_name: Global Services Ltd level_1_approved_at: '2024-01-17T10:30:00+00:00' level_1_approved_by: id: 102 first_name: Jane last_name: Smith email: user2@example.com org_id: 502 org_name: Global Services Ltd rejected_at: '2024-01-17T10:30:00+00:00' rejected_by: id: 102 first_name: Jane last_name: Smith email: user2@example.com org_id: 502 org_name: Global Services Ltd rejected_reason: null custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' project: id: 102 title: Mobile App Development description: Native iOS and Android application empty: summary: Empty result set value: invoices: [] filtered: summary: Filtered results description: Results after applying filters value: invoices: - id: 101 external_id: EXT-1001 external_provider: Example external_provider description: Complete redesign of corporate website with modern UX status: unpaid project_summary: >- Website Redesign Project - Complete redesign of corporate website with modern UX vatable: true reference_number: INV-20240001 self_bill: false subtype: standard type: credit_note client: null client_org: null supplier: id: 101 name: Acme Corporation email: user1@example.com vetting_status: PASSED tax_number: Example tax_number tax_registered: true milestone_id: 501 line_item_sheet_id: 501 sent_at: '2024-01-16T10:30:00+00:00' dated_on: '2024-01-16' due_on: '2024-01-16' client_due_on: '2024-01-16' payment_terms_in_days: 30 client_payment_terms_in_days: 30 paid_at: '2024-01-16T10:30:00+00:00' is_credit_note: false credit_note_id: 501 credit_note_reason: null manual_client_tax_type: id: 101 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 101 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' net_total: cents: 150000 currency: GBP tax_total: cents: 150000 currency: GBP total: cents: 150000 currency: GBP cis_amount_due: cents: 150000 currency: GBP cis_deductible: cents: 150000 currency: GBP cis_deduction_total: cents: 150000 currency: GBP cis_rate: id: 101 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 101 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' cis_contractor: null cis_subcontractor: null invoice_items: - id: 101 external_id: EXT-1001 external_provider: Example external_provider invoice_id: 501 description: >- Complete redesign of corporate website with modern UX billing_start: '2024-01-16' billing_end: '2024-01-16' unit_type: Example unit_type milestone_id: 501 line_item_sheet_id: 501 unit_cost: cents: 150000 currency: GBP quantity: '1500.00' discount: 1500 net_total_price: null tax_total: cents: 150000 currency: GBP tax_rate: '1500.00' total_price: null cis_type: id: 101 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 101 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' tax_type: id: 101 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 101 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' manual_client_tax_type: null invoice_item_taxes: - id: 101 invoice_item_id: 501 tax_type: null tax_rate: '1500.00' tax_amount: cents: 150000 currency: GBP sales_tax_amount: cents: 150000 currency: GBP ccy: GBP position: 101 created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' - id: 102 invoice_item_id: 502 tax_type: null tax_rate: '1500.00' tax_amount: cents: 300000 currency: GBP sales_tax_amount: cents: 300000 currency: GBP ccy: GBP position: 102 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' manual_tax_type: id: 101 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 101 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' - id: 102 external_id: EXT-1002 external_provider: Example external_provider invoice_id: 502 description: Native iOS and Android application billing_start: '2024-01-17' billing_end: '2024-01-17' unit_type: Example unit_type milestone_id: 502 line_item_sheet_id: 502 unit_cost: cents: 300000 currency: GBP quantity: '1500.00' discount: 1500 net_total_price: null tax_total: cents: 300000 currency: GBP tax_rate: '1500.00' total_price: null cis_type: id: 102 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 102 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' tax_type: id: 102 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 102 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' manual_client_tax_type: null invoice_item_taxes: - id: 102 invoice_item_id: 502 tax_type: null tax_rate: '1500.00' tax_amount: cents: 300000 currency: GBP sales_tax_amount: cents: 300000 currency: GBP ccy: GBP position: 102 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' - id: 103 invoice_item_id: 503 tax_type: null tax_rate: '1500.00' tax_amount: cents: 450000 currency: GBP sales_tax_amount: cents: 450000 currency: GBP ccy: GBP position: 103 created_at: '2024-01-18T10:30:00+00:00' updated_at: '2024-01-18T10:30:00+00:00' created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' manual_tax_type: id: 102 label: Example label country_code: Example country_code rate: '1500.00' domestic_recharge: true tax_reference: 102 archived: true custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' approved_at: '2024-01-16T10:30:00+00:00' approved_by: id: 101 first_name: Demo last_name: User email: user1@example.com org_id: 501 org_name: Acme Corporation level_1_approved_at: '2024-01-16T10:30:00+00:00' level_1_approved_by: id: 101 first_name: Demo last_name: User email: user1@example.com org_id: 501 org_name: Acme Corporation rejected_at: '2024-01-16T10:30:00+00:00' rejected_by: id: 101 first_name: Demo last_name: User email: user1@example.com org_id: 501 org_name: Acme Corporation rejected_reason: null custom_fields: department: Engineering priority: high cost_code: CC-001 created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' project: id: 101 title: Website Redesign Project description: >- Complete redesign of corporate website with modern UX '401': description: >- Unauthorized - the access token is missing, expired, revoked or malformed content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid_token error_description: >- The access token provided is expired, revoked, malformed, or invalid for other reasons '403': description: Forbidden - insufficient scope content: application/json: schema: $ref: '#/components/schemas/Error' example: error: insufficient_scope error_description: >- The request requires higher privileges than provided by the access token required_scope: invoices:read provided_scopes: - welcome:read '422': description: Invalid filter or sort parameters content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_attribute: summary: Unknown filter attribute value: error: 'Invalid filter attribute: unknown_field' invalid_operator: summary: Invalid operator for type value: error: Operator 'like' is not valid for integer type invalid_value: summary: Invalid value format value: error: 'Invalid date format for created_at: not-a-date' invalid_sort_attribute: summary: Unknown sort attribute value: error: 'Invalid sort attribute: unknown_field' invalid_sort_direction: summary: Invalid sort direction value: error: Invalid sort direction 'random'. Must be 'asc' or 'desc' security: - oauth2: - invoices:read tenantId: [] components: schemas: Invoice: type: object properties: id: type: integer external_id: type: string external_provider: type: string description: type: string status: type: string enum: - draft - unpaid - paid - level_1_approved - approved - rejected example: draft project_summary: type: string vatable: type: boolean example: true reference_number: type: string self_bill: type: boolean example: true subtype: type: string type: type: string enum: - invoice - credit_note - all example: invoice client: type: string client_org: type: string supplier: oneOf: - $ref: '#/components/schemas/EmbeddedSupplier' - type: 'null' milestone_id: type: integer line_item_sheet_id: type: integer sent_at: type: string dated_on: type: string due_on: type: string client_due_on: type: string payment_terms_in_days: type: integer client_payment_terms_in_days: type: integer paid_at: type: string is_credit_note: type: boolean example: true credit_note_id: type: integer credit_note_reason: type: string manual_client_tax_type: oneOf: - $ref: '#/components/schemas/TaxType' - type: 'null' net_total: $ref: '#/components/schemas/Money' tax_total: $ref: '#/components/schemas/Money' total: $ref: '#/components/schemas/Money' cis_amount_due: $ref: '#/components/schemas/Money' cis_deductible: $ref: '#/components/schemas/Money' cis_deduction_total: $ref: '#/components/schemas/Money' cis_rate: oneOf: - $ref: '#/components/schemas/TaxType' - type: 'null' cis_contractor: type: boolean example: true cis_subcontractor: type: boolean example: true invoice_items: type: array items: $ref: '#/components/schemas/InvoiceItem' approved_at: type: string approved_by: oneOf: - $ref: '#/components/schemas/EmbeddedUser' - type: 'null' level_1_approved_at: type: string level_1_approved_by: oneOf: - $ref: '#/components/schemas/EmbeddedUser' - type: 'null' rejected_at: type: string rejected_by: oneOf: - $ref: '#/components/schemas/EmbeddedUser' - type: 'null' rejected_reason: type: string custom_fields: type: object additionalProperties: type: string description: Key-value pairs of custom field data created_at: type: string updated_at: type: string project: oneOf: - $ref: '#/components/schemas/EmbeddedProject' - type: 'null' Error: type: object description: Error envelope returned by every non-2xx V4 response properties: error: type: string example: insufficient_scope error_description: type: string message: type: string details: type: object additionalProperties: true required_scope: type: string example: projects:read provided_scopes: type: array items: type: string EmbeddedSupplier: type: object properties: id: type: integer name: type: string email: type: string vetting_status: type: string enum: - NOT REGISTERED - PASSED - FAILED - PENDING example: NOT REGISTERED tax_number: type: string tax_registered: type: boolean example: true TaxType: type: object properties: id: type: integer label: type: string country_code: type: string rate: type: string domestic_recharge: type: boolean example: true tax_reference: type: integer archived: type: boolean example: true custom_fields: type: object additionalProperties: type: string description: Key-value pairs of custom field data created_at: type: string updated_at: type: string Money: type: object properties: cents: type: integer example: 150000 currency: type: string example: GBP InvoiceItem: type: object properties: id: type: integer external_id: type: integer external_provider: type: string invoice_id: type: integer description: type: string billing_start: type: string billing_end: type: string unit_type: type: string milestone_id: type: integer line_item_sheet_id: type: integer unit_cost: $ref: '#/components/schemas/Money' quantity: type: string discount: type: string net_total_price: type: string tax_total: $ref: '#/components/schemas/Money' tax_rate: type: string total_price: type: string cis_type: oneOf: - $ref: '#/components/schemas/TaxType' - type: 'null' tax_type: oneOf: - $ref: '#/components/schemas/TaxType' - type: 'null' manual_client_tax_type: type: string invoice_item_taxes: type: array items: $ref: '#/components/schemas/InvoiceItemTax' created_at: type: string updated_at: type: string manual_tax_type: oneOf: - $ref: '#/components/schemas/TaxType' - type: 'null' EmbeddedUser: type: object properties: id: type: integer first_name: type: string last_name: type: string email: type: string org_id: type: integer org_name: type: string EmbeddedProject: type: object properties: id: type: integer title: type: string description: type: string InvoiceItemTax: type: object properties: id: type: integer invoice_item_id: type: integer tax_type: type: string tax_rate: type: string tax_amount: $ref: '#/components/schemas/Money' sales_tax_amount: $ref: '#/components/schemas/Money' ccy: type: string position: type: integer created_at: type: string updated_at: type: string securitySchemes: oauth2: type: oauth2 description: >- OAuth 2.0 client credentials. The access token from POST /oauth/token is sent as a bearer token. Request only the scopes you need. flows: clientCredentials: tokenUrl: https://api.zivio.net/api/v4/oauth/token scopes: bank_accounts:read: Read bank account details on suppliers and the org. catalogs:read: Read catalog items. cost_centers:read: Read cost center records. eoi_responses:read: Read responses to expressions of interest. eois:read: Read expressions of interest. offers:read: Read offers for projects. org_units:read: Read your organization unit hierarchy. org_users:read: Read members of your organization. resources:read: Read resource (worker) records. sales_invoices:read: Read invoices issued to clients. sales_milestones:read: Read milestones on sales engagements. skill_categories:read: Read the skill category taxonomy. skill_taxonomies:read: Read skill taxonomy structure. skills:read: Read individual skills. supplier_documents:read: Read documents uploaded by suppliers. supplier_lists:read: Read curated lists of suppliers. supplier_users:read: Read users belonging to supplier organizations. tax_types:read: Read configured tax types. users:read: Read user profiles. variation_orders:read: Read variation orders on projects. welcome:read: 'Required: confirms your identity to the application.' bid_evaluations:read: >- Read evaluation scorecards for bids, including criterion scores and quality, cost and total scores. bid_evaluations:write: >- Score bids against a project's quality criteria and override calculated cost scores. bids:read: Read bids submitted on projects. bids:write: >- Shortlist, select, eliminate and reinstate bids submitted on projects. invoices:read: Read invoices on projects. invoices:write: Create and update invoices. notes:read: Read notes on projects and EOIs. notes:write: Create and update notes on projects and EOIs. project_approvals:read: Read project approval workflows. project_approvals:write: Create and update project approval workflows. project_conversations:read: Read messages exchanged with suppliers on a project. project_conversations:write: Send messages to suppliers on a project. project_invitations:read: Read supplier invitations on projects. project_invitations:write: Invite suppliers to bid on projects. project_questions:read: Read supplier clarification questions on projects. project_questions:write: Answer and approve supplier clarification questions. projects:read: Read projects. projects:write: Create and update projects. milestones:read: Read milestones on projects. milestones:write: Create and update milestones. orgs:read: Read organization records. orgs:write: Create and update organization records. purchase_orders:read: Read purchase orders. purchase_orders:write: Create and update purchase orders. reviews:read: Read reviews left on suppliers. reviews:write: Create and update reviews. suppliers:read: Read supplier profiles. suppliers:write: Create and update supplier profiles. raw_scorecard_entries:write: Create and update raw scorecard entries. raw_scorecard_entries:read: Read raw scorecard entries. tasks:read: >- Read the acting user's task queue, including outstanding approvals and items to review. tasks:write: Complete and dismiss tasks in the acting user's task queue. act_as_user: >- Make requests as another user within the token holder's delegation boundary. tenantId: type: apiKey name: zivio-tenant-id in: header description: >- Your Zivio organisation identifier. The regional API endpoints serve every Zivio organisation, so each request must identify yours. ````