---
title: "Create bulk employment job"
method: POST
path: "/v1/bulk-employment-jobs"
tags: ["Employment Management"]
---

# Create bulk employment job

`POST /v1/bulk-employment-jobs`

## Request

- Base URL: `https://gateway.remote.com`
- URL: `https://gateway.remote.com/v1/bulk-employment-jobs`
- 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: `employment:write`
  - 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: `employment:write`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `all:write`
  - HTTP bearer

Creates a job to bulk-create employments for multiple employees at once. Each employee payload must match the employment schema for the selected country.

## 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:write` works too.

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

## Request body

- BulkEmploymentCreateParams: Creates an asynchronous bulk employment job. Global Payroll activation is currently limited to Serbia (SRB) and requires the `bulk_gp_product_activation` feature flag. Submission happens after the initial `202` response; if a row later fails during Global Payroll activation, the failure is reported through the bulk-employment rows/status endpoints rather than the create response.
  - `country_code` string, required: Country code according to ISO 3166-1 3-digit alphabetic codes.
  - `employees` BulkEmploymentEmployeePayload[], required
    - `activate_global_payroll` boolean
    - `send_invitation` boolean: Per-employee override for onboarding invitations. Takes precedence over the batch-level `send_invitation` value when present.
  - `send_invitation` boolean: Batch default for onboarding invitations. Each employee can override it with their own `send_invitation` value. Defaults to `false` when omitted.

## Response `202`

Accepted

- BulkEmploymentImportJobResponse
  - `data` BulkEmploymentImportJob, required
    - `column_mapping` object, nullable: The column mapping for the import job. For times when imported data columns do not match the schema fields and need to be manually mapped to the correct schema fields.
      - `auto_mapped_columns` string[]: The column names that have been automatically mapped by Tiger (rawr!) and maybe also by AI.
      - `mapping` object, required: The map of schema fields paths to data columns
      - `source_columns` object[], required: The data columns to map to
        - `index` integer, required: The index of the data column in the file
        - `name` string, required: The name of the data column
        - `sample_data` string, nullable: A sample data value from the data column
      - `unmapped_column_count` integer, required: The number of columns that have not been mapped
      - `unmapped_required_field_count` integer, required: The number of required schema field paths that have not been mapped
    - `display_name` string: The name to be displayed for the user interface
    - `errors` string[]
    - `failed_count` integer, required: The number of rows that failed to be processed
    - `finished_at` string, datetime, nullable, required: Optional UTC date time in YYYY-MM-DDTHH:mm:ss format
    - `id` string, uuid, required
    - `imported_count` integer: The number of rows that have been imported in previous submission stages
    - `inserted_at` string, datetime, required: UTC date time in YYYY-MM-DDTHH:mm:ss format
    - `inserted_by` union, required: Someone registered in Remote using a unique email address.
      - object
        - `email` string, email, nullable: The email used for authentication. It may be hidden in case no permission is given to see sensible data.
        - `name` string, required
        - `personal_details` PersonalDetails: Personal details for a user, includes sensitive information
          - `birthdate` string
          - `full_preferred_name` string, nullable
          - `gender` string, nullable
          - `gender_description` string, nullable
          - `given_name` string, nullable
          - `is_us_person` boolean, nullable
          - `mobile_number` string
          - `nationality` string[]
          - `preferred_name` string, nullable
          - `preferred_pronouns` string, nullable
          - `recovery_number` string, nullable
          - `redacted_fields` string[]: Names of fields redacted because the caller lacks the required attribute permission
          - `sex` string, nullable
          - `surname` string, nullable
          - `title` 'mr' | 'mrs' | 'miss' | 'ms' | 'mx', nullable
        - `profile_picture` string, uri, nullable
        - `slug` string, required
        - `status` 'active' | 'cancelled' | 'deleted' | 'inactive' | 'draft' | 'created' | 'invited' | 'initiated'
      - object
        - `account` AccountsAccount: An Account
          - `login_email` Email
            - `address` string, required
            - `confirmed_at` string, datetime, nullable: Optional UTC date time in YYYY-MM-DDTHH:mm:ss format
            - `login_synced` boolean
            - `status` 'pending' | 'confirmed' | 'deleted'
            - `type` 'login' | 'personal' | 'work'
            - `unconfirmed_address` string, nullable
          - `login_synced_with` 'none' | 'personal' | 'work', nullable: Indicates which email type the account login is synchronized with.
          - `personal_email` object, nullable
            - `address` string, required
            - `confirmed_at` string, datetime, nullable: Optional UTC date time in YYYY-MM-DDTHH:mm:ss format
            - `login_synced` boolean
            - `status` 'pending' | 'confirmed' | 'deleted'
            - `type` 'login' | 'personal' | 'work'
            - `unconfirmed_address` string, nullable
          - `slug` string, required
          - `status` 'created' | 'active' | 'deleted' | 'locked'
        - `assigned_roles` object[], nullable
          - `data_scope` 'all' | 'employment_entities' | 'external' | 'internal' | 'rps' | 'secondary_reports' | 'direct_reports' | 'employment_countries' | 'onboarding_reports' | 'direct_and_indirect_reports' | 'assigned_billing_legal_entities' | 'employment_departments' | 'employment_company_structure_nodes'
          - `name` string, required
          - `slug` string, required
          - `type` 'default' | 'custom' | 'template' | 'owner'
        - `integration_users` AccountUserIntegrationUser[]
          - `external_user_id` string, required
          - `integration` object, required
            - `name` string, required
          - `role` 'employee' | 'employer', required: Whether this mapping represents a synced employee or a company admin
          - `sync_to_remote_status` 'enabled' | 'disabled', nullable: Whether the employee should be synced to Remote based on the sync_to_remote flag in the external HRIS
        - `invited_by` AccountsMinimalCompanyAdmin
          - `job_title` string, nullable
          - `name` string
          - `slug` string
        - `job_title` string, nullable
        - `login_synced_with` 'none' | 'personal' | 'work', nullable: Indicates which email type the account login is synchronized with.
        - `raw_email` string
        - `role` 'admin' | 'employer' | 'employee' | 'freelancer' | 'service_provider' | 'candidate'
        - `signup_source` string, nullable
    - `legal_entity` object, nullable
      - `name` string
      - `slug` string, uuid: A unique identifier in UUID v4 format.
    - `metadata` object, required: The metadata for the import job
    - `name` string, required
    - `processed_count` integer, required: The number of processed rows, regardless of success or failure
    - `reupload_merge_fields` string[]: Row-data fields this uploader matches on when a re-uploaded CSV is merged into the draft. Empty when the uploader cannot merge.
    - `reupload_modes` string[]: How a re-uploaded CSV may be applied to this uploader's existing rows. The uploader lists them with `reupload_modes` in its config, and an empty list means none is offered. While the `bulk_uploader_reupload_modes` flag is off only `replace` is listed.
    - `server_metadata` object: Metadata only Remote sets for the import job, for example whether it is a self-serve job
    - `stage` 'creation' | 'column_mapping' | 'validation' | 'submission', required: The stage of the import job. * `creation` - The import job is in the creation stage, which means the rows are being created. * `column_mapping` - The import job is in the column mapping stage, which means the CSV headers are being mapped to JSON schema fields. * `validation` - The import job is in the validation stage, which means the rows are being validated. * `submission` - The import job is in the submission stage, which means the rows are being submitted.
    - `status` 'draft' | 'uploaded' | 'in_progress' | 'finished' | 'failed', required: * `draft` - **Deprecated**, the import job data has been uploaded and the job created, but not yet started * `uploaded` - **Deprecated**, replaced by the `draft` status * `in_progress` - Data is actively being imported * `finished` - The import job has finished processing * `failed` - The import job has failed completely, nothing has been imported
    - `total_count` integer, required: The total number of rows to import
    - `updated_at` string, datetime, required: UTC date time in YYYY-MM-DDTHH:mm:ss format

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `422`: Unprocessable Entity
- `429`: Unprocessable Entity

---

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