---
title: "List Contractor Invoices. Requires a token issued via the authorization_code grant (company_manager role) — not usable with a client_credentials (integration) token."
method: GET
path: "/v1/contractor-invoices"
tags: ["Invoices"]
---

# List Contractor Invoices. Requires a token issued via the authorization_code grant (company_manager role) — not usable with a client_credentials (integration) token.

`GET /v1/contractor-invoices`

## Request

- Base URL: `https://gateway.remote.com`
- URL: `https://gateway.remote.com/v1/contractor-invoices`
- Auth: one of:
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `https://gateway.remote.com/company.manage`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `invoices:read`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `all:read`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `all:write`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `invoices:read`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `all:read`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `all:write`
  - HTTP bearer

Lists Contractor Invoice records.

## Authentication

This endpoint accepts any one of the following token types:

- **Company-scoped access token** (`OAuth2AuthorizationCode`) — obtained by a company manager through the Authorization Code flow or the Refresh Token flow. See [Authentication for partners](https://developer.remote.com/docs/authentication-for-partners).
- **Company-scoped access token (assertion)** (`OAuth2CompanyManagerAssertion`) — obtained through the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant for a company manager. See [OAuth Assertion](https://developer.remote.com/docs/authorization-method-oauth-assertion).
- **Customer API token** (`CustomerAPIToken`) — generated by the customer on their Integration Settings page, with the scopes they choose there. See [Authorization for customers](https://developer.remote.com/docs/authorization-for-customers).

## Scopes

Any one of the scopes in a token type's row is enough. `all:read` and `all:write` work too.

| Token type | Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|---|
| Company-scoped access token | Manage invoices (`invoices`) | View invoices (`invoices:read`) | Manage invoices (`invoices:write`) |
| Company-scoped access token (assertion) | Manage invoices (`invoices`) | View invoices (`invoices:read`) | Manage invoices (`invoices:write`) |
| Customer API token | Manage invoices (`invoices`) | View invoices (`invoices:read`) | Manage invoices (`invoices:write`) |

## Query parameters

- `status` 'issued' | 'draft' | 'approved' | 'pending_payment' | 'in_review' | 'externally_paid' | 'rejected' | 'rejected_by_remote' | 'blocked' | 'compliance_review' | 'compliance_failed' | 'pay_out_scheduled' | 'enqueued' | 'processing' | 'manual_payout' | 'paid_out' | 'pay_out_failed' | 'funds_returned': Current record state. - `enqueued`: An outstanding payment is enqueued to complete the invoice payment. - `externally_paid`: The invoice was paid outside the platform and the employer reported that the contractor was paid. - `issued`: This invoice has been uploaded by the contractor. - `in_review`: This invoice has been uploaded by the contractor and is in the process of review by Remote. This is only expected for Contractor of Record invoices. - `paid_out`: This invoice has been paid out to contractor. This is the final expected stage of a contractor invoice. - `pay_out_failed`: There were issues paying out to the contractor. This is usually caused by a balance issue, an issue with the contractor's bank account, or another type error that comes from payment partner. - `pending_payment`: An outstanding payment has been created for this invoice and is awaiting the company payment before payout begins. - `processing`: The invoice is being processed for pay out. This status should only exist for a few seconds. - `rejected`: This invoice has been rejected by the the company or Remote support team, when requested by customers. It cannot be rejected if it's already paid. - `rejected_by_remote`: This invoice has been rejected by Remote during the Contractor of Record approval process. - `funds_returned`: A pay out was successfully attempted for the invoice, but the funds were rejected by the contractor's bank, either due to incorrect details or some other reason. - `manual_payout`: The invoice is not supported by our automated systems and must instead be manually paid by internal Remote teams. - `blocked`: The invoice is marked as blocked. It will not be paid out.
- `contractor_invoice_schedule_id` string, uuid: A unique identifier in UUID v4 format.
- `employment_id` string, uuid: A unique identifier in UUID v4 format.
- `date_from` string, date: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
- `date_to` string, date: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
- `due_date_from` string, date: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
- `due_date_to` string, date: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
- `approved_date_from` string, date: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
- `approved_date_to` string, date: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
- `paid_out_date_from` string, date: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
- `paid_out_date_to` string, date: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
- `sort_by` 'date' | 'due_date' | 'approved_at' | 'paid_out_at'
- `order` 'asc' | 'desc'
- `page` integer
- `page_size` integer

## Response `200`

Success

- ListContractorInvoicesResponse: Paginated response schema listing all Contractor Invoices.
  - `data` object
    - `contractor_invoices` ContractorInvoice[]
      - `amount` integer, required: Overall amount that is calculated by summing all invoice items.
      - `approved_at` string, datetime, nullable: The datetime which contractor invoice has been approved and it's pending for payment.
      - `contractor_invoice_schedule_id` string, uuid, nullable: Invoice schedule that might have generated contractor invoice.
      - `currency` string, required: Currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
      - `date` string, date, required: The issuance date specified by a contractor.
      - `description` string, nullable: Custom defined description.
      - `due_date` string, date, nullable: The payment deadline chosen by the contractor while creating an invoice.
      - `employment_id` string, uuid: Employment identifier associated with the contractor invoice.
      - `fx_rate` number, float, nullable: The guaranteed FX rate applied for the payment. Only present for guaranteed payout invoices.
      - `id` string, uuid, required: Contractor Invoice identifier.
      - `items` ContractorInvoiceItem[], required: Invoice line items.
        - `amount` integer, required: Amount, in cents.
        - `description` string, required: Describes invoice item intent.
        - `type` 'manual' | 'time_tracking' | 'expense' | 'upload_summary', required: Current types. - `manual`: Item manually entered when creating invoice. - `time_tracking`: Item generated by time tracking. - `expense`: Item that represents an expense included in the invoice. - `upload_summary`: Single item on an uploaded invoice. It carries the VAT the contractor stated on the uploaded PDF, and summarises the PDF rather than copying its lines.
      - `number` string, nullable: Invoice identifier.
      - `paid_out_at` string, utc_datetime, nullable: Date and time which invoice was paid to contractor.
      - `pay_out_method` 'local' | 'swift' | 'swift_our', nullable: Payment method used for the payout: local (e.g. bank transfer), swift (SHA), or swift_our (OUR). Only present for guaranteed payout invoices.
      - `payment` ContractorInvoicePayment, nullable: The payment that settles this invoice, or `null` while no payment does. `reference` is the transaction receipt (TR) number for Contractor Management and the Remote invoice number for Contractor of Record; it changes when a payment is reset and re-initiated. `amount_due` is the total of the payment this invoice belongs to, shared by every invoice in it. `status` says where the payment stands and `pay_in_method` how Remote collects it; the invoice's pay-in details are the authority on whether and where to wire.
        - `amount_due` integer, required: Total amount of the payment in cents, shared by every invoice in it. This is the amount the payment was raised for, not a running balance: when `status` is `partially_paid` Remote has already received part of it and the outstanding balance is lower. Remote contacts the company directly with that balance; it is not published here.
        - `billing_document_id` string, uuid, nullable, required: The billing document's public id. Set only for Contractor-of-Record invoices, null otherwise.
        - `currency` string, required: Currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
        - `due_date` string, date, nullable, required: Optional UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
        - `pay_in_method` 'bank_transfer' | 'direct_debit' | 'card' | 'prefunding_credit' | 'other' | 'not_selected', required: How Remote collects this payment: `bank_transfer` when the company wires it, `direct_debit` for a mandate-based collection, `card`, `prefunding_credit` when prefunded balance covers it, and `other` for anything else. Wire when this reads `bank_transfer`; Remote collects `direct_debit`, `card` and `prefunding_credit` itself and a transfer would pay twice. `not_selected` means Remote has not recorded a collection method: for Contractor of Record that lasts until the company starts the payment, so confirm the arrangement before wiring.
        - `reference` string, required: The reference to quote when paying: the transaction receipt number, or the Remote invoice number for Contractor of Record. Put it in the transfer memo, with the company name; Remote matches an incoming transfer on it.
        - `status` 'awaiting_payment' | 'partially_paid' | 'blocked' | 'processing' | 'paid', required: Where the payment stands: `awaiting_payment` means Remote has not received the funds and the payment is still expected, `processing` that a collection is in flight, and `paid` that Remote has received the funds. `partially_paid` means Remote received some of the amount but not all of it, because the company underpaid or part of a collection failed after the rest settled; `amount_due` still shows the original total rather than what remains, and Remote follows up with the company on the outstanding balance directly. `blocked` means the payment is on a compliance hold: the reference stays valid, and the payment returns to `awaiting_payment` once Remote lifts it.
      - `processing_fee` integer, nullable: SWIFT fee amount in cents. Only present when pay_out_method is swift or swift_our.
      - `processing_fee_currency` string, nullable: Currency code of the SWIFT fee. Only present when processing_fee is set.
      - `processing_fee_payer` 'company' | 'contractor', nullable: Entity responsible for paying the SWIFT fee. Only present when processing_fee is set.
      - `source_amount` integer, required: The amount the company needs to pay (pay in amount).
      - `source_currency` string, required: Currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
      - `status` 'issued' | 'draft' | 'approved' | 'pending_payment' | 'in_review' | 'externally_paid' | 'rejected' | 'rejected_by_remote' | 'blocked' | 'compliance_review' | 'compliance_failed' | 'pay_out_scheduled' | 'enqueued' | 'processing' | 'manual_payout' | 'paid_out' | 'pay_out_failed' | 'funds_returned', required: Current record state. - `enqueued`: An outstanding payment is enqueued to complete the invoice payment. - `externally_paid`: The invoice was paid outside the platform and the employer reported that the contractor was paid. - `issued`: This invoice has been uploaded by the contractor. - `in_review`: This invoice has been uploaded by the contractor and is in the process of review by Remote. This is only expected for Contractor of Record invoices. - `paid_out`: This invoice has been paid out to contractor. This is the final expected stage of a contractor invoice. - `pay_out_failed`: There were issues paying out to the contractor. This is usually caused by a balance issue, an issue with the contractor's bank account, or another type error that comes from payment partner. - `pending_payment`: An outstanding payment has been created for this invoice and is awaiting the company payment before payout begins. - `processing`: The invoice is being processed for pay out. This status should only exist for a few seconds. - `rejected`: This invoice has been rejected by the the company or Remote support team, when requested by customers. It cannot be rejected if it's already paid. - `rejected_by_remote`: This invoice has been rejected by Remote during the Contractor of Record approval process. - `funds_returned`: A pay out was successfully attempted for the invoice, but the funds were rejected by the contractor's bank, either due to incorrect details or some other reason. - `manual_payout`: The invoice is not supported by our automated systems and must instead be manually paid by internal Remote teams. - `blocked`: The invoice is marked as blocked. It will not be paid out.
      - `target_amount` integer, nullable: The amount the contractor receives (pay out amount). Can be null if pay out is not guaranteed.
      - `target_currency` string, nullable: Currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
    - `current_page` integer: The current page among all of the total_pages
    - `total_count` integer: The total number of records in the result
    - `total_pages` integer: The total number of pages the user can go through

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity

---

[API](https://skmtc.dev/remote-com/apis/contractors.md) - [All operations](https://skmtc.dev/remote-com/apis/contractors/llms.txt) - [OpenAPI document](https://skmtc.dev/remote-com/apis/contractors/revisions/e1e7f1caaada?raw)