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 tohttps://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 validaccess_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 theexpires_in
field has passed. That said, it is fundamental to store the returnedrefresh_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).
Updated 15 days ago