Remote Legal Entities API
The Legal Entities API from Remote — 3 operation(s) for legal entities.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Legal Entities API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Legal Entities
paths:
/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:
- Legal Entities
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) |
|---|---|---|
| Manage companies (`company_management`) | - | Manage companies (`company:write`) |
'
operationId: put_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'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdministrativeDetailsParams'
description: Legal entity administrative details params
required: false
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
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictResponse'
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:
- OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- company:write
- company_management
- all:write
OAuth2ClientCredentials:
- https://gateway.remote.com/company.manage
- company:write
- company_management
- all:write
summary: Update Legal Entity Administrative details
tags:
- Legal Entities
/v1/companies/{company_id}/legal-entities:
get:
callbacks: {}
deprecated: false
description: 'Lists all active legal entities 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
parameters:
- description: Company ID
example: d2091b1e-b1a4-437a-91ea-2809ffbb6d59
in: path
name: company_id
required: true
schema:
$ref: '#/components/schemas/UuidSlug'
- 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/ListCompanyLegalEntitiesResponse'
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: List Company Legal Entities
tags:
- Legal Entities
/v1/companies/{company_id}/legal-entities/{legal_entity_id}/contractor-eligibility:
get:
callbacks: {}
deprecated: false
description: 'Returns which contractor products (standard, plus, cor) the legal entity is eligible to use,
and the list of country codes where COR is supported for this legal entity.
COR-supported countries exclude sanctioned and signup-prevented countries and apply entity rules (same-country, local-to-local).
When the legal entity is not COR-eligible, `cor_supported_country_codes` is an empty list.
## 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_contractor-eligibility
parameters:
- description: Company ID
in: path
name: company_id
required: true
schema:
$ref: '#/components/schemas/UuidSlug'
- description: Legal entity ID
in: path
name: legal_entity_id
required: true
schema:
$ref: '#/components/schemas/UuidSlug'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ContractorEligibilityResponse'
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 contractor eligibility and COR-supported countries for legal entity
tags:
- Legal Entities
components:
schemas:
TooManyRequestsResponse:
description: Returned when the API rate limit has been exceeded (HTTP 429). Wait before retrying. Check the `Retry-After` response header for the recommended wait time.
example:
message: Too many requests
properties:
message:
pattern: Too many requests
type: string
title: TooManyRequestsResponse
type: object
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
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
UnprocessableEntityResponse:
anyOf:
- properties:
errors:
type: object
required:
- errors
type: object
- properties:
message:
oneOf:
- type: string
- $ref: '#/components/schemas/ParameterError'
- items:
$ref: '#/components/schemas/ParameterError'
title: ParameterErrors
type: array
- $ref: '#/components/schemas/ActionError'
- items:
$ref: '#/components/schemas/ActionError'
title: ActionErrors
type: array
required:
- message
type: object
example:
errors:
some_field:
- is invalid
title: UnprocessableEntityResponse
type: object
NotFoundResponse:
description: Returned when the requested resource does not exist or is not accessible with the current authentication credentials.
example:
message: '{resource} not found'
properties:
message:
description: A message indicating which resource was not found.
pattern: Not Found
type: string
title: NotFoundResponse
type: object
ListCompanyLegalEntitiesResponse:
description: Response schema listing many legal_entities
example:
current_page: 1
legal_entities:
- country_code: USA
global_payroll_enabled: true
id: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
is_default: false
name: Remote Inc
total_count: 1
total_pages: 1
properties:
data:
properties:
current_page:
description: The current page among all of the total_pages
type: integer
legal_entities:
items:
$ref: '#/components/schemas/CompanyLegalEntity'
type: array
total_count:
description: The total number of records in the result
type: integer
total_pages:
description: The total number of pages the user can go through
type: integer
type: object
title: ListCompanyLegalEntitiesResponse
type: object
ContractorEligibilityResponse:
additionalProperties: false
example:
data:
contractor_eligibility:
cor: false
ineligibility_reasons:
cor:
- company_not_enrolled_in_product
plus: []
standard: []
plus: true
standard: true
cor_supported_country_codes:
- USA
- GBR
- DEU
properties:
data:
additionalProperties: false
properties:
contractor_eligibility:
additionalProperties: false
description: Which contractor products the legal entity can use (standard, plus, cor).
properties:
cor:
type: boolean
ineligibility_reasons:
description: Per-product lists of reasons why the legal entity is ineligible. Empty list means eligible.
properties:
cor:
items:
type: string
type: array
plus:
items:
type: string
type: array
standard:
items:
type: string
type: array
required:
- standard
- plus
- cor
type: object
plus:
type: boolean
standard:
type: boolean
required:
- standard
- plus
- cor
- ineligibility_reasons
type: object
cor_supported_country_codes:
description: ISO 3166-1 alpha-3 country codes where COR is supported for this legal entity. Empty when not COR-eligible.
items:
type: string
type: array
required:
- contractor_eligibility
- cor_supported_country_codes
type: object
required:
- data
title: ContractorEligibilityResponse
type: object
CompanyLegalEntity:
additionalProperties: false
example:
country_code: USA
global_payroll_enabled: true
id: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
is_default: false
name: Remote Inc
properties:
country_code:
description: ISO 3166-1 alpha-3 country code (e.g., 'USA', 'GBR', 'DEU')
nullable: true
type: string
global_payroll_enabled:
description: Whether Global Payroll services are enabled for this legal entity.
type: boolean
id:
description: Company slug
format: uuid
type: string
is_default:
description: Indicates if this is the default legal entity for the company
type: boolean
name:
description: The registered name of the legal entity.
type: string
required:
- id
- global_payroll_enabled
- name
title: CompanyLegalEntity
type: object
UuidSlug:
description: Identifier of the employment being terminated.
example: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
format: uuid
title: UuidSlug
type: string
AdministrativeDetailsParams:
additionalProperties: false
example:
administrative_details:
company_industry: Information Technology
entity_type: c_corp
mailing_address_same_as_filing: 'yes'
naics_code: '12345'
sic_code:
- '12345'
state_tax_account_details:
- state: AK
tax_account_number: '12345'
tax_rate: 5
- state: MD
tax_account_number: '54321'
tax_rate: 50
tax_classification: corp
product_type: peo
properties:
administrative_details:
description: 'Administrative information. As its properties may vary depending on the country,
you must query the `Show legal entity administrative details form schema` endpoint
passing the country code and `administrative_details` as path parameters.
'
type: object
product_type:
default: global_payroll
enum:
- peo
- global_payroll
- e2e_payroll
type: string
required:
- product_type
- administrative_details
title: AdministrativeDetailsParams
type: object
ConflictResponse:
description: Returned when the request conflicts with the current state of a resource (HTTP 409). For example, trying to create a resource that already exists or performing an action that requires the resource to be in a different state.
example:
message: Company needs to be in status active to manage employments
properties:
message:
description: A human-readable message describing the conflict and the expected state.
type: string
title: ConflictResponse
type: object
ActionError:
properties:
action:
description: The action that lead to the error message.
type: string
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
required:
- code
- message
- action
title: ActionError
type: object
securitySchemes:
BasicAuth:
description: 'Authenticate using the basic authentication for partners.
Use the CLIENT_ID as login and CLIENT_SECRET as password.
'
scheme: basic
type: http
ClientToken:
description: 'Authenticate a partner using only the the provided `client_token`.
This authentication method only allows accessing marketing endpoints.
'
scheme: bearer
type: http
CustomerAPIToken:
description: 'Authenticate using API Key generated by the customer in their Integration Settings page.
'
scheme: bearer
type: http
OAuth2:
description: 'Authenticate using OAuth 2.0 protocol.
'
flows:
authorizationCode:
authorizationUrl: /auth/oauth2/authorize
scopes:
company_department:read: company_department:read
webhook:write: webhook:write
magic_link:write: magic_link:write
offboarding:write: offboarding:write
custom_field:write: custom_field:write
address:write: address:write
expense:read: expense:read
employment:write: employment:write
identity_verification:write: identity_verification:write
timesheet:write: timesheet:write
travel_letter:write: travel_letter:write
incentive:read: incentive:read
personal_detail:read: personal_detail:read
invoices:write: invoices:write
work_authorization:write: work_authorization:write
timeoff:write: timeoff:write
company_structure:read: company_structure:read
benefit_renewal:write: benefit_renewal:write
benefit_offer:read: benefit_offer:read
employment_documents: employment_documents
onboarding:write: onboarding:write
payroll_run:read: payroll_run:read
risk_reserve:write: risk_reserve:write
invoices: invoices
resignation_letter:read: resignation_letter:read
resignation:read: resignation:read
convert_currency:read: convert_currency:read
employments: employments
probation_document:read: probation_document:read
company_admin: company_admin
payroll: payroll
help_center_article:read: help_center_article:read
timesheet:read: timesheet:read
custom_field_value:write: custom_field_value:write
company_currencies:read: company_currencies:read
payslip:read: payslip:read
pay_item:write: pay_item:write
resignation:write: resignation:write
custom_field:read: custom_field:read
payroll_calendar:read: payroll_calendar:read
contract_amendment:write: contract_amendment:write
offboarding:read: offboarding:read
timeoff:read: timeoff:read
probation_document:write: probation_document:write
country:read: country:read
webhook:read: webhook:read
company_department:write: company_department:write
company_manager:read: company_manager:read
pay_item:read: pay_item:read
contract_amendment:read: contract_amendment:read
company:read: company:read
sso_configuration:write: sso_configuration:write
benefit_offer:write: benefit_offer:write
contract_eligibility:write: contract_eligibility:write
benefit_renewal:read: benefit_renewal:read
background_check:read: background_check:read
custom_field_value:read: custom_field_value:read
expense:write: expense:write
identity_verification:read: identity_verification:read
address:read: address:read
document:write: document:write
time_and_attendance: time_and_attendance
employment_payments: employment_payments
form:read: form:read
work_authorization:read: work_authorization:read
invoices:read: invoices:read
incentive:write: incentive:write
employment:read: employment:read
contract:read: contract:read
company_manager:write: company_manager:write
travel_letter:read: travel_letter:read
document:read: document:read
sso_configuration:read: sso_configuration:read
tokenUrl: /auth/oauth2/token
clientCredentials:
scopes:
company:read: company:read
company:write: company:write
company_admin: company_admin
company_management: company_management
convert_currency:read: convert_currency:read
country:read: country:read
employment_documents: employment_documents
employment_payments: employment_payments
employments: employments
help_center_article:read: help_center_article:read
invoices: invoices
payroll: payroll
payroll_calendar:read: payroll_calendar:read
pricing_plan:read: pricing_plan:read
pricing_plan:write: pricing_plan:write
time_and_attendance: time_and_attendance
webhook:read: webhook:read
webhook:write: webhook:write
tokenUrl: /auth/oauth2/token
type: oauth2
OAuth2Assertion:
description: 'Authenticate as the employee using the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant in the OAuth2 protocol.
'
flows:
clientCredentials:
scopes:
address:read: address:read
address:write: address:write
bank_account:read: bank_account:read
bank_account:write: bank_account:write
document:read: document:read
document:write: document:write
emergency_contact:read: emergency_contact:read
emergency_contact:write: emergency_contact:write
employment_documents: employment_documents
employment_payments: employment_payments
employments: employments
expense:read: expense:read
incentive:read: incentive:read
payroll: payroll
payslip:read: payslip:read
personal_detail:read: personal_detail:read
personal_detail:write: personal_detail:write
time_and_attendance: time_and_attendance
timeoff:read: timeoff:read
timeoff:write: timeoff:write
timesheet:read: timesheet:read
tokenUrl: /auth/oauth2/token
x-assertionType: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
type: oauth2
OAuth2AuthorizationCode:
description: 'Authenticate as the token authorizer using `authorization_code` / `refresh_token` grants in the OAuth 2.0 protocol.
'
flows:
authorizationCode:
authorizationUrl: /auth/oauth2/authorize
refreshUrl: /auth/oauth2/token
scopes:
company_department:read: company_department:read
webhook:write: webhook:write
magic_link:write: magic_link:write
offboarding:write: offboarding:write
custom_field:write: custom_field:write
address:write: address:write
expense:read: expense:read
employment:write: employment:write
identity_verification:write: identity_verification:write
timesheet:write: timesheet:write
travel_letter:write: travel_letter:write
incentive:read: incentive:read
personal_detail:read: personal_detail:read
invoices:write: invoices:write
work_authorization:write: work_authorization:write
timeoff:write: timeoff:write
company_structure:read: company_structure:read
benefit_renewal:write: benefit_renewal:write
benefit_offer:read: benefit_offer:read
employment_documents: employment_documents
onboarding:write: onboarding:write
payroll_run:read: payroll_run:read
risk_reserve:write: risk_reserve:write
invoices: invoices
resignation_letter:read: resignation_letter:read
resignation:read: resignation:read
convert_currency:read: convert_currency:read
employments: employments
probation_document:read: probation_document:read
company_admin: company_admin
payroll: payroll
help_center_article:read: help_center_article:read
timesheet:read: timesheet:read
custom_field_value:write: custom_field_value:write
company_currencies:read: company_currencies:read
payslip:read: payslip:read
pay_item:write: pay_item:write
resignation:write: resignation:write
custom_field:read: custom_field:read
payroll_calendar:read: payroll_calendar:read
contract_amendment:write: contract_amendment:write
offboarding:read: offboarding:read
timeoff:read: timeoff:read
probation_document:write: probation_document:write
country:read: country:read
webhook:read: webhook:read
company_department:write: company_department:write
company_manager:read: company_manager:read
pay_item:read: pay_item:read
contract_amendment:read: contract_amendment:read
company:read: company:read
sso_configuration:write: sso_configuration:write
benefit_offer:write: benefit_offer:write
contract_eligibility:write: contract_eligibility:write
benefit_renewal:read: benefit_renewal:read
background_check:read: background_check:read
custom_field_value:read: custom_field_value:read
expense:write: expense:write
identity_verification:read: identity_verification:read
address:read: address:read
document:write: document:write
time_and_attendance: time_and_attendance
employment_payments: employment_payments
form:read: form:read
work_authorization:read: work_authorization:read
invoices:read: invoices:read
incentive:write: incentive:write
employment:read: employment:read
contract:read: contract:read
company_manager:write: company_manager:write
travel_letter:read: travel_letter:read
document:read: document:read
sso_configuration:read: sso_configuration:read
tokenUrl: /auth/oauth2/token
type: oauth2
OAuth2ClientCredentials:
description: 'Authenticate using `client_credentials` grant in the OAuth 2.0 protocol.
'
flows:
clientCredentials:
scopes:
company:read: company:read
company:write: company:write
company_admin: company_admin
company_management: company_management
convert_currency:read: convert_currency:read
country:read: country:read
employment_documents: employment_documents
employment_payments: employment_payments
employments: employments
help_center_article:read: help_center_article:read
invoices: invoices
payroll: payroll
payroll_calendar:read: payroll_calendar:read
pricing_plan:read: pricing_plan:read
pricing_plan:write: pricing_plan:write
time_and_attendance: time_and_attendance
webhook:read: webhook:read
webhook:write: webhook:write
tokenUrl: /auth/oauth2/token
type: oauth2