Sign in

v1

latestOpenAPI 3.1.02026-07-242735131.1 MB
Company Management

Create a company

Creates a new company.

Creating a company with only the required request body parameters

When you call this endpoint and omit all the optional parameters in the request body, the following resources get created upon a successful response:

  • A new company with status pending.
  • A company owner for the new company with status initiated.

See the update a company endpoint for more details on how to get your company and its owner to active status.

If you'd like to create a company and its owner with active status in a single request, please provide the optional address_details parameter as well.

Accepting the Terms of Service

A required step for creating a company in Remote is to accept our Terms of Service (ToS).

Company managers need to be aware of our Terms of Service and Privacy Policy, hence it's the responsibility of our partners to advise and ensure company managers read and accept the ToS. The terms have to be accepted only once, before creating a company, and the Remote API will collect the acceptance timestamp as its confirmation.

To ensure users read the most recent version of Remote's Terms of Service, their acceptance must be done within the last fifteen minutes prior the company creation action.

To retrieve this information, partners can provide an element with any text and a description explaining that by performing that action they are accepting Remote's Term of Service. For instance, the partner can add a checkbox or a "Create Remote Account" button followed by a description saying "By creating an account, you agree to Remote's Terms of Service. Also see Remote's Privacy Policy".

Scopes

CategoryRead only ScopeWrite only Scope (read access implicit)
Manage companies (company_management)-Manage companies (company:write)
post/v1/companies

Query parameters

integer

Specific version number

OR
'latest'

Use latest version

Version of the address_details form schema

integer

Specific version number

OR
'latest'

Use latest version

Version of the bank_account_details form schema

actionstring

Complementary action(s) to perform when creating a company:

  • get_oauth_access_tokens returns the user's access and refresh tokens
  • send_create_password_email sends a reset password token to the company owner's email so they can log in using Remote UI (not needed if integration plans to use SSO only)

If action contains send_create_password_email you can redirect the user to https://employ.remote.com/api-integration-new-password-send

asyncboolean

Whether the request should be performed async

scopestring

Scope of the access token

Headers

Authorizationstring required

Requires a client credentials access token obtained through the Client Credentials flow or the Refresh Token flow.

The refresh token needs to have been obtained through the Client Credentials flow.

Request body

address_detailsobject

Fields can vary depending on the country. Please, check the required fields structure using the Show form schema endpoint. Use the desired country and address_details as the form name for the placeholders. The response complies with the JSON Schema specification.

bank_account_detailsobject

Fields can vary depending on the country. Please, check the required fields structure using the Show form schema endpoint. Use the desired country and bank_account_details as the form name for the placeholders. The response complies with the JSON Schema specification.

company_owner_emailstring email required

The company owner email.

This value cannot be changed once set.

company_owner_namestring required

The company owner name.

This value cannot be changed from the Remote API once set.

country_codestring required

3-letter country code of the country the company address is located in.

For a list of countries supported through the Remote API, make a call to the list countries endpoint. This endpoint will also include the 3-letter country codes you can use for this field.

desired_currency'AUD' | 'CAD' | 'CHF' | 'DKK' | 'EUR' | 'GBP' | 'JPY' | 'NOK' | 'NZD' | 'SEK' | 'SGD' | 'USD' required

Desired currency for invoicing and displaying converted salaries in Remote UI regardless of the employee's country.

email_domainstring

The domain of the company. Use this field to specify the company domain name when it's different from the domain in the company owner's email.

external_idstring

Id of the company as represented in the external partner system.

namestring required

The company name

phone_numberstring

A phone number the company can be contacted with.

registration_numberstring

The company registration number. This field or tax_number (but not both) should be submitted.

tax_numberstring

The tax identifier of the company. This field or registration_number (but not both) should be submitted.

terms_of_service_accepted_atstring date-time required

Date and time the Terms of Service were accepted. To ensure users read the most recent version of Remote's Terms of Service, their action cannot have been done more than fifteen minutes ago. The UTC offset must be included in the ISO 8601 format: YYYY-MM-DD HOURS:MINUTES:SECONDSZ

Example request

{
  "address_details": {
    "address": "1709 Broderick St",
    "address_line_2": "Flat number 123",
    "city": "San Francisco",
    "postal_code": "94115",
    "state": "CA"
  },
  "bank_account_details": {
    "account_holder": "Joe Smith",
    "account_number": "31234123123",
    "account_type": "savings",
    "name": "Bank name",
    "ownership_type": "BUSINESS",
    "routing_number": "123124123"
  },
  "company_owner_email": "ceo@techvision.com",
  "company_owner_name": "Joe Smith",
  "country_code": "USA",
  "desired_currency": "USD",
  "external_id": "00001111",
  "name": "Tech Vision",
  "phone_number": "+11123123456",
  "tax_number": "123456789",
  "terms_of_service_accepted_at": "2022-05-05 15:03:45Z"
}

Response

Created

Example response

{
  "data": {
    "data": {
      "company": {
        "address_details": {
          "address": "1709 Broderick St",
          "address_line_2": "Flat number 123",
          "city": "San Francisco",
          "postal_code": "94115",
          "state": "CA"
        },
        "bank_account_details": {
          "account_holder": "Joe Smith",
          "account_number": "31234123123",
          "account_type": "savings",
          "name": "Bank name",
          "ownership_type": "BUSINESS",
          "routing_number": "123124123"
        },
        "company_owner_email": "te@remote.com",
        "company_owner_name": "Joe Smith",
        "company_owner_user_id": "75619adf-8775-4531-9e7d-5b2cbabdc1a8",
        "country_code": "USA",
        "created_at": "2021-07-15T18:18:17Z",
        "default_legal_entity_credit_risk_status": "no_deposit_required",
        "desired_currency": "USD",
        "external_id": "00001111",
        "id": "e5a8b061-company-id-4c5c81ac885e",
        "name": "Your Company Name",
        "phone_number": "+1123123456",
        "status": "active",
        "terms_of_service_accepted_at": "2021-10-29T12:39:15Z",
        "updated_at": "2021-07-15T18:18:17Z"
      }
    }
  }
}