List Contractor Invoices. Requires a token issued via the authorization_code grant (company_manager role) — not usable with a client_credentials (integration) token.
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.
- 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.
- Customer API token (CustomerAPIToken) — generated by the customer on their Integration Settings page, with the scopes they choose there. See 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) |
Request
- Base URLhttps://gateway.remote.com
- URLhttps://gateway.remote.com/v1/contractor-invoices
- Auth
- OAuth 2Authorization code: /auth/oauth2/authorizeToken URL: /auth/oauth2/token scopes: https://gateway.remote.com/company.manage
- or OAuth 2Authorization code: /auth/oauth2/authorizeToken URL: /auth/oauth2/token scopes: invoices:read
- or OAuth 2Authorization code: /auth/oauth2/authorizeToken URL: /auth/oauth2/token scopes: all:read
- or OAuth 2Authorization code: /auth/oauth2/authorizeToken URL: /auth/oauth2/token scopes: all:write
- or OAuth 2Client credentialsToken URL: /auth/oauth2/token scopes: invoices:read
- or OAuth 2Client credentialsToken URL: /auth/oauth2/token scopes: all:read
- or OAuth 2Client credentialsToken URL: /auth/oauth2/token scopes: all:write
- or HTTP bearer
Query parameters
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.
Filters contractor invoices by status matching the value.
A unique identifier in UUID v4 format.
Filters contractor invoices by invoice schedule ID matching the value.
A unique identifier in UUID v4 format.
Filters contractor invoices by the employment ID matching the value. Returns 404 when the employment does not exist or belongs to another company.
Filters contractor invoices by date greater than or equal to the value.
Filters contractor invoices by date less than or equal to the value.
Filters contractor invoices by due date greater than or equal to the value.
Filters contractor invoices by due date less than or equal to the value.
Filters contractor invoices by approved date greater than or equal to the value.
Filters contractor invoices by approved date less than or equal to the value.
Filters contractor invoices by paid out date greater than or equal to the value.
Filters contractor invoices by paid out date less than or equal to the value.
Field to sort by
Sort order
Starts fetching records after the given page
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
No recorded changes to this operation across all 1 revision of this API.