Remote Companies API

openapi: 3.2.0
info:
  title: Remote Companies API
  description: 'Create and manage companies on the Remote.com platform. Customers and

    partners use this API to onboard new companies, retrieve compliance

    profiles, manage company managers and departments, configure SSO, and

    issue magic links for passwordless authentication.


    The Companies API is the entry point for every Remote integration. A

    company-scoped access token is required for nearly every other API call

    in the Remote ecosystem.'
  version: '2026-05-22'
  contact:
    name: Remote API Support
    url: https://support.remote.com/
  termsOfService: https://remote.com/legal/terms
  license:
    name: Remote API Terms
    url: https://developer.remote.com/docs/api-terms
  x-logo:
    url: https://remote.com/favicon.ico
servers:
- url: https://gateway.remote.com/v1
  description: Production
- url: https://gateway.remote-sandbox.com/v1
  description: Sandbox
security:
- BearerAuth: []
tags:
- name: Companies
  description: Create, retrieve, and update company records
paths:
  /companies:
    get:
      summary: List Companies
      description: List companies accessible to the current partner or customer access token.
      operationId: listCompanies
      tags:
      - Companies
      parameters:
      - $ref: '#/components/parameters/PageQuery'
      - $ref: '#/components/parameters/PageSizeQuery'
      responses:
        '200':
          description: A page of companies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      summary: Create A Company
      description: 'Create a new company on Remote. Returns the company resource together

        with a company-scoped access token that the partner/customer may use

        to call subsequent endpoints on the new company''s behalf.'
      operationId: createCompany
      tags:
      - Companies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyCreateRequest'
      responses:
        '201':
          description: Company created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyCreateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /companies/{company_id}:
    parameters:
    - $ref: '#/components/parameters/CompanyIdPath'
    get:
      summary: Show A Company
      description: Retrieve a company by id.
      operationId: showCompany
      tags:
      - Companies
      responses:
        '200':
          description: Company record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyEnvelope'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      summary: Update A Company
      description: Update fields on an existing company.
      operationId: updateCompany
      tags:
      - Companies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyUpdateRequest'
      responses:
        '200':
          description: Company updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /companies/{company_id}/legal_entities:
    parameters:
    - $ref: '#/components/parameters/CompanyIdPath'
    get:
      summary: List Company Legal Entities
      description: List the legal entities under which the company hires.
      operationId: listCompanyLegalEntities
      tags:
      - Companies
      responses:
        '200':
          description: Legal entities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegalEntityList'
  /forms/{form_type}:
    parameters:
    - name: form_type
      in: path
      required: true
      schema:
        type: string
        enum:
        - company
        - employment
        - contract_amendment
        - benefit_offer
        - benefit_renewal_request
        - offboarding
        - expense
    get:
      summary: Show A JSON Schema Form
      description: Returns the JSON Schema form definition used by Remote to collect localized data for the given resource type.
      operationId: showSchemaForm
      tags:
      - Companies
      responses:
        '200':
          description: JSON Schema form.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
components:
  schemas:
    CompanyEnvelope:
      type: object
      properties:
        data:
          type: object
          properties:
            company:
              $ref: '#/components/schemas/Company'
    Address:
      type: object
      properties:
        address:
          type: string
        address_line_2:
          type: string
        city:
          type: string
        country_code:
          type: string
          description: ISO 3166-1 alpha-3 country code.
        local_details:
          type: object
          additionalProperties: true
        postal_code:
          type: string
    LegalEntity:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        country_code:
          type: string
        type:
          type: string
          enum:
          - remote_entity
          - partner_entity
          - customer_entity
    CompanyList:
      type: object
      properties:
        data:
          type: object
          properties:
            companies:
              type: array
              items:
                $ref: '#/components/schemas/Company'
            current_page:
              type: integer
            total_count:
              type: integer
            total_pages:
              type: integer
    CompanyUpdateRequest:
      type: object
      properties:
        name:
          type: string
        external_id:
          type: string
        address:
          $ref: '#/components/schemas/Address'
        tax_number:
          type: string
    CompanyCreateRequest:
      type: object
      required:
      - name
      - company_owner_email
      properties:
        name:
          type: string
        company_owner_email:
          type: string
          format: email
        company_owner_name:
          type: string
        desired_currency:
          type: string
          default: USD
        external_id:
          type: string
        terms_of_service_accepted_at:
          type: string
          format: date-time
    CompanyCreateResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            company:
              $ref: '#/components/schemas/Company'
            access_token:
              type: string
              description: Company-scoped access token.
            refresh_token:
              type: string
            expires_in:
              type: integer
    ErrorResponse:
      type: object
      required:
      - errors
      properties:
        errors:
          type: object
          additionalProperties: true
        message:
          type: string
    LegalEntityList:
      type: object
      properties:
        data:
          type: object
          properties:
            legal_entities:
              type: array
              items:
                $ref: '#/components/schemas/LegalEntity'
    Company:
      type: object
      required:
      - id
      - name
      - status
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        external_id:
          type: string
          nullable: true
        status:
          type: string
          enum:
          - created
          - draft
          - profile_completed
          - activation_pending
          - activated
          - archived
        company_owner_user_id:
          type: string
          format: uuid
        primary_billing_contact:
          type: string
          nullable: true
        bank_account_currency_code:
          type: string
        tax_number:
          type: string
          nullable: true
        address:
          $ref: '#/components/schemas/Address'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  parameters:
    CompanyIdPath:
      name: company_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    PageSizeQuery:
      name: page_size
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    PageQuery:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Too Many Requests
      headers:
        x-ratelimit-count:
          schema:
            type: integer
          description: Requests made in the current 60-second window.
        x-ratelimit-remaining:
          schema:
            type: integer
          description: Requests remaining in the current window.
        x-ratelimit-reset:
          schema:
            type: integer
          description: Milliseconds until the rate limit resets.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Company-scoped or partner-scoped OAuth 2.0 access token.