Employment Management
Bulk list employments
Lists full-detail employments for the company scope, page-by-page via an opaque cursor. Each employment is the same shape returned by Show employment, except files are excluded to avoid a per-employment file lookup; use the Show employment endpoint to fetch files for a specific employment. The files field is always null on this endpoint.
Pass the next_cursor value from a page's response as the cursor query parameter to fetch the next page. next_cursor is null once the last page has been reached.
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 employments (employments) | View employments (employment:read) | Manage employments (employment:write) |
| Company-scoped access token (assertion) | Manage employments (employments) | View employments (employment:read) | Manage employments (employment:write) |
| Customer API token | Manage employments (employments) | View employments (employment:read) | Manage employments (employment:write) |
get/v1/employments/bulk
Request
- Base URLhttps://gateway.remote.com
- URLhttps://gateway.remote.com/v1/employments/bulk
- 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: employment: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: employment: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
company_idstring
Company ID
cursorstring
Opaque pagination cursor returned as next_cursor from a previous page.
limitinteger
Number of employments to return per page (max 100, default 50).
group_tax_servicing_countriesboolean
When true, returns tax_servicing_countries grouped into global/regions/subregions instead of a flat list of country names.
Response
Success
Example response
{
"data": [
{
"personal_details": {},
"manager_email": "john.doe@company.com",
"provisional_start_date": "2021-07-03",
"address_details": {},
"pricing_plan_details": {
"frequency": "annually"
},
"full_name": "Jane Smith",
"type": "employee",
"employment_lifecycle_stage": "employee_self_enrollment",
"administrative_details": {},
"company_id": "e31adae1-company-id-af5fba7dd803",
"work_address_details": {},
"bill_to_legal_entity_id": "663e0b79-c893-45ff-a1b2-f6dcabc098b5",
"work_email": "jane.smith@company.com",
"status": "created",
"updated_at": "2021-07-15T18:18:17Z",
"basic_information": {},
"job_title": "Engineer",
"id": "20a72f86-employment-id-9e4942a902ff",
"manager": "John Doe",
"login_email": "jane@smith.com",
"employment_model": "eor",
"personal_email": "jane@smith.com",
"country": {
"alpha_2_code": "PT",
"code": "PRT",
"contractor_products_available": [
"standard",
"plus",
"cor"
],
"country_subdivisions": [
{
"code": "PT-06",
"name": "Coimbra",
"subdivision_type": "District"
},
{
"code": "PT-11",
"name": "Lisboa",
"subdivision_type": "District"
}
],
"employment_agreement_preview_available": true,
"eor_onboarding": true,
"global_payroll_supported": true,
"locked_benefits": "after_first_hire",
"name": "Portugal",
"region": "Europe",
"subregion": "Southern Europe",
"supported_json_schemas": [
"additional_documents",
"address_details",
"administrative_details",
"employment-basic-information",
"bank_account_details",
"contract_details",
"emergency_contact"
]
},
"user_status": "active",
"bank_account_details": [],
"files": [],
"engaged_by_legal_entity_id": "663e0b79-c893-45ff-a1b2-f6dcabc098b5",
"billing_address_details": {},
"onboarding_tasks": {
"address_details": {
"description": "Primary residence.",
"status": "completed"
},
"administrative_details": {
"description": "Information we need for tax purposes.",
"status": "completed"
},
"bank_account_details": {
"description": "Bank account used for receiving salary payments.",
"status": "completed"
},
"billing_address_details": {
"description": "Address associated with the employee's bank account.",
"status": "completed"
},
"contract_details": {
"description": "Employee-specific details for their employment agreement.",
"status": "completed"
},
"emergency_contact_details": {
"description": "Who should be called in an emergency.",
"status": "completed"
},
"employment_document_details": {
"description": "We need some additional documents.",
"status": "pending"
},
"personal_details": {
"description": "Personal details, such as name and date of birth.",
"status": "completed"
},
"pricing_plan_details": {
"description": "How often Remote will bill employers for management fees.",
"status": "completed"
}
},
"contract_details": {},
"emergency_contact_details": {},
"eligible_for_onboarding_cancellation": true,
"manager_employment_id": "20a72f86-employment-id-9e4942a902ff",
"created_at": "2021-11-11T18:44:39"
}
],
"next_cursor": "eyJpZCI6MTIzfQ"
}Changes
No recorded changes to this operation across all 1 revision of this API.