Remote Companies API

openapi: 3.0.0
info:
  title: Remote Address Details Companies API
  version: 0.1.0
servers:
- url: https://gateway.remote.com/
  variables: {}
- url: https://gateway.remote-sandbox.com/
  variables: {}
security:
- OAuth2: []
tags:
- name: Companies
paths:
  /v1/companies/{company_id}/employments/{employment_id}/onboarding-reserves-status:
    get:
      callbacks: {}
      deprecated: false
      description: 'Returns the onboarding reserves status for a specific employment.


        The status is the same as the credit risk status but takes the onboarding reserves policies into account.



        ## Scopes


        | Category | Read only Scope | Write only Scope (read access implicit) |

        |---|---|---|

        | Manage employments (`employments`) | View employments (`employment:read`) | Manage employments (`employment:write`) |

        '
      operationId: get_v1_companies_company_id_employments_employment_id_onboarding-reserves-status
      parameters:
      - description: Company ID
        example: d2091b1e-b1a4-437a-91ea-2809ffbb6d59
        in: path
        name: company_id
        required: true
        schema:
          $ref: '#/components/schemas/UuidSlug'
      - description: Employment ID
        example: 97e04d61-0a6d-4c4f-9299-c08d1eeaba20
        in: path
        name: employment_id
        required: true
        schema:
          $ref: '#/components/schemas/UuidSlug'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingReservesStatusResponse'
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
      security:
      - OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - employment:read
        - employment:write
        - employments
        - all:write
        - all:read
        OAuth2ClientCredentials:
        - https://gateway.remote.com/company.manage
        - employment:read
        - employment:write
        - employments
        - all:write
        - all:read
      summary: Get Onboarding Reserves Status for Employment
      tags:
      - Companies
  /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:
      - Companies
  /v1/companies/{company_id}/compliance-profile:
    get:
      callbacks: {}
      deprecated: false
      description: 'Returns the KYB and credit risk status for the company''s default legal entity.



        ## 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_compliance-profile
      parameters:
      - description: Company ID
        example: d2091b1e-b1a4-437a-91ea-2809ffbb6d59
        in: path
        name: company_id
        required: true
        schema:
          $ref: '#/components/schemas/UuidSlug'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyComplianceProfileResponse'
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
      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: Get Company Compliance Profile
      tags:
      - Companies
  /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:
      - Companies
    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:
      - Companies
    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:
      - Companies
  /v1/company-managers:
    get:
      callbacks: {}
      description: 'List all company managers of an integration. If filtered by the company_id param,

        it lists only company managers belonging to the specified company.



        ## Scopes


        | Category | Read only Scope | Write only Scope (read access implicit) |

        |---|---|---|

        | Manage company resources (`company_admin`) | View managers (`company_manager:read`) | Manage managers (`company_manager:write`) |

        '
      operationId: get_v1_company-managers
      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: A Company ID to filter the results (only applicable for Integration Partners).
        example: 0a8s2d1-company-id-2e3f4th
        in: query
        name: company_id
        required: false
        schema:
          type: string
      - description: Starts fetching records after the given page
        example: 1
        in: query
        name: page
        required: false
        schema:
          type: integer
      - description: Change the amount of records returned per page, defaults to 20, limited to 100
        example: 30
        in: query
        name: page_size
        required: false
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyManagersResponse'
          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:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - company_manager:read
        - company_manager:write
        - company_admin
        - all:write
        - all:read
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - company_manager:read
        - company_manager:write
        - company_admin
        - all:write
        - all:read
      summary: List Company Managers
      tags:
      - Companies
    post:
      callbacks: {}
      description: 'Create a Company Manager and sends the invitation email for signing in to the Remote Platform.


        ## Scopes


        | Category | Read only Scope | Write only Scope (read access implicit) |

        |---|---|---|

        | Manage company resources (`company_admin`) | - | Manage managers (`company_manager:write`) |

        '
      operationId: post_v1_company-managers
      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: 'Complementary action(s) to perform when creating a company manager:


          - `no_invite` skips the email invitation step

          '
        example: no_invite
        in: query
        name: actions
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyManagerParams'
        description: Company Manager params
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyManagerData'
          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:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - company_manager:write
        - company_admin
        - all:write
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - company_manager:write
        - company_admin
        - all:write
      summary: Create and invite a Company Manager
      tags:
      - Companies
  /v1/company-departments:
    get:
      callbacks: {}
      deprecated: false
      description: 'Lists all departments for the authorized company specified in the request.



        ## Scopes


        | Category | Read only Scope | Write only Scope (read access implicit) |

        |---|---|---|

        | Manage company resources (`company_admin`) | View departments (`company_department:read`) | Manage departments (`company_department:write`) |

        '
      operationId: get_v1_company-departments
      parameters:
      - description: Company ID
        example: d2091b1e-b1a4-437a-91ea-2809ffbb6d59
        in: query
        name: company_id
        required: true
        schema:
          type: string
      - description: 'Paginate option. Default: true. When true, paginates response; otherwise, does not.'
        example: false
        in: query
        name: paginate
        required: false
        schema:
          type: boolean
      - description: Starts fetching records after the given page
        example: 1
        in: query
        name: page
        required: false
        schema:
          default: 1
          minimum: 1
          type: integer
      - description: Number of items per page
        example: 20
        in: query
        name: page_size
        required: false
        schema:
          default: 20
          maximum: 100
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCompanyDepartmentsPaginatedResponse'
          description: Success
        '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:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - company_department:read
        - company_department:write
        - company_admin
        - all:write
        - all:read
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - company_department:read
        - company_department:write
        - company_admin
        - all:write
        - all:read
      summary: List Company Departments
      tags:
      - Companies
    post:
      callbacks: {}
      deprecated: false
      description: 'Creates a new department in the specified company. Department names may be non-unique and must be non-empty with no more than 255 characters (Unicode code points).


        ## Scopes


        | Category | Read only Scope | Write only Scope (read access implicit) |

        |---|---|---|

        | Manage company resources (`company_admin`) | - | Manage departments (`company_department:write`) |

        '
      operationId: post_v1_company-departments
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCompanyDepartmentParams'
        description: Create Company Department request params
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyDepartmentCreatedResponse'
          description: Created
        '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:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - company_department:write
        - company_admin
        - all:write
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - company_department:write
        - company_admin
        - all:write
      summary: Create New Department
      tags:
      - Companies
  /v1/companies/{company_id}/legal-entities/{legal_entity_id}/administrative-details:
    get:
      callbacks: {}
      deprecated: false
      description: 'Show administrative details of legal entity for the authorized company specified in the request.



        ## 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_legal-entities_legal_entity_id_administrative-details
      parameters:
      - description: Company ID
        example: d2091b1e-b1a4-437a-91ea-2809ffbb6d59
        in: path
        name: company_id
        required: true
        schema:
          $ref: '#/components/schemas/UuidSlug'
      - description: Legal entity ID
        example: d2091b1e-b1a4-437a-91ea-2809ffbb6d59
        in: path
        name: legal_entity_id
        required: true
        schema:
          $ref: '#/components/schemas/UuidSlug'
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                description: Country specific json schema driven administrative details for legal entities
                example:
                  data:
                    legal_entity_state: new
                    trade_sector: test sector
                properties:
                  data:
                    type: object
                required:
                - data
                title: ShowLegalEntityAdministrativeDetailsResponse
                type: object
          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
      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 Legal Entity Administrative details
      tags:
      - Companies
    put:
      callbacks: {}
      deprecated: false
      description: 'Update administrative details of legal entity for the authorized company specified in the request.



        ## Scopes


        | Category | Read only Scope | Write only Scope (read access implicit) |

        |---|---|---|

        

# --- truncated at 32 KB (121 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-companies-api-openapi.yml