Creating Companies

The OAuth2 Authorization Code Flow allows Company Admins to connect their accounts securely with a Remote API Partner.

Eligible API Partners are allowed to create the company and get the company's consent in a single request. This means that the company creation endpoint can do both:

Create the Remote Company using the Remote UI and
Grant permissions for the API Partner to manage it through the API. In this case, the Company Admin doesn't need to go through the Authorization Code Flow.

If you are not sure about your eligibility, reach out to your Remote contact for clarifications.

Creating the company and getting the consent

ℹ️ When you’re ready to release your integration, replace the domain with https://gateway.remote.com.
You can find the API documentation for the /v1/companies endpoint here.

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 POST request to https://gateway.remote-sandbox.com/eor/v1/companies?action=get_oauth_access_tokens
Notice the action query string. This parameter informs the Remote API that it should also return a valid access_token for managing the newly created company.
Include the Authorization header with a valid access token generated by the Client Credentials Flow.
Include the Content-Type: application/json header to indicate the format of the submitted data.
Send the required fields encoded in JSON format. Ensure that the country_code you’re using is a supported country using the list countries endpoint.

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"
  }
}'

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 mentioned 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).