Remote Basic Information API
The Basic Information API from Remote — 2 operation(s) for basic information.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Basic Information API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Basic Information
paths:
/v2/employments/{employment_id}/basic-information:
get:
callbacks: {}
deprecated: false
description: 'Returns the employment''s basic information.
This endpoint requires and returns country-specific data. The exact required and returned fields will
vary depending on which country the employment is in. To see the list of parameters for each country,
see the **Show form schema** endpoint under the [Countries](#tag/Countries) category.
Please note that the compliance requirements for each country are subject to change according to local
laws. Given its continual updates, using Remote''s [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) should be considered in order to avoid
compliance issues and to have the latest version of a country requirements.
If you are using this endpoint to build an integration, make sure you are dynamically collecting or
displaying the latest parameters for each country by querying the _"Show form schema"_ endpoint.
For more information on JSON Schemas, see the **How JSON Schemas work** documentation.
To learn how you can dynamically generate forms to display in your UI, see the documentation for
the [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) tool.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | View employments (`employment:read`) | Manage employments (`employment:write`) |
'
operationId: get_v2_employments_employment_id_basic-information
parameters:
- description: Employment ID
example: 93t3j-employment-id-9suej43
in: path
name: employment_id
required: true
schema:
type: string
- description: Version of the employment_basic_information form schema
example: 1
in: query
name: employment_basic_information_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/EmploymentDetailsOnlyResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
'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: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- employment:read
- employment:write
- employments
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- employment:read
- employment:write
- employments
- all:write
- all:read
summary: Get basic information
tags:
- Basic Information
put:
callbacks: {}
deprecated: false
description: 'Updates employment''s basic information.
Supported employment statuses: `created`, `job_title_review`, `created_reserve_paid`, `created_awaiting_reserve`.
This endpoint requires and returns country-specific data. The exact required and returned fields will
vary depending on which country the employment is in. To see the list of parameters for each country,
see the **Show form schema** endpoint under the [Countries](#tag/Countries) category.
Please note that the compliance requirements for each country are subject to change according to local
laws. Given its continual updates, using Remote''s [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) should be considered in order to avoid
compliance issues and to have the latest version of a country requirements.
If you are using this endpoint to build an integration, make sure you are dynamically collecting or
displaying the latest parameters for each country by querying the _"Show form schema"_ endpoint.
For more information on JSON Schemas, see the **How JSON Schemas work** documentation.
To learn how you can dynamically generate forms to display in your UI, see the documentation for
the [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) tool.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | - | Manage employments (`employment:write`) |
'
operationId: put_v2_employments_employment_id_basic-information
parameters:
- description: Employment ID
example: 93t3j-employment-id-9suej43
in: path
name: employment_id
required: true
schema:
type: string
- description: Version of the employment_basic_information form schema
example: 1
in: query
name: employment_basic_information_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
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmploymentBasicInformationParams'
description: Employment basic information params
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmploymentDetailsOnlyResponse'
description: Success
'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/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:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- employment:write
- employments
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- employment:write
- employments
- all:write
summary: Update basic information
tags:
- Basic Information
/v1/employments/{employment_id}/basic-information:
put:
callbacks: {}
deprecated: false
description: 'Updates employment''s basic information.
Supported employment statuses: `created`, `job_title_review`, `created_reserve_paid`, `created_awaiting_reserve`.
This endpoint requires and returns country-specific data. The exact required and returned fields will
vary depending on which country the employment is in. To see the list of parameters for each country,
see the **Show form schema** endpoint under the [Countries](#tag/Countries) category.
Please note that the compliance requirements for each country are subject to change according to local
laws. Given its continual updates, using Remote''s [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) should be considered in order to avoid
compliance issues and to have the latest version of a country requirements.
If you are using this endpoint to build an integration, make sure you are dynamically collecting or
displaying the latest parameters for each country by querying the _"Show form schema"_ endpoint.
For more information on JSON Schemas, see the **How JSON Schemas work** documentation.
To learn how you can dynamically generate forms to display in your UI, see the documentation for
the [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) tool.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | - | Manage employments (`employment:write`) |
'
operationId: put_v1_employments_employment_id_basic-information
parameters:
- description: Employment ID
example: 93t3j-employment-id-9suej43
in: path
name: employment_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmploymentBasicInformationParams'
description: Employment basic information params
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmploymentResponse'
description: Success
'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/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:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- employment:write
- employments
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- employment:write
- employments
- all:write
summary: Update basic information
tags:
- Basic Information
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
UserStatus:
description: 'The status of the user account associated with this employment.
- `active`: The user account is active and the user can log in.
- `created`: The user account has been created but not yet activated.
- `initiated`: The user has been invited but has not completed registration.
- `cancelled`: The user account was cancelled before activation.
- `inactive`: The user account has been deactivated (e.g., after offboarding).
- `deleted`: The user account has been deleted.
'
enum:
- active
- created
- initiated
- cancelled
- inactive
- deleted
example: active
title: UserStatus
type: string
ProvisionalStartDate:
description: 'Indicates the expected start date of the employee or contractor.
Required for employees, but optional for contractors. Date format is in ISO8601 without the time component.
See the **Date and Time Format** documentation for more details on how the Remote API works with dates.
'
example: '2022-03-21'
format: date
title: ProvisionalStartDate
type: string
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
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
BadRequestResponse:
description: Returned when the request is malformed or contains invalid parameters. The message may be a simple string or a structured object with a code and detailed message.
example:
message: invalid {resource}
oneOf:
- properties:
message:
description: A human-readable error message describing what was wrong with the request.
type: string
required:
- message
type: object
- properties:
message:
properties:
code:
type: string
message:
type: string
required:
- code
- message
type: object
type: object
title: BadRequestResponse
type: object
Employment:
description: Complete information of an employment, including all onboarding task statuses, country-specific form data (address, contract, administrative, etc.), and contractor-specific settings where applicable.
example:
personal_details: {}
manager_email: john.doe@company.com
provisional_start_date: '2021-07-03'
address_details: {}
pricing_plan_details:
frequency: annually
full_name: Jane Smith
type: employee
employment_lifecycle_stage: employee_self_enrollment
administrative_details: {}
company_id: e31adae1-company-id-af5fba7dd803
work_address_details: {}
bill_to_legal_entity_id: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
work_email: jane.smith@company.com
status: created
updated_at: '2021-07-15T18:18:17Z'
basic_information: {}
job_title: Engineer
id: 20a72f86-employment-id-9e4942a902ff
manager: John Doe
login_email: jane@smith.com
employment_model: eor
personal_email: jane@smith.com
country:
alpha_2_code: PT
code: PRT
contractor_products_available:
- standard
- plus
- cor
country_subdivisions:
- code: PT-06
name: Coimbra
subdivision_type: District
- code: PT-11
name: Lisboa
subdivision_type: District
employment_agreement_preview_available: true
eor_onboarding: true
locked_benefits: after_first_hire
name: Portugal
region: Europe
subregion: Southern Europe
supported_json_schemas:
- additional_documents
- address_details
- administrative_details
- employment-basic-information
- bank_account_details
- contract_details
- emergency_contact
user_status: active
bank_account_details: []
files: []
engaged_by_legal_entity_id: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
billing_address_details: {}
onboarding_tasks:
address_details:
description: Primary residence.
status: completed
administrative_details:
description: Information we need for tax purposes.
status: completed
bank_account_details:
description: Bank account used for receiving salary payments.
status: completed
billing_address_details:
description: Address associated with the employee's bank account.
status: completed
contract_details:
description: Employee-specific details for their employment agreement.
status: completed
emergency_contact_details:
description: Who should be called in an emergency.
status: completed
employment_document_details:
description: We need some additional documents.
status: pending
personal_details:
description: Personal details, such as name and date of birth.
status: completed
pricing_plan_details:
description: How often Remote will bill employers for management fees.
status: completed
contract_details: {}
emergency_contact_details: {}
eligible_for_onboarding_cancellation: true
manager_employment_id: 20a72f86-employment-id-9e4942a902ff
created_at: '2021-11-11T18:44:39'
properties:
personal_details:
description: Personal details information. Its properties may vary depending on the country.
type: object
short_id:
$ref: '#/components/schemas/ShortId'
department:
description: Name of related department, if any. Otherwise, null.
nullable: true
type: string
manager_email:
description: The email address of the employee's manager. Null if no manager is assigned.
nullable: true
type: string
provisional_start_date:
$ref: '#/components/schemas/ProvisionalStartDate'
address_details:
description: Home address information. Its properties may vary depending on the country.
type: object
pricing_plan_details:
$ref: '#/components/schemas/PricingPlanDetails'
full_name:
description: The employee's full name.
type: string
type:
description: 'For the employment types `contractor`, `global_payroll_employee` and `direct_employee`, only [List employments](#operation/get_index_employment) and
[Show employment](#operation/get_show_employment) operations are available.
'
enum:
- employee
- contractor
- direct_employee
- global_payroll_employee
type: string
contractor_settings:
description: Contractor-specific settings. Only present for contractor employments.
nullable: true
properties:
requires_work_confirmation:
description: Whether the contractor requires work confirmation before submitting invoices.
type: boolean
type: object
employment_lifecycle_stage:
$ref: '#/components/schemas/EmploymentLifecycleStage'
administrative_details:
description: Administrative information. Its properties may vary depending on the country.
type: object
contractor_type:
description: Type of contractor product. Only present for contractor employments. 'standard' for Contractor Standard, 'cor' for Contractor of Record, 'plus' for Contractor Plus.
enum:
- standard
- cor
- plus
nullable: true
type: string
contractor_rate:
description: Contractor compensation rate details. Only present for contractor employments when rate is configured.
nullable: true
properties:
amount:
properties:
amount:
description: Rate amount as decimal
type: number
currency:
properties:
code:
description: Currency code (e.g., USD, EUR)
type: string
type: object
type: object
pay_frequency:
description: Payment frequency cadence
enum:
- weekly
- bi_weekly
- semi_monthly
- monthly
nullable: true
type: string
slug:
description: Unique identifier for the contractor rate
type: string
type:
description: Rate type indicating billing frequency
enum:
- hourly
- daily
- weekly
- monthly
- one_off
type: string
type: object
company_id:
description: The unique identifier (UUID) of the company this employment belongs to.
type: string
expiration_date:
description: 'The planned service end date for contractor of record (COR) employments.
For signed COR contractors, this date is stored on the contract record (not in `contract_details`).
It is `null` for employee employments or unsigned contractor agreements.
Date format is ISO 8601 without the time component (e.g. "2024-12-31").
'
format: date
nullable: true
type: string
work_address_details:
description: Work address information. Its properties may vary depending on the country.
type: object
bill_to_legal_entity_id:
description: The unique identifier (UUID) of the legal entity that is billed for this employment.
example: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
format: uuid
nullable: true
title: BillToLegalEntityID
type: string
work_email:
description: The employee's work email address, typically provided by the employer.
type: string
status:
$ref: '#/components/schemas/EmploymentStatus'
updated_at:
description: The timestamp when this employment record was last updated.
format: date-time
type: string
basic_information:
description: 'Employment basic information. Its properties may vary depending on the country.
'
type: object
job_title:
description: The employee's job title. May be null if not yet set.
nullable: true
type: string
id:
description: The unique identifier (UUID) of the employment.
type: string
probation_period_end_date:
description: The date when the employee's probation period ends, if applicable.
format: date
type: string
department_id:
description: Unique ID of related department, if any. Otherwise, null.
example: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
format: uuid
nullable: true
title: DepartmentID
type: string
manager:
description: The full name of the employee's manager.
type: string
login_email:
description: The email address the employee uses to log in to the Remote platform.
type: string
external_id:
description: A unique reference code for the employment record in a non-Remote system. While uniqueness is recommended, it is not strictly enforced within Remote's system.
type: string
employment_model:
description: 'For the employment models `peo` and `global_payroll`, only [List employments](#operation/get_index_employment) and
[Show employment](#operation/get_show_employment) operations are available.
'
enum:
- global_payroll
- peo
- eor
nullable: true
type: string
personal_email:
description: The employee's personal email address, used for account-related communications.
type: string
country:
$ref: '#/components/schemas/NullableCountry'
user_status:
$ref: '#/components/schemas/UserStatus'
seniority_date:
$ref: '#/components/schemas/EmploymentSeniorityDate'
bank_account_details:
items:
description: List of bank account information. Its properties may vary depending on the country.
type: object
type: array
files:
description: Documents associated with this employment (e.g., contracts, tax forms, identity documents).
items:
$ref: '#/components/schemas/File'
type: array
active_contract_id:
description: The unique identifier (UUID) of the currently active contract for this employment.
type: string
engaged_by_legal_entity_id:
description: The unique identifier (UUID) of the legal entity that engaged this employment.
example: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
format: uuid
nullable: true
title: EngagedByLegalEntityID
type: string
billing_address_details:
description: Billing address information. Its properties may vary depending on the country.
type: object
onboarding_tasks:
$ref: '#/components/schemas/OnboardingTasks'
contract_details:
description: Contract information. Its properties may vary depending on the country.
type: object
emergency_contact_details:
description: Emergency contact information. Its properties may vary depending on the country.
type: object
eligible_for_onboarding_cancellation:
description: Whether this employment can still be cancelled during the onboarding process. Once the employment is active, this will be false.
type: boolean
manager_employment_id:
description: The employment ID of the employee's manager on Remote, if the manager is also managed through Remote. Null otherwise.
nullable: true
type: string
created_at:
description: The timestamp when this employment record was created.
type: string
required:
- address_details
- administrative_details
- bank_account_details
- billing_address_details
- company_id
- contract_details
- country
- created_at
- emergency_contact_details
- files
- full_name
- id
- type
- employment_model
- work_address_details
- job_title
- manager_email
- manager_employment_id
- onboarding_tasks
- personal_details
- personal_email
- login_email
- pricing_plan_details
- status
- employment_lifecycle_stage
- updated_at
- work_email
- eligible_for_onboarding_cancellation
title: Employment
type: object
ShortId:
description: Unique short identifier for the employment, automatically generated and visible in select areas of the Remote platform. Not intended as a replacement for the employment `id` field.
example: WN1IZT
title: ShortId
type: string
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
ForbiddenResponse:
description: Returned when the authenticated user or token does not have permission to perform the requested action. Check that the token has the required OAuth2 scopes and that the user has the necessary role.
example:
message: Forbidden
properties:
message:
pattern: Forbidden
type: string
required:
- message
title: ForbiddenResponse
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
File:
additionalProperties: false
description: A file associated with an employment, such as a contract, tax form, or identity document.
example:
id: 9880b711-file-id-ecf8f551bd78
inserted_at: '2021-07-15T18:18:17Z'
name: id.pdf
sub_type: personal_id
type: id
properties:
id:
description: The unique identifier (UUID) of the file.
type: string
inserted_at:
$ref: '#/components/schemas/DateTimeIso8601'
name:
description: The file name including extension (e.g., "id.pdf", "contract.pdf").
type: string
sub_type:
description: A more specific classification of the file within its type (e.g., "personal_id" within type "id", or "ir_35" within type "contract"). Null if no sub-type applies.
nullable: true
type: string
type:
description: The broad category of the file (e.g., "id", "contract", "tax_form").
type: string
required:
- id
- inserted_at
- name
- type
title: File
type: object
CountrySubdivision:
description: A subdivision of a supported country on Remote
example:
code: PT-11
name: Lisboa
s
# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-basic-information-api-openapi.yml