Company creation
In this guide, you will learn how to
- Request authorization from companies that you would like to manage on their behalf.
- Create your first company and obtain a company-scoped access token at the same time.
Before you get started
Before you get started, ensure that
- You have valid credentials. For more details, visit Authorization for Partners.
- You have a valid access token using the
client_credentialsgrant. For more details, visit Client Credentials Flow for Partners.
Creating your first company
If you want to act on behalf of a company that already exists, you would follow the Authorization Code Flow to request consent from an admin of that company. But what about when your integration is the one creating the company?
Eligible Remote API partners are allowed to create the company and get the company’s “consent” in a single request. That means you can get the access token for the company at the same time you create the company, eliminating your need to go through the Authorization Code Flow to obtain consent after creating the company through the Remote API.
How do you know if you’re an eligible Remote API partner?
When making the creating company call with the action=get_oauth_access_tokens parameter, if you receive an error response that contains the following body, it’s likely because you’re not yet eligible to create your company and get the consent in the same request yet:
{
"message": "invalid_params"
}
If you’re not sure about your eligibility or would like to request access to this feature, you can reach out to your Remote contact for clarification or email [email protected].
Checking if your desired country is supported
The Remote API supports the most popular countries requested by our customers, but not every country is supported. To check which countries are supported, you can use the List countries endpoint.
$ curl --location \
--request GET \
--header 'Authorization: Bearer eyJraWQ...' \
'https://gateway.remote-sandbox.com/eor/v1/countries'
If your desired country is not supported, you can reach out to your Remote contact or email [email protected] to let us know of your interest to hire in your country of choice.
Creating the company and getting the consent
In order to create the company and get consent in a single operation, a POST request needs to be done against the company creation endpoint with the proper parameters. Here's how to build the request:
- Send a
POSTrequest tohttps://gateway.remote-sandbox.com/eor/v1/companies?action=get_oauth_access_tokens - Notice the
actionquery string. This parameter informs the Remote API that it also should return a validaccess_tokenfor managing the newly created company. - Include the
Authorizationheader with a valid access token generated by the Client Credentials Flow. - Include the
Content-Type: application/jsonheader to indicate the format of the submitted data. - Send the required fields encoded in JSON format. Ensure that the
country_codeyou’re using is a supported country using the list countries endpoint. - 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.
- 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".
Request example
$ curl --location \
--request POST \
--header 'Authorization: Bearer eyJraWQ...' \
--header 'Content-Type: application/json' \
'https://gateway.remote-sandbox.com/eor/v1/companies?action=get_oauth_access_tokens' \
--data-raw '{
"name": "My Test Co.",
"tax_number": "123456789",
"country_code": "CAN",
"desired_currency": "CAD",
"company_owner_email": "[email protected]",
"company_owner_name": "Jane Smith",
"terms_of_service_accepted_at": "2022-05-06 16:35:00Z",
"address_details": {
"address": "Adress line 1",
"address_line_2": "Address line 2",
"city": "San Francisco",
"postal_code": "90001",
"state": "CA"
}
}'
{
"data": {
"tokens": {
"refresh_token": "7e70ace....2e74e",
"expires_in": 3600,
"access_token": "eyJhb.....o"
},
"company": {
"id": "3b8da86f-6114-443c-a1c0-.......",
"name": "Partner_Custompany",
"status": "active",
"updated_at": "2024-08-02T23:19:40",
"external_id": null,
"created_at": "2024-08-02T23:19:39",
"country_code": "GBR",
"phone_number": "2403606588",
"bank_account_details": null,
"tax_number": "7984465",
"registration_number": null,
"desired_currency": "GBP",
"company_owner_email": "[email protected]",
"company_owner_name": "John Pustomer",
"address_details": {
"address": "1709 Broderick St",
"address_line_2": "Flat number 123",
"city": "London",
"postal_code": "SW79 8SY"
},
"terms_of_service_accepted_at": "2024-08-02T23:19:38Z"
}
}
}
curl --location 'https://gateway.niceremote.com/v1/companies/schema?country_code=GBR&form=address_details' \
--header 'Authorization: Bearer eyJra...' \
{
"data": {
"additionalProperties": false,
"properties": {
"address": {
"maxLength": 255,
"title": "Address",
"type": "string",
"x-jsf-presentation": {
"inputType": "text"
}
},
"address_line_2": {
"description": "(Optional) For example, apartment, block, or building number.",
"maxLength": 255,
"title": "Address line 2",
"type": [
"string",
"null"
],
"x-jsf-presentation": {
"inputType": "text"
}
},
"city": {
"maxLength": 255,
"title": "City",
"type": "string",
"x-jsf-presentation": {
"inputType": "text"
}
},
"postal_code": {
"description": "Make sure you enter the correct UK postal code format. Eg: KY11 9NN, N1 2NU, LS1 8EQ",
"maxLength": 255,
"pattern": "^([A-Z]{1,2}[0-9][A-Z0-9]?|[BFS]IQQ) ?[0-9][A-Z]{2}$",
"title": "Postal code",
"type": "string",
"x-jsf-presentation": {
"inputType": "text"
}
}
},
"required": [
"address",
"city",
"postal_code"
],
"type": "object",
"x-jsf-order": [
"address",
"address_line_2",
"city",
"postal_code"
]
}
}
Parsing the response
Here’s an example response you might receive:
{
"data": {
"company":{
...
},
"tokens":{
"access_token": "<ACCESS TOKEN>",
"refresh_token": "<REFRESH TOKEN>",
"expires_in": 3600
}
}
}
The response payload contains two main fields: company and tokens. The company field contains all information regarding the newly created company, such as the name, address, and status.
The tokens field contains crucial information about the consent. The access_token contains a valid access token that can be used for managing the created company.
Note that the returned access_tokens expires after the number of seconds contained in the expires_in field has passed. That said, it is fundamental to store the returned refresh_token securely.
The refresh_token is crucial for requesting new access tokens through the Refresh Token Flow as the access_token is only valid for 1 hour (equivalent to 3600 seconds).
There are other forms such as bank_account_details that can be fetched and data can be mapped as per the schema to be included in creation/updating request for a Company. Find more details here.
Updated about 1 month ago