Contractors
Invoices

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

Changed on

Lists Contractor Invoice records.

Authentication

This endpoint accepts any one of the following token types:

  • Company-scoped access token (OAuth2AuthorizationCode) — obtained through the Authorization Code flow or the Refresh Token flow. See Authentication for partners.
  • Customer API token (CustomerAPIToken) — generated by the customer on their Integration Settings page. See Authorization for customers.

Scopes

CategoryRead only ScopeWrite only Scope (read access implicit)
Manage invoices (invoices)View invoices (invoices:read)Manage invoices (invoices:write)
get/v1/contractor-invoices

Request

  • Base URL: https://gateway.remote.com
  • URL: https://gateway.remote.com/v1/contractor-invoices
  • Auth: HTTP bearer and OAuth 2 (authorization code, authorization URL /auth/oauth2/authorize, token URL /auth/oauth2/token, scopes: https://gateway.remote.com/company.manage, invoices:read, invoices:write, invoices, all:write, all:read)

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.
Example:issued

Filters contractor invoices by status matching the value.

contractor_invoice_schedule_idstring uuid

A unique identifier in UUID v4 format.

Example:663e0b79-c893-45ff-a1b2-f6dcabc098b5

Filters contractor invoices by invoice schedule ID matching the value.

date_fromstring date

UTC date in ISO 8601 format

Example:2021-07-01

Filters contractor invoices by date greater than or equal to the value.

date_tostring date

UTC date in ISO 8601 format

Example:2021-07-01

Filters contractor invoices by date less than or equal to the value.

due_date_fromstring date

UTC date in ISO 8601 format

Example:2021-07-01

Filters contractor invoices by due date greater than or equal to the value.

due_date_tostring date

UTC date in ISO 8601 format

Example:2021-07-01

Filters contractor invoices by due date less than or equal to the value.

approved_date_fromstring date

UTC date in ISO 8601 format

Example:2021-07-01

Filters contractor invoices by approved date greater than or equal to the value.

approved_date_tostring date

UTC date in ISO 8601 format

Example:2021-07-01

Filters contractor invoices by approved date less than or equal to the value.

paid_out_date_fromstring date

UTC date in ISO 8601 format

Example:2021-07-01

Filters contractor invoices by paid out date greater than or equal to the value.

paid_out_date_tostring date

UTC date in ISO 8601 format

Example:2021-07-01

Filters contractor invoices by paid out date less than or equal to the value.

sort_by'date' | 'due_date' | 'approved_at' | 'paid_out_at'

Field to sort by

order'asc' | 'desc'

Sort order

pageinteger

Starts fetching records after the given page

page_sizeinteger

Number of items per page

Response

Success

Example response

{
  "contractor_invoices": [
    {
      "amount": 350000,
      "approved_at": "2024-06-05T00:00:00Z",
      "contractor_invoice_schedule_id": "9f8e7d6c-5b4a-3c2d-1e0f-a1b2c3d4e5f6",
      "currency": "BRL",
      "date": "2024-06-01",
      "description": "Mobile developer payment.",
      "due_date": "2024-06-15",
      "fx_rate": 1.12,
      "id": "663e0b79-c893-45ff-a1b2-f6dcabc098b5",
      "items": [
        {
          "amount": 5000,
          "description": "Description",
          "type": "manual"
        }
      ],
      "number": "ABC123",
      "paid_out_at": "2024-06-05T12:00:00Z",
      "pay_out_method": "swift_our",
      "payment": {
        "amount_due": 350000,
        "billing_document_id": null,
        "currency": "USD",
        "due_date": "2024-06-15",
        "pay_in_method": "bank_transfer",
        "reference": "TR0000000042",
        "status": "awaiting_payment"
      },
      "processing_fee": 500,
      "processing_fee_currency": "USD",
      "processing_fee_payer": "company",
      "source_amount": 350000,
      "source_currency": "BRL",
      "status": "paid_out",
      "target_amount": 350000,
      "target_currency": "BRL"
    }
  ],
  "current_page": 1,
  "total_count": 1,
  "total_pages": 1
}

Changes

  • 011e5a8b97f5Revision changes
    • warning

      added the new upload_summary enum value to the ///// response property for the response status

  • be4636f25834Revision changes
    • warning

      added the new partially_paid enum value to the //// response property for the response status

    • info

      added the required property //// to the response with the status