Remote Company Management API
The Company Management API from Remote — 4 operation(s) for company management.
The Company Management API from Remote — 4 operation(s) for company management.
openapi: 3.0.0
info:
title: Remote Address Details Company Management API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Company Management
paths:
/v1/companies/schema:
get:
callbacks: {}
deprecated: false
description: 'Returns the json schema of the requested company form.
Currently only supports the `address_details` form.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage company resources (`company_admin`) | View companies (`company:read`) | Manage companies (`company:write`) |
'
operationId: get_v1_companies_schema
parameters:
- description: Country code according to ISO 3-digit alphabetic codes.
example: CAN
in: query
name: country_code
required: true
schema:
type: string
- description: Name of the desired form
example: address_details
in: query
name: form
required: true
schema:
enum:
- address_details
type: string
- description: Version of the form schema
example: 1
in: query
name: json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyFormResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- OAuth2ClientCredentials:
- https://gateway.remote.com/company.manage
- company:read
- company:write
- company_admin
- all:write
- all:read
summary: Show form schema
tags:
- Company Management
/v1/companies/{company_id}:
get:
callbacks: {}
description: 'Given an ID, shows a company.
If the used access token was issued by the OAuth 2.0 Authorization Code flow,
then only the associated company can be accessed through the endpoint.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage company resources (`company_admin`) | View companies (`company:read`) | Manage companies (`company:write`) |
'
operationId: get_v1_companies_company_id
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: Company ID
example: 0a8s2d1-company-id-2e3f4th
in: path
name: company_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Too many requests
security:
- OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- company:read
- company:write
- company_admin
- all:write
- all:read
OAuth2ClientCredentials:
- https://gateway.remote.com/company.manage
- company:read
- company:write
- company_admin
- all:write
- all:read
summary: Show a company
tags:
- Company Management
patch:
callbacks: {}
description: 'Given an ID and a request object with new information, updates a company.
### Getting a company and its owner to `active` status
If you created a company using the
[create a company endpoint](#tag/Companies/operation/post_create_company) without all the required
request body parameters, you can use this endpoint to provide the missing data. Once the company
and its owner have all the necessary data, both their statuses will be set to `active` and the company
onboarding will be marked as "completed".
The following constitutes a company with "all the necessary data":
* Complete `address`, with valid `address`, `postal_code`, `country` and `state` parameters (Varies by country. Use the
[show form schema endpoint](#tag/Countries/operation/get_show_form_country) to see which address parameters
are required).
* Company `tax_number` or `registration_number` is not nil
* Company `name` is not nil (already required when creating the company)
* Company has a `desired_currency` in their bank account (already required when creating the company)
* Company has accepted terms of service (already required when creating the company)
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage companies (`company_management`) | - | Manage companies (`company:write`) |
'
operationId: patch_v1_companies_company_id (2)
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: Version of the address_details form schema
example: 1
in: query
name: address_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the bank_account_details form schema
example: 1
in: query
name: bank_account_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: 'Company ID
'
example: 0a8s2d1-company-id-2e3f4th
in: path
name: company_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCompanyParams'
description: Update Company params
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Too many requests
security:
- OAuth2ClientCredentials:
- https://gateway.remote.com/company.manage
- company:write
- company_management
- all:write
summary: Update a company
tags:
- Company Management
put:
callbacks: {}
description: 'Given an ID and a request object with new information, updates a company.
### Getting a company and its owner to `active` status
If you created a company using the
[create a company endpoint](#tag/Companies/operation/post_create_company) without all the required
request body parameters, you can use this endpoint to provide the missing data. Once the company
and its owner have all the necessary data, both their statuses will be set to `active` and the company
onboarding will be marked as "completed".
The following constitutes a company with "all the necessary data":
* Complete `address`, with valid `address`, `postal_code`, `country` and `state` parameters (Varies by country. Use the
[show form schema endpoint](#tag/Countries/operation/get_show_form_country) to see which address parameters
are required).
* Company `tax_number` or `registration_number` is not nil
* Company `name` is not nil (already required when creating the company)
* Company has a `desired_currency` in their bank account (already required when creating the company)
* Company has accepted terms of service (already required when creating the company)
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage companies (`company_management`) | - | Manage companies (`company:write`) |
'
operationId: patch_v1_companies_company_id
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: Version of the address_details form schema
example: 1
in: query
name: address_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the bank_account_details form schema
example: 1
in: query
name: bank_account_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: 'Company ID
'
example: 0a8s2d1-company-id-2e3f4th
in: path
name: company_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCompanyParams'
description: Update Company params
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Too many requests
security:
- OAuth2ClientCredentials:
- https://gateway.remote.com/company.manage
- company:write
- company_management
- all:write
summary: Update a company
tags:
- Company Management
/v1/companies/{company_id}/actions:
get:
callbacks: {}
description: 'Given a company ID, returns the company-level actions still pending for the company — for
example company verification and Remote Payments setup. The list can be empty or contain one
or more actions; `setup_remote_payments` is returned once per legal entity that needs it.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage company resources (`company_admin`) | View companies (`company:read`) | Manage companies (`company:write`) |
'
operationId: get_v1_companies_company_id_actions
parameters:
- description: Company ID
example: 0a8s2d1-company-id-2e3f4th
in: path
name: company_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyActionsResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Too many requests
security:
- OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- company:read
- company:write
- company_admin
- all:write
- all:read
OAuth2ClientCredentials:
- https://gateway.remote.com/company.manage
- company:read
- company:write
- company_admin
- all:write
- all:read
summary: List a company's pending actions
tags:
- Company Management
/v1/companies:
get:
callbacks: {}
deprecated: false
description: 'List all companies that authorized your integration to act on their behalf. In other words, these are all the companies that your integration can manage. Any company that has completed the authorization flow for your integration will be included in the response.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage company resources (`company_admin`) | View companies (`company:read`) | Manage companies (`company:write`) |
'
operationId: get_v1_companies
parameters:
- description: '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.
'
example: Bearer <CLIENT-CREDENTIALS ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: External ID
in: query
name: external_id
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CompaniesResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- OAuth2ClientCredentials:
- https://gateway.remote.com/company.manage
- company:read
- company:write
- company_admin
- all:write
- all:read
summary: List all companies
tags:
- Company Management
post:
callbacks: {}
deprecated: false
description: " Creates a new company.\n\n ### Creating a company with only the required request body parameters\n When you call this endpoint and omit all the optional parameters in the request body,\n the following resources get created upon a successful response:\n * A new company with status `pending`.\n * A company owner for the new company with status `initiated`.\n\n See the [update a company endpoint](#tag/Companies/operation/patch_update_company) for\n more details on how to get your company and its owner to `active` status.\n\n If you'd like to create a company and its owner with `active` status in a single request,\n please provide the optional `address_details` parameter as well.\n\n ### Accepting the Terms of Service\n\n A required step for creating a company in Remote is to accept our Terms of Service (ToS).\n\n Company managers need to be aware of our Terms of Service and Privacy Policy,\n hence **it's the responsibility of our partners to advise and ensure company managers read\n and accept the ToS**. The terms have to be accepted only once, before creating a company,\n and the Remote API will collect the acceptance timestamp as its confirmation.\n\n To ensure users read the most recent version of Remote's Terms of Service, their **acceptance\n must be done within the last fifteen minutes prior the company creation action**.\n\n To retrieve this information, partners can provide an element with any text and a description\n explaining that by performing that action they are accepting Remote's Term of Service. For\n instance, the partner can add a checkbox or a \"Create Remote Account\" button followed by a\n description saying \"By creating an account, you agree to\n [Remote's Terms of Service](https://remote.com/terms-of-service). Also see Remote's\n [Privacy Policy](https://remote.com/privacy-policy)\".\n\n\n## Scopes\n\n| Category | Read only Scope | Write only Scope (read access implicit) |\n|---|---|---|\n| Manage companies (`company_management`) | - | Manage companies (`company:write`) |\n"
operationId: post_v1_companies
parameters:
- description: '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.
'
example: Bearer <CLIENT-CREDENTIALS ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: Version of the address_details form schema
example: 1
in: query
name: address_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the bank_account_details form schema
example: 1
in: query
name: bank_account_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: '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](https://employ.remote.com/api-integration-new-password-send)
'
example: get_oauth_access_tokens,send_create_password_email
in: query
name: action
required: false
schema:
type: string
- description: 'Whether the request should be performed async
'
example: true
in: query
name: async
required: false
schema:
type: boolean
- description: 'Scope of the access token
'
example: file:read timeoff:create
in: query
name: scope
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCompanyParams'
description: Create Company params
required: false
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyCreationResponse'
description: Created
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyCreationConflictErrorResponse'
description: Conflict
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- OAuth2ClientCredentials:
- https://gateway.remote.com/company.manage
- company:write
- company_management
- all:write
summary: Create a company
tags:
- Company Management
components:
schemas:
ParameterError:
example:
code: invalid_param
message: Invalid parameter
param: employment_id
properties:
code:
description: An error code that describes the nature of the error.
type: string
message:
description: A developer friendly error message that gives details on what the error was and how it may be remedied.
type: string
param:
description: The parameter that lead to the error message.
type: string
required:
- code
- message
- param
title: ParameterError
type: object
CompanyNotEligibleForCreationErrorResponse:
description: Error returned when the company already have employees in countries supported by the integration.
example:
data:
code: resource_not_eligible
message: The company already have employees in integration supported countries.
resource_id: d1bb9535-3296-4240-8a67-81475bd24e80
resource_type: company_creation
properties:
code:
pattern: resource_not_eligible
type: string
message:
pattern: The company already have employees in integration supported countries.
type: string
resource_id:
format: uuid
type: string
resource_type:
pattern: company_creation
type: string
title: CompanyNotEligibleForCreationErrorResponse
type: object
CompanyWithTokensResponse:
description: Shows a company with its refresh and access tokens. Please contact Remote if you need the tokens when creating a company.
example:
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'
tokens:
access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.cThIIoDvwdueQB468K5xDc5633seEFoqwxjF_xSJyQQ
company_id: 6e60f5f9-e6a6-4b04-b13c-84bced848bab
expires_in: 7200
refresh_token: b480036a-d229-49ef-a606-7e8fba58a5eb
token_type: Bearer
user_id: 6550e536-8655-4bce-8bd9-b295f786ad71
properties:
company:
$ref: '#/components/schemas/Company'
tokens:
$ref: '#/components/schemas/OAuth2Tokens'
title: CompanyWithTokensResponse
type: object
CompanyActionsResponse:
description: Lists a company's pending actions
example:
data:
actions:
- required: true
type: verify_company
- legal_entity_id: 31b8e49b-aa1c-47af-849c-3d0a53e20e0d
required: true
type: setup_remote_payments
properties:
data:
properties:
actions:
items:
$ref: '#/components/schemas/CompanyAction'
type: array
type: object
required:
- data
title: CompanyActionsResponse
type: object
RefreshTokenResponse:
allOf:
- $ref: '#/components/schemas/BaseTokenResponse'
- example:
access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.cThIIoDvwdueQB468K5xDc5633seEFoqwxjF_xSJyQQ
expires_in: 7200
refresh_token: b480036a-d229-49ef-a606-7e8fba58a5eb
token_type: Bearer
properties:
refresh_token:
description: The refresh token
type: string
type: object
example:
access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.cThIIoDvwdueQB468K5xDc5633seEFoqwxjF_xSJyQQ
expires_in: 7200
refresh_token: b480036a-d229-49ef-a606-7e8fba58a5eb
token_type: Bearer
title: RefreshTokenResponse
type: object
UnauthorizedResponse:
description: Returned when the request does not include valid authentication credentials. Ensure you are passing a valid OAuth2 access token or API token in the Authorization header.
example:
message: Unauthorized
properties:
message:
pattern: Unauthorized
type: string
required:
- message
title: UnauthorizedResponse
type: object
CompanyAction:
description: A pending company-level action (e.g. for Contractor Management Review-step banners).
example:
legal_entity_id: 31b8e49b-aa1c-47af-849c-3d0a53e20e0d
required: true
type: setup_remote_payments
properties:
legal_entity_id:
description: The legal entity that needs Remote Payments setup. Present only for setup_remote_payments actions.
nullable: true
type: string
required:
description: Whether the action must be completed.
type: boolean
type:
description: The action the company still needs to complete.
enum:
- verify_company
- setup_remote_payments
type: string
required:
- type
- required
title: CompanyAction
type: object
CompanyCreationConflictErrorResponse:
example:
data:
message: The company with the provided EIN is already registered.
properties:
message:
oneOf:
- $ref: '#/components/schemas/CompanyAlreadyExistsErrorResponse'
- $ref: '#/components/schemas/CompanyNotEligibleForCreationErrorResponse'
title: CompanyCreationConflictErrorResponse
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-company-management-api-openapi.yml