Remote Engagement Agreement Details API
The Engagement Agreement Details API from Remote — 2 operation(s) for engagement agreement details.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Engagement Agreement Details API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Engagement Agreement Details
paths:
/v2/employments/{employment_id}/engagement-agreement-details:
get:
callbacks: {}
deprecated: false
description: 'Returns the engagement agreement details for an employment.
## 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_engagement-agreement-details
parameters:
- description: Employment ID
example: 93t3j-employment-id-9suej43
in: path
name: employment_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmploymentEngagementAgreementDetailsResponse'
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 engagement agreement details
tags:
- Engagement Agreement Details
post:
callbacks: {}
deprecated: false
description: 'Creates or updates the engagement agreement details for an employment.
This endpoint requires country-specific data. The exact required 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 compliance requirements for each country are subject to change according to local laws.
Using Remote''s [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) is recommended
to avoid compliance issues and to have the latest version of a country''s requirements.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | - | Manage employments (`employment:write`) |
'
operationId: post_v2_employments_employment_id_engagement-agreement-details
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/EmploymentEngagementAgreementDetailsParams'
description: Employment engagement agreement details params
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
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
'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: Upsert engagement agreement details
tags:
- Engagement Agreement Details
/v1/employments/{employment_id}/engagement-agreement-details:
get:
callbacks: {}
deprecated: false
description: 'Returns the engagement agreement details for an employment.
## 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_employments_employment_id_engagement-agreement-details
parameters:
- description: Employment ID
example: 93t3j-employment-id-9suej43
in: path
name: employment_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmploymentEngagementAgreementDetailsResponse'
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 engagement agreement details
tags:
- Engagement Agreement Details
post:
callbacks: {}
deprecated: false
description: 'Creates or updates the engagement agreement details for an employment.
This endpoint requires country-specific data. The exact required 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 compliance requirements for each country are subject to change according to local laws.
Using Remote''s [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) is recommended
to avoid compliance issues and to have the latest version of a country''s requirements.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | - | Manage employments (`employment:write`) |
'
operationId: post_v1_employments_employment_id_engagement-agreement-details
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/EmploymentEngagementAgreementDetailsParams'
description: Employment engagement agreement details params
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
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
'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: Upsert engagement agreement details
tags:
- Engagement Agreement Details
components:
schemas:
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
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
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
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
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
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
EmploymentEngagementAgreementDetailsResponse:
example:
data:
details:
has_business_presence: 'no'
has_similar_roles: 'no'
slug: 93t3j-engagement-agreement-details-id
properties:
data:
additionalProperties: false
properties:
details:
additionalProperties: false
oneOf:
- additionalProperties: false
properties:
allowances_details:
items:
type: string
nullable: true
type: array
available_pto:
nullable: true
type: integer
break_time_per_day:
nullable: true
type: integer
business_expenses:
nullable: true
type: string
cba:
nullable: true
type: string
cba_document:
nullable: true
type: object
covenants:
items:
type: string
nullable: true
type: array
has_allowances:
nullable: true
type: string
has_bonus:
nullable: true
type: string
has_business_expenses:
nullable: true
type: string
has_business_presence:
type: string
has_cba:
nullable: true
type: string
has_commissions:
nullable: true
type: string
has_covenants:
nullable: true
type: string
has_illness_remuneration:
nullable: true
type: string
has_overtime_compensation:
nullable: true
type: string
has_pension_scheme:
nullable: true
type: string
has_signing_bonus:
nullable: true
type: string
has_similar_roles:
type: string
has_similar_work_conditions:
nullable: true
type: string
illness_remuneration_details:
nullable: true
type: string
max_annual_gross_salary:
nullable: true
type: integer
min_annual_gross_salary:
nullable: true
type: integer
overtime_compensation_begins:
nullable: true
type: integer
overtime_compensation_type:
nullable: true
type: string
overtime_pay_percentage:
nullable: true
type: integer
pension_scheme:
nullable: true
type: string
similar_roles:
nullable: true
type: string
similar_work_conditions_details:
nullable: true
type: string
work_hours_per_week:
nullable: true
type: integer
working_days:
items:
type: string
nullable: true
type: array
title: EngagementAgreementDetailsParamsDEU
type: object
type: object
slug:
type: string
required:
- slug
- details
type: object
required:
- data
title: EmploymentEngagementAgreementDetailsResponse
type: object
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
SuccessResponse:
description: A generic success response returned by operations that don't produce a specific resource (e.g., updates, deletes).
example:
data:
status: ok
properties:
data:
properties:
status:
description: The result status. Always `"ok"` for successful operations.
type: string
type: object
required:
- data
title: SuccessResponse
type: object
EmploymentEngagementAgreementDetailsParams:
additionalProperties: false
description: 'Engagement agreement details schema compatible params.
'
example:
engagement_agreement_details:
allowances_details:
- meal_allowance
- transportation_commuter_allowance
available_pto: 20
break_time_per_day: 1
business_expenses: Business expenses details
cba: CBA 1
cba_document:
filename: cba_document.pdf
covenants:
- confidentiality
- non_compete
has_allowances: 'yes'
has_bonus: 'yes'
has_business_expenses: 'yes'
has_business_presence: 'yes'
has_cba: 'yes'
has_commissions: 'yes'
has_covenants: 'yes'
has_illness_remuneration: 'yes'
has_overtime_compensation: 'yes'
has_pension_scheme: 'yes'
has_signing_bonus: 'yes'
has_similar_roles: 'yes'
has_similar_work_conditions: 'yes'
illness_remuneration_details: Illness remuneration details
max_annual_gross_salary: 100000
min_annual_gross_salary: 50000
overtime_compensation_begins: 10
overtime_compensation_type: extra_pay
overtime_pay_percentage: 5
pension_scheme: Pension scheme details
similar_roles: Role 1, Role 2, Role 3
similar_work_conditions_details: Similar work conditions details
work_hours_per_week: 40
working_days:
- monday
- tuesday
- wednesday
- thursday
- friday
properties:
engagement_agreement_details:
additionalProperties: false
description: 'Engagement agreement details params. As its properties may vary depending on the country,
you must query the [Show form schema](#tag/Countries/operation/get_show_engagement_agreement_details_country) endpoint
passing the country code.
'
oneOf:
- additionalProperties: false
properties:
allowances_details:
items:
type: string
nullable: true
type: array
available_pto:
nullable: true
type: integer
break_time_per_day:
nullable: true
type: integer
business_expenses:
nullable: true
type: string
cba:
nullable: true
type: string
cba_document:
nullable: true
type: object
covenants:
items:
type: string
nullable: true
type: array
has_allowances:
nullable: true
type: string
has_bonus:
nullable: true
type: string
has_business_expenses:
nullable: true
type: string
has_business_presence:
type: string
has_cba:
nullable: true
type: string
has_commissions:
nullable: true
type: string
has_covenants:
nullable: true
type: string
has_illness_remuneration:
nullable: true
type: string
has_overtime_compensation:
nullable: true
type: string
has_pension_scheme:
nullable: true
type: string
has_signing_bonus:
nullable: true
type: string
has_similar_roles:
type: string
has_similar_work_conditions:
nullable: true
type: string
illness_remuneration_details:
nullable: true
type: string
max_annual_gross_salary:
nullable: true
type: integer
min_annual_gross_salary:
nullable: true
type: integer
overtime_compensation_begins:
nullable: true
type: integer
overtime_compensation_type:
nullable: true
type: string
overtime_pay_percentage:
nullable: true
type: integer
pension_scheme:
nullable: true
type: string
similar_roles:
nullable: true
type: string
similar_work_conditions_details:
nullable: true
type: string
work_hours_per_week:
nullable: true
type: integer
working_days:
items:
type: string
nullable: true
type: array
title: EngagementAgreementDetailsParamsDEU
type: object
type: object
required:
- engagement_agreement_details
title: EmploymentEngagementAgreementDetailsParams
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: expens
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-engagement-agreement-details-api-openapi.yml