---
title: "List Contractor Invoices"
method: GET
path: "/v1/contractor-invoices"
tags: ["Invoices"]
---

# List Contractor Invoices

`GET /v1/contractor-invoices`

Lists Contractor Invoice records.

## Scopes

| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| 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 — Identifier of the employment being terminated.
- `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, nullable, required — Currency code of the SWIFT fee. Only present when processing_fee is set.
      - `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', 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.
      - `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.
      - `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, nullable, required — Currency code of the SWIFT fee. Only present when processing_fee is set.
      - `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.net/remote-com/apis/remote.md) · [All operations](https://skmtc.net/remote-com/apis/remote/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/remote-com/remote/revisions/7e6a0c61ac82/schema)