Remote Employments API
The Employments API from Remote — 53 operation(s) for employments.
Remote Employments API is one of 101 APIs that Remote publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
Tagged areas include Employments. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and an API reference.
This API exposes 66 operations across 53 paths, and defines 111 schemas. It is described by OpenAPI 3.0.0, at version 0.1.0.
Requests are made against 2 base URLs: https://gateway.remote.com/, https://gateway.remote-sandbox.com/.
66 operations
53 paths
111 schemas
1 DELETE24 GET2 PATCH18 POST21 PUT
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 7
Remote Employments API declares
7 security schemes
for authenticating requests.
It accepts HTTP basic authentication (BasicAuth).
It accepts HTTP bearer tokens (ClientToken).
It accepts HTTP bearer tokens (CustomerAPIToken).
It supports OAuth 2.0 (OAuth2) using the authorizationCode and clientCredentials flows, exposing 77 scopes.
It supports OAuth 2.0 (OAuth2Assertion) using the clientCredentials flow, exposing 21 scopes.
It supports OAuth 2.0 (OAuth2AuthorizationCode) using the authorizationCode flow, exposing 73 scopes.
It supports OAuth 2.0 (OAuth2ClientCredentials) using the clientCredentials flow, exposing 18 scopes.
By default, every request must be authenticated.
BasicAuth— Authenticate using the basic authentication for partners. Use the CLIENTID as login and CLIENTSECRET as password.ClientToken— Authenticate a partner using only the the provided clienttoken. This authentication method only allows accessing marketing endpoints.CustomerAPIToken— Authenticate using API Key generated by the customer in their Integration Settings page.OAuth2— Authenticate using OAuth 2.0 protocol.OAuth2Assertion— Authenticate as the employee using the urn:ietf:params:oauth:grant-type:jwt-bearer grant in the OAuth2 protocol.OAuth2AuthorizationCode— Authenticate as the token authorizer using authorizationcode / refreshtoken grants in the OAuth 2.0 protocol.OAuth2ClientCredentials— Authenticate using clientcredentials grant in the OAuth 2.0 protocol.
Paths & Operations 66
Across 53 paths, the API surfaces 66 operations — 1 DELETE, 24 GET, 2 PATCH, 18 POST, 21 PUT. Each is listed below with its method, path, parameters, and response codes.
Employments 66
PUT
/v2/employments/{employment_id}/pricing-plan-details
Update pricing plan details
POST
/v1/cancel-onboarding/{employment_id}
Cancel onboarding
PUT
/v2/employments/{employment_id}/address-details
Update address details
GET
/v1/employments
List employments
POST
/v1/employments
Create employment
GET
/v1/employee/bank-account
Show employee bank account
PUT
/v1/employee/bank-account
Update employee bank account
GET
/v2/employments/{employment_id}/engagement-agreement-details
Get engagement agreement details
POST
/v2/employments/{employment_id}/engagement-agreement-details
Upsert engagement agreement details
GET
/v1/employee/documents/{id}
Download a document for the employee
GET
/v1/identity-verification/{employment_id}
Get Employment Profile
GET
/v1/employments/{employment_id}/job
Show employment job
DELETE
/v1/onboarding/employments/{employment_id}/pre-onboarding-requirements/{requirement_slug}/acknowledge
Remove a pre-onboarding acknowledgement
POST
/v1/onboarding/employments/{employment_id}/pre-onboarding-requirements/{requirement_slug}/acknowledge
Acknowledge a pre-onboarding acknowledgement requirement
GET
/v1/employments/{employment_id}/background-checks/{background_check_id}
Show Background Check
GET
/v1/onboarding/employments/{employment_id}/pre-onboarding-document-requirementsdeprecated
List pre-onboarding document requirements for an employment
GET
/v1/employments/{employment_id}/cost-center-allocations
List cost center allocations for an employment
PUT
/v2/employments/{employment_id}/federal-taxes
Update federal taxes
POST
/v1/risk-reserve
Create risk reserve
POST
/v1/employments/{employment_id}/risk-reserve-proof-of-payments
Submit risk reserve proof of payment
GET
/v1/employee/address
Show employee address
PUT
/v1/employee/address
Update employee address
GET
/v2/employments/{employment_id}/basic-information
Get basic information
PUT
/v2/employments/{employment_id}/basic-information
Update basic information
PUT
/v1/employments/{employment_id}/federal-taxes
Update federal taxes
POST
/v1/onboarding/employments/{employment_id}/pre-onboarding-requirements/{requirement_slug}/documents
Find or create a document for a pre-onboarding requirement
GET
/v1/files/{id}
Download file
POST
/v1/identity-verification/{employment_id}/decline
Decline Identity Verification
GET
/v1/onboarding/employments/{employment_id}/pre-onboarding-documents/{id}
Retrieve a pre-onboarding document with its rendered PDF content
PUT
/v1/employee/federal-taxes
Submit employee federal taxes
PUT
/v2/employments/{employment_id}/emergency-contact
Update emergency contact
PUT
/v1/employments/{employment_id}/basic-information
Update basic information
GET
/v1/employments/{employment_id}
Show employment
PATCH
/v1/employments/{employment_id}
Update employment
PUT
/v1/employments/{employment_id}
Update employment
GET
/v1/company/{company_id}/cost-center-allocations
List cost center allocations for a company
GET
/v1/bulk-employment-jobs/{job_id}/rows
List bulk employment rows
GET
/v1/employee/emergency-contact
Show employee emergency contact
PUT
/v1/employee/emergency-contact
Update employee emergency contact
PUT
/v2/employments/{employment_id}/contract-details
Update contract details
POST
/v1/readydeprecated
Complete onboarding
POST
/v1/employments/{employment_id}/contract-origin
Set contract origin for a contractor employment
GET
/v1/employee/personal-details
Show employee personal details
PUT
/v1/employee/personal-details
Update employee personal details
GET
/v1/employments/{employment_id}/files
List employment files
POST
/v1/documents
Upload file
POST
/v1/employments/{employment_id}/invite
Invite employment
PUT
/v2/employments/{employment_id}/bank-account-details
Update bank account details
GET
/v1/employments/{employment_id}/onboarding-steps
Show onboarding steps for an employment
GET
/v1/bulk-employment-jobs/{job_id}
Show bulk employment job
PATCH
/v2/employments/{employment_id}
Update employment
PUT
/v2/employments/{employment_id}
Update employment
PUT
/v2/employments/{employment_id}/personal-details
Update personal details
POST
/v1/onboarding/employments/{employment_id}/pre-onboarding-documentsdeprecated
Find or create a pre-onboarding document for an employment
PUT
/v2/employments/{employment_id}/billing-address-details
Update billing address details
POST
/v1/bulk-employment-jobs
Create bulk employment job
PUT
/v1/employments/{employment_id}/personal-details
Update personal details
POST
/v1/onboarding/employments/{employment_id}/pre-onboarding-documents/{id}/sign
Sign a pre-onboarding document
PUT
/v1/employee/state-taxes/{jurisdiction}
Submit employee state taxes
GET
/v1/employments/{employment_id}/engagement-agreement-details
Get engagement agreement details
POST
/v1/employments/{employment_id}/engagement-agreement-details
Upsert engagement agreement details
PUT
/v2/employments/{employment_id}/administrative-details
Update administrative details
GET
/v1/employee/documents
Indexes all the documents for the employee
POST
/v1/employee/documents
Upload employee file
POST
/v1/identity-verification/{employment_id}/verify
Verify Employment Identity
GET
/v1/onboarding/employments/{employment_id}/pre-onboarding-requirements
List pre-onboarding requirements for an employment
Schemas 111
The contract defines 111 schemas that model the data the API accepts and returns. The most detailed are Employment (45 properties), BulkEmploymentImportJob (17 properties), EmploymentFullParams (17 properties), MinimalEmployment (16 properties). Each schema is shown below with its type and property counts.
IdentityVerification
object
Identity Verification
4 properties
4 required
BackgroundChecks.BackgroundCheckResponse
object
Background Check Response
1 property
1 required
ParameterError
object
3 properties
3 required
ImportJobRowsResponse
object
1 property
1 required
IdentityVerificationResponse
object
Identity Verification response
1 property
1 required
ListFilesResponse
object
Response schema listing many files
1 property
EmploymentDocument
object
Employment document file
Job
object
A job assigned to an employment, including its classification within the company's job architecture (family, sub-family, career track, level) and any custom fi…
10 properties
3 required
ConflictResponse
object
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…
1 property
SuccessResponse
object
A generic success response returned by operations that don't produce a specific resource (e.g., updates, deletes).
1 property
1 required
EmploymentContractDetailsParams
object
Employment contract details params.
1 property
1 required
EmploymentBillingAddressDetailsParams
object
Employment billing address details params.
1 property
1 required
RiskReserveProofOfPaymentResponse
object
1 property
Signatory
object
A signatory on a contract document. For company and employee signatories, userid is provided. For other signatory types, userid is null.
9 properties
2 required
CompleteOnboarding
object
Parameters to complete onboarding
1 property
ListCostCenterAllocationsResponse
object
Response listing the cost center allocations for an employment.
1 property
1 required
ContractorContractDocumentStatus
string
The signing status of a contract document. - draft: The document is being prepared and has not been sent for signing. - awaitingsignatures: The document has be…
BulkEmploymentEmployeePayload
object
Employee payload. The nested fields must match the employment schema for the selected country. activateglobalpayroll is currently supported only for Serbia (SR…
2 properties
EmploymentBasicResponse
object
A lightweight employment representation returned after creation. Contains basic identification, country, and status fields but not the full onboarding details…
13 properties
DownloadDocumentResponse
object
Response containing a document's metadata and its base64-encoded content for download.
1 property
1 required
File
object
A file associated with an employment, such as a contract, tax form, or identity document.
5 properties
4 required
EmploymentBankAccountDetailsParams
object
Employment bank account details params.
1 property
1 required
EmploymentWithCostCenterAllocations
object
An employment under the company with its cost center allocations.
4 properties
2 required
JobAssociation
object
A reference to a related job classification entity (job family, sub-family, career track, or job level). Null if not assigned.
2 properties
EmploymentCreationResponse
object
1 property
IndexPreOnboardingRequirementsResponse
object
List of pre-onboarding requirements for an employment.
1 property
1 required
EmploymentResponse
object
Response containing the full employment record after an update operation.
1 property
1 required
CreateRiskReserveProofOfPaymentParams
object
1 property
1 required
NullableDateTime
string
Optional UTC date time in YYYY-MM-DDTHH:mm:ss format
Step
object
8 properties
5 required
EmploymentLifecycleStage
string
The stage of employment lifecycle. When it's onboarded means the employee is ready to commence or has already commenced.
EmploymentOnboardingStepsResponse
object
1 property
1 required
CountryCode
string
Country code according to ISO 3166-1 3-digit alphabetic codes.
FindOrCreatePreOnboardingDocumentParams
object
Parameters to find an existing unsigned pre-onboarding document or create a new one.
2 properties
1 required
DownloadFileResponse
object
Response containing the file's metadata and its base64-encoded content for download.
1 property
1 required
PreOnboardingDocumentRequirement
object
A pre-onboarding document requirement that must be fulfilled before an employee can be onboarded.
10 properties
5 required
AccountsLoginSyncedWith
string
Indicates which email type the account login is synchronized with.
ProvisionalStartDate
string
Indicates the expected start date of the employee or contractor. Required for employees, but optional for contractors. Date format is in ISO8601 without the ti…
PreOnboardingRequirement
object
A pre-onboarding requirement (document or acknowledgement) that must be fulfilled before an employee can be onboarded.
9 properties
9 required
EmploymentPersonalDetailsParams
object
Employment personal details.
1 property
1 required
EmploymentEngagementAgreementDetailsParams
object
Engagement agreement details schema compatible params.
1 property
1 required
Slug
string
SignatoryStatus
string
Current signing status of this signatory
DateTime
string
UTC date time in YYYY-MM-DDTHH:mm:ss format
ListCompanyCostCenterAllocationsResponse
object
Response schema listing many employments
1 property
Country
object
A supported country on Remote
11 properties
3 required
EmploymentCreateParams
object
Description of the basic required and onboarding tasks params to create an employment. You do not need to include all onboarding tasks when creating or updatin…
8 properties
2 required
ShortId
string
Unique short identifier for the employment, automatically generated and visible in select areas of the Remote platform. Not intended as a replacement for the e…
ActionError
object
3 properties
3 required
SignatoryType
string
The role of this signatory in the contract signing process
MinimalEmployment
object
A lightweight employment representation used in list responses. Contains key identification, status, and type fields but not the full onboarding details or cou…
16 properties
14 required
BulkEmploymentImportJob
object
17 properties
12 required
IndexPreOnboardingDocumentRequirementsResponse
object
List of pre-onboarding document requirements for an employment.
1 property
1 required
EmployeeFileParams
object
Parameters to upload a file from an employee-issued token. The employment is derived from the access token's subject, so no employment id is required in the bo…
3 properties
1 required
EmploymentAdministrativeDetailsParams
object
Employment administrative details params.
1 property
1 required
EmploymentSeniorityDate
string
The date the employee first started working for your company. If you don’t include a seniority date, the employee’s start date with Remote will be deemed as th…
TaskDescription
object
Description and status of an onboarding task.
2 properties
NullableCountry
object
A supported country on Remote
11 properties
3 required
EmploymentStateTaxesParams
object
State taxes schema compatible params, submitted one jurisdiction at a time.
1 property
1 required
TooManyRequestsResponse
object
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.
1 property
UploadFileResponse
object
Response returned after successfully uploading a file.
1 property
SignContractDocument
object
SignContractDocument schema
1 property
1 required
AccountsAccount
object
An Account
5 properties
1 required
CostCenter
object
The cost center an employment is allocated to.
3 properties
3 required
EmploymentV2UpdateParams
object
Parameters for updating employment-level fields such as department, manager, work email, and external ID.
4 properties
FileParams
object
Parameters to upload a file
4 properties
2 required
ListEmploymentsResponse
object
Response schema listing many employments
1 property
ListDocumentsResponse
object
Response schema listing many documents
1 property
EmploymentImage
object
Employment image file
ImportJobRowError
object
3 properties
1 required
UnprocessableEntityResponse
object
Employment
object
Complete information of an employment, including all onboarding task statuses, country-specific form data (address, contract, administrative, etc.), and contra…
45 properties
28 required
BadRequestResponse
object
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 messa…
CreateRiskReserveParams
object
Parameters for creating a risk reserve deposit for an employment. A risk reserve is a refundable deposit held by Remote to cover potential liabilities during t…
1 property
1 required
EmploymentFullParams
object
Description of the basic required and onboarding tasks params to create an employment. You do not need to include all onboarding tasks when creating or updatin…
17 properties
BulkEmploymentCreateParams
object
Creates an asynchronous bulk employment job. Global Payroll activation is currently limited to Serbia (SRB) and requires the bulkgpproductactivation feature fl…
3 properties
2 required
MinimalUser
object
6 properties
2 required
NotFoundResponse
object
Returned when the requested resource does not exist or is not accessible with the current authentication credentials.
1 property
EmploymentDetailsOnlyResponse
object
Response containing only the updated details struct plus base employment fields (id, status, type, updatedat, userstatus). Exactly one of the details propertie…
1 property
1 required
DateTimeIso8601
string
UTC date time in [ISO 8601][] format. [ISO 8601]: https://en.wikipedia.org/wiki/ISO8601
ShowPreOnboardingDocumentResponse
object
Returns the rendered contract PDF (base64) and signatories for a pre-onboarding document.
1 property
1 required
EmploymentPricingPlanDetailsParams
object
Employment pricing plan details params.
1 property
1 required
EmploymentBasicInformationParams
object
Employment basic information params.
1 property
1 required
CreatePreOnboardingAcknowledgementResponse
object
Returns the slug of the recorded pre-onboarding acknowledgement.
1 property
1 required
CostCenterAllocation
object
A cost center allocation for an employment, including the allocated percentage and effective period.
6 properties
6 required
BulkEmploymentImportJobResponse
object
1 property
1 required
EmploymentAddressDetailsParams
object
Employment address details params.
1 property
1 required
UserStatus
string
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 b…
Date
string
UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO8601) format
AccountsMinimalCompanyAdmin
object
3 properties
EmploymentEngagementAgreementDetailsResponse
object
1 property
1 required
EmploymentShowResponse
object
Response containing the full employment record, including the termination date if the employment has an active offboarding.
1 property
1 required
UnauthorizedResponse
object
Returned when the request does not include valid authentication credentials. Ensure you are passing a valid OAuth2 access token or API token in the Authorizati…
1 property
1 required
AccountUserIntegrationUser
object
3 properties
3 required
PersonalDetails
object
Personal details for a user, includes sensitive information
15 properties
ImportDataRow
object
ForbiddenResponse
object
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…
1 property
1 required
EmploymentEmergencyContactParams
object
Employment emergency contact params.
1 property
1 required
Email
object
6 properties
1 required
UuidSlug
string
Identifier of the employment being terminated.
CountrySubdivision
object
A subdivision of a supported country on Remote
3 properties
1 required
PricingPlanDetails
object
Selected type of payment.
1 property
1 required
BackgroundChecks.BackgroundCheckRequestItem
object
4 properties
4 required
BackgroundChecks.BackgroundCheck
object
5 properties
5 required
EmploymentStatus
string
The current status of the employment record. - active: The employee is fully onboarded and actively working. - created: The employment has been created but onb…
SubStep
object
8 properties
5 required
EmploymentJobResponse
object
1 property
1 required
EmploymentFederalTaxesParams
object
Federal taxes schema compatible params.
1 property
1 required
CreatePreOnboardingDocumentResponse
object
Returns the slug of the found-or-created pre-onboarding document.
1 property
1 required
ImportJobRow
object
8 properties
3 required
OnboardingTasks
object
All tasks that need to be completed before marking the employment as ready
9 properties
9 required
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from Remote 12
Other APIs Remote publishes across the network.
Remote Address Details API
Remote Administrative Details API
Remote Background Checks API
Remote Bank Account Details API
Remote Basic Information API
Remote Benefit Offers API
Remote Benefit Offers By Employment API
Remote Benefit Renewals API
Remote Benefits API
Remote Billing Address Details API
Remote Billing API
Remote Billing Documents API
#Employments