> ## Documentation Index > Fetch the complete documentation index at: https://developer.remote.com/llms.txt > Use this file to discover all available pages before exploring further. # List employments Lists all employments, except for the deleted ones. 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. # OpenAPI definition ```json { "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" }, "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" }, "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" }, "MinimalEmployment": { "description": "A lightweight employment representation used in list responses. Contains key identification, status, and type fields but not the full onboarding details or country-specific form data.", "example": { "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" ] }, "department": null, "department_id": null, "employment_lifecycle_stage": "employment_creation", "employment_model": "eor", "external_id": "1234567890", "full_name": "Jane Smith", "id": "add736b8-employment-id-a76ccae2abe8", "job_title": "Engineer", "login_email": "janesmith@company.com", "personal_email": "janesmith@company.com", "short_id": "1234567890", "status": "created", "type": "employee", "work_address_details": {}, "work_email": "janesmith@company.com" }, "properties": { "country": { "$ref": "#/components/schemas/NullableCountry" }, "department": { "description": "Name of related department, if any. Otherwise, null.", "nullable": true, "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" }, "employment_lifecycle_stage": { "$ref": "#/components/schemas/EmploymentLifecycleStage" }, "employment_model": { "description": "The employment model. `eor` (Employer of Record), `peo` (Professional Employer Organization), or `global_payroll`.", "enum": [ "eor", "peo", "global_payroll" ], "nullable": true, "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.", "nullable": true, "type": "string" }, "full_name": { "description": "The employee's full name.", "type": "string" }, "id": { "description": "The unique identifier (UUID) of the employment.", "type": "string" }, "job_title": { "description": "The employee's job title.", "type": "string" }, "login_email": { "description": "The email the employee uses to log in to Remote.", "format": "email", "type": "string" }, "personal_email": { "description": "The employee's personal email address.", "format": "email", "type": "string" }, "short_id": { "$ref": "#/components/schemas/ShortId" }, "status": { "$ref": "#/components/schemas/EmploymentStatus" }, "type": { "description": "The type of employment.", "enum": [ "employee", "contractor", "direct_employee", "global_payroll_employee" ], "type": "string" }, "work_address_details": { "description": "Work address information. Its properties may vary depending on the country.", "type": "object" }, "work_email": { "description": "The employee's work email address. Null if not set.", "format": "email", "nullable": true, "type": "string" } }, "required": [ "country", "full_name", "id", "job_title", "personal_email", "login_email", "status", "type", "short_id", "external_id", "employment_lifecycle_stage", "work_address_details", "employment_model", "work_email" ], "title": "MinimalEmployment", "type": "object" }, "CountrySubdivision": { "description": "A subdivision of a supported country on Remote", "example": { "code": "PT-11", "name": "Lisboa", "subdivision_type": "District" }, "properties": { "code": { "description": "The ISO 3166-2 subdivision code (e.g., \"PT-11\" for Lisboa).", "type": "string" }, "name": { "description": "The subdivision's name (e.g., \"Lisboa\", \"California\").", "type": "string" }, "subdivision_type": { "description": "The type of subdivision (e.g., \"District\", \"State\", \"Province\").", "type": "string" } }, "required": [ "name" ], "title": "CountrySubdivision", "type": "object" }, "EmploymentLifecycleStage": { "description": "The stage of employment lifecycle. When it's `onboarded` means the employee is ready to commence or has already commenced.", "enum": [ "employment_creation", "employee_self_enrollment", "right_to_work_check", "contract_signing", "remote_enrollment", "onboarded", "offboarded" ], "example": "employee_self_enrollment", "title": "EmploymentLifecycleStage", "type": "string" }, "NullableCountry": { "description": "A supported country on Remote", "example": { "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" ] }, "nullable": true, "properties": { "alpha_2_code": { "description": "The ISO 3166-1 alpha-2 country code (e.g., \"PT\").", "type": "string" }, "code": { "description": "The ISO 3166-1 alpha-3 country code (e.g., \"PRT\"). This is the primary code used across the Remote API.", "type": "string" }, "contractor_products_available": { "description": "Contractor product names available for this country", "items": { "enum": [ "standard", "plus", "cor" ], "type": "string" }, "type": "array" }, "country_subdivisions": { "description": "Administrative subdivisions of the country (e.g., states, provinces, districts). Null if the country has no subdivisions relevant to Remote's services.", "items": { "$ref": "#/components/schemas/CountrySubdivision" }, "nullable": true, "type": "array" }, "employment_agreement_preview_available": { "description": "Whether an Employment Agreement preview is available for this country.", "type": "boolean" }, "eor_onboarding": { "description": "Whether EOR (Employer of Record) onboarding is available in this country.", "type": "boolean" }, "locked_benefits": { "description": "When benefit plan selections become locked for this country (e.g., \"after_first_hire\" means benefits cannot be changed after the first employee is hired).", "type": "string" }, "name": { "description": "The country's full English name.", "type": "string" }, "region": { "description": "The geographic region the country belongs to (e.g., \"Europe\", \"Asia\", \"Americas\").", "type": "string" }, "subregion": { "description": "The geographic subregion (e.g., \"Southern Europe\", \"Southeast Asia\"). Null for some countries.", "nullable": true, "type": "string" }, "supported_json_schemas": { "description": "The list of JSON schema form names available for this country (e.g., \"address_details\", \"contract_details\"). Use these with the Show form schema endpoint to get country-specific field requirements.", "items": { "type": "string" }, "type": "array" } }, "required": [ "alpha_2_code", "code", "name" ], "title": "NullableCountry", "type": "object" }, "EmploymentStatus": { "description": "The current status of the employment record.\n\n- `active`: The employee is fully onboarded and actively working.\n- `created`: The employment has been created but onboarding has not started.\n- `pre_hire`: A pre-hire employment record, created before formal onboarding begins.\n- `created_awaiting_reserve`: The employment is created but waiting for a risk reserve deposit to be paid.\n- `created_reserve_paid`: The risk reserve has been paid and the employment can proceed with onboarding.\n- `initiated`: Onboarding has been started by the employer.\n- `invited`: The employee has been invited to complete their self-enrollment on Remote.\n- `pending`: The employment is pending review or further action before it can become active.\n- `review`: The employment is under review by Remote (e.g., contract or compliance review).\n- `archived`: The employment has been terminated or offboarded.\n- `deleted`: The employment record has been deleted.\n", "enum": [ "active", "created", "pre_hire", "created_awaiting_reserve", "created_reserve_paid", "initiated", "invited", "pending", "review", "job_title_review", "pending_post_self_enrollment_actions", "offboarding", "archived", "deleted" ], "example": "active", "title": "EmploymentStatus", "type": "string" }, "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" }, "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" }, "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" }, "ListEmploymentsResponse": { "description": "Response schema listing many employments", "example": { "current_page": 1, "employments": [ { "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" ] }, "department": null, "department_id": null, "employment_lifecycle_stage": "employment_creation", "employment_model": "eor", "external_id": "1234567890", "full_name": "Jane Smith", "id": "add736b8-employment-id-a76ccae2abe8", "job_title": "Engineer", "login_email": "janesmith@company.com", "personal_email": "janesmith@company.com", "short_id": "1234567890", "status": "created", "type": "employee", "work_address_details": {}, "work_email": "janesmith@company.com" } ], "total_count": 1, "total_pages": 1 }, "properties": { "data": { "properties": { "current_page": { "description": "The current page among all of the total_pages", "type": "integer" }, "employments": { "items": { "$ref": "#/components/schemas/MinimalEmployment" }, "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": "ListEmploymentsResponse", "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" }, "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" } }, "securitySchemes": { "OAuth2": { "description": "Authenticate using OAuth 2.0 protocol.\n", "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" } } }, "info": { "title": "Employments", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/v1/employments": { "get": { "callbacks": {}, "deprecated": false, "description": "Lists all employments, except for the deleted ones.\n\nThis endpoint requires and returns country-specific data. The exact required and returned fields will\nvary depending on which country the employment is in. To see the list of parameters for each country,\nsee the **Show form schema** endpoint under the [Countries](#tag/Countries) category.\n\nPlease note that the compliance requirements for each country are subject to change according to local\nlaws. 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\ncompliance issues and to have the latest version of a country requirements.\n\nIf you are using this endpoint to build an integration, make sure you are dynamically collecting or\ndisplaying the latest parameters for each country by querying the _\"Show form schema\"_ endpoint.\n\nFor more information on JSON Schemas, see the **How JSON Schemas work** documentation.\n\nTo learn how you can dynamically generate forms to display in your UI, see the documentation for\nthe [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) tool.\n\n", "operationId": "get_v1_employments", "parameters": [ { "description": "Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.\n\nThe refresh token needs to have been obtained through the Authorization Code flow.\n", "example": "Bearer ", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" } }, { "description": "Company ID", "example": "93t3j-company-id-9suej43", "in": "query", "name": "company_id", "required": false, "schema": { "type": "string" } }, { "description": "Filters the results by employments whose login email matches the value", "example": "anna@example.com", "in": "query", "name": "email", "required": false, "schema": { "type": "string" } }, { "description": "Filters the results by employments whose status matches the value.\nSupports multiple values separated by commas.\nAlso supports the value `incomplete` to get all employments that are not onboarded yet.\n", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "description": "Filters the results by employments whose employment product type matches the value", "example": "contractor", "in": "query", "name": "employment_type", "required": false, "schema": { "type": "string" } }, { "description": "Filters the results by employments whose employment model matches the value.\nPossible values: `global_payroll`, `peo`, `eor`\n", "example": "global_payroll", "in": "query", "name": "employment_model", "required": false, "schema": { "enum": [ "global_payroll", "peo", "eor" ], "type": "string" } }, { "description": "Filters the results by the employment's short ID. Returns at most one result.", "example": "aB1cD2", "in": "query", "name": "short_id", "required": false, "schema": { "type": "string" } }, { "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/ListEmploymentsResponse" } } }, "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" } }, "summary": "List employments", "tags": [ "Employment Management" ] } } }, "security": [ { "OAuth2": [] } ], "servers": [ { "url": "https://gateway.remote.com/", "variables": {} }, { "url": "https://gateway.remote-sandbox.com/", "variables": {} } ], "tags": [ { "name": "Employments" } ], "webhooks": { "background_check.status.updated": { "post": { "deprecated": false, "description": "This event is triggered when a background check request status is updated.", "operationId": "background_check.status.updated", "requestBody": { "content": { "application/json": { "schema": { "example": { "background_check_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "company_id": "ba310525-9282-40c9-8977-14d844bf891a", "employment_id": "e966a8b8-1076-11ee-a5f2-9b3997a968f6", "event_type": "background_check.status.updated" }, "properties": { "background_check_id": { "description": "The unique identifier of the background check.", "type": "string" }, "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "event_type", "background_check_id", "company_id", "employment_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "background_check.status.updated", "tags": [ "Background Checks" ] } }, "employment.account.updated": { "post": { "deprecated": false, "description": "This event is triggered whenever an employment account email is updated.", "operationId": "employment.account.updated", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "event_type": "employment.account.updated" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "event_type", "employment_id", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.account.updated", "tags": [ "Employment Management" ] } }, "employment.administrative_details.updated": { "post": { "deprecated": false, "description": "This event is triggered when the administrative details of an employment are updated.", "operationId": "employment.administrative_details.updated", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_slug": "f2a1b3c4-d5e6-7f8g-9h0i-j1k2l3m4n5o6", "event_type": "employment.administrative_details.updated" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_slug": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "event_type", "employment_slug", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.administrative_details.updated", "tags": [ "Employment Management" ] } }, "employment.details.updated": { "post": { "deprecated": false, "description": "This event is triggered whenever an employment `department` or `manager` is updated.", "operationId": "employment.details.updated", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "event_type": "employment.details.updated" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "event_type", "employment_id", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.details.updated", "tags": [ "Employment Management" ] } }, "employment.employment_agreement.available": { "post": { "deprecated": false, "description": "This event is triggered when an employment agreement is available for a user", "operationId": "employment.employment_agreement.available", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "event_type": "employment.employment_agreement.available", "file_id": "0073fcb5-b669-4e4a-b963-2a47744e75a1" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" }, "file_id": { "description": "The unique identifier of the related file.", "type": "string" } }, "required": [ "file_id", "employment_id", "event_type", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.employment_agreement.available", "tags": [ "Employments" ] } }, "employment.eor_hiring.invoice_created": { "post": { "deprecated": false, "description": "This event is triggered when a invoice report is created for a employment.", "operationId": "employment.eor_hiring.invoice_created", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "f2a1b3c4-d5e6-7f8g-9h0i-j1k2l3m4n5o6", "employment_id": "f8e9d2c7-3a1b-4f5c-9e6d-8b7a2c1d0e3f", "event_type": "employment.eor_hiring.invoice_created", "invoice_report_id": "c7f8e9d2-3a1b-4f5c-9e6d-8b7a2c1d0e3f" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" }, "invoice_report_id": { "description": "The unique identifier of the invoice report.", "type": "string" } }, "required": [ "event_type", "employment_id", "invoice_report_id", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.eor_hiring.invoice_created", "tags": [ "Employments" ] } }, "employment.eor_hiring.proof_of_payment_accepted": { "post": { "deprecated": false, "description": "This event is triggered when a proof of payment is accepted.", "operationId": "employment.eor_hiring.proof_of_payment_accepted", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "f2a1b3c4-d5e6-7f8g-9h0i-j1k2l3m4n5o6", "employment_id": "f8e9d2c7-3a1b-4f5c-9e6d-8b7a2c1d0e3f", "event_type": "employment.eor_hiring.proof_of_payment_accepted", "proof_of_payment_id": "c7f8e9d2-3a1b-4f5c-9e6d-8b7a2c1d0e3f" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" }, "proof_of_payment_id": { "description": "The unique identifier of the proof of payment.", "type": "string" } }, "required": [ "event_type", "employment_id", "proof_of_payment_id", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.eor_hiring.proof_of_payment_accepted", "tags": [ "Employments" ] } }, "employment.eor_hiring.proof_of_payment_submitted": { "post": { "deprecated": false, "description": "This event is triggered when a proof of payment is submitted (uploaded) for an EOR hiring onboarding.", "operationId": "employment.eor_hiring.proof_of_payment_submitted", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "f2a1b3c4-d5e6-7f8g-9h0i-j1k2l3m4n5o6", "employment_id": "f8e9d2c7-3a1b-4f5c-9e6d-8b7a2c1d0e3f", "event_type": "employment.eor_hiring.proof_of_payment_submitted", "proof_of_payment_id": "c7f8e9d2-3a1b-4f5c-9e6d-8b7a2c1d0e3f" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" }, "proof_of_payment_id": { "description": "The unique identifier of the proof of payment.", "type": "string" } }, "required": [ "event_type", "employment_id", "proof_of_payment_id", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.eor_hiring.proof_of_payment_submitted", "tags": [ "Employments" ] } }, "employment.no_longer_eligible_for_onboarding_cancellation": { "post": { "deprecated": false, "description": "This event is triggered when an employment is no longer eligible for onboarding cancellation.", "operationId": "employment.no_longer_eligible_for_onboarding_cancellation", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_slug": "ba310525-9282-40c9-8977-14d844bf891a" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_slug": { "description": "The unique identifier of the related employment.", "type": "string" } }, "required": [ "employment_slug", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.no_longer_eligible_for_onboarding_cancellation", "tags": [ "Employments" ] } }, "employment.onboarding.cancelled": { "post": { "deprecated": false, "description": "This event is triggered when an employment onboarding is cancelled.", "operationId": "employment.onboarding.cancelled", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_id": "f8e9d2c7-3a1b-4f5c-9e6d-8b7a2c1d0e3f", "event_type": "employment.onboarding.cancelled" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "event_type", "employment_id", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.onboarding.cancelled", "tags": [ "Employments" ] } }, "employment.onboarding.completed": { "post": { "deprecated": false, "description": "This event is triggered when an employment onboarding is completed and the\nemployment is set to `active`.\n\nAn onboarding is considered complete when the employee finishes their self-enrollment\nand has completed all the onboarding tasks assigned to them (Personal profile, Administrative details,\nEmergency contact, Supporting documentation, etc).\n", "operationId": "employment.onboarding.completed", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "event_type": "employment.onboarding.completed" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "event_type", "employment_id", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.onboarding.completed", "tags": [ "Employment Management" ] } }, "employment.onboarding.started": { "post": { "deprecated": false, "description": "This event is triggered when an employment onboarding is started.\n", "operationId": "employment.onboarding.started", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "event_type": "employment.onboarding.started" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "event_type", "employment_id", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.onboarding.started", "tags": [ "Employment Management" ] } }, "employment.onboarding_task.completed": { "post": { "deprecated": false, "description": "This event is triggered everytime an employment onboarding task\n(Personal profile, Administrative details, Emergency contact,\nSupporting documentation, etc) is completed by an employee during\nthe self-enrollment.\n", "operationId": "employment.onboarding_task.completed", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "97c7ce7e-ca67-11ed-bce5-3bb70cbb9f9e", "completed_task": { "action": "administrative_details", "completed_at": "2023-03-23T03:21:23Z", "description": "description for administrative details", "name": "Administrative details", "required": true, "status": "completed" }, "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "event_type": "employment.onboarding_task.completed" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "completed_task": { "properties": { "action": { "description": "The action identifier for this task.", "enum": [ "additional_documents", "administrative_details", "business_information", "emergency_contact", "home_address", "i9_verification", "identity_verification", "payment_details", "review_compensation", "safetywing_enrollment", "user_details", "employment_eligibility" ], "type": "string" }, "completed_at": { "description": "The timestamp when the task was completed.", "format": "datetime", "type": "string" }, "description": { "description": "A description of what this onboarding task covers.", "type": "string" }, "name": { "description": "The name of the completed onboarding task (e.g., \"Personal details\").", "type": "string" }, "required": { "description": "Whether this task was required for onboarding completion.", "type": "boolean" }, "status": { "description": "The status of the task.", "enum": [ "created", "completed" ], "type": "string" } }, "required": [ "name", "description", "required", "completed_at", "action", "status" ] }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "event_type", "company_id", "employment_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.onboarding_task.completed", "tags": [ "Employment Management" ] } }, "employment.personal_information.updated": { "post": { "deprecated": false, "description": "This event is triggered whenever an employment personal details is updated. Personal details includes personal informations, home address and emergency contact.", "operationId": "employment.personal_information.updated", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "event_type": "employment.personal_information.updated" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "event_type", "employment_id", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.personal_information.updated", "tags": [ "Employment Management" ] } }, "employment.start_date.changed": { "post": { "deprecated": false, "description": "This event is triggered when the start date of an employment is changed", "operationId": "employment.start_date.changed", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "event_type": "employment.start_date.changed" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "employment_id", "event_type", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.start_date.changed", "tags": [ "Employment Management" ] } }, "employment.status.updated": { "post": { "deprecated": false, "description": "This event is triggered when the employment status is updated", "operationId": "employment.status.updated", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "event_type": "employment.status.updated" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "employment_id", "event_type", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.status.updated", "tags": [ "Employment Management" ] } }, "employment.updated": { "post": { "deprecated": false, "description": "This event is triggered when an employment is updated.\n", "operationId": "employment.updated", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "event_type": "employment.updated" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "event_type", "employment_id", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.updated", "tags": [ "Employment Management" ] } }, "employment.user_status.activated": { "post": { "deprecated": false, "description": "This event is triggered whenever an employment user is updated to the active status.", "operationId": "employment.user_status.activated", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "event_type": "employment.user_status.activated" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "event_type", "employment_id", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.user_status.activated", "tags": [ "Employment Management" ] } }, "employment.user_status.deactivated": { "post": { "deprecated": false, "description": "This event is triggered whenever an employment user is updated to the inactive status.", "operationId": "employment.user_status.deactivated", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "event_type": "employment.user_status.deactivated" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "event_type", "employment_id", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.user_status.deactivated", "tags": [ "Employment Management" ] } }, "employment.user_status.initiated": { "post": { "deprecated": false, "description": "This event is triggered whenever an employment user is updated to the initiated status.", "operationId": "employment.user_status.initiated", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "event_type": "employment.user_status.initiated" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "event_type", "employment_id", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.user_status.initiated", "tags": [ "Employment Management" ] } }, "employment.user_status.invited": { "post": { "deprecated": false, "description": "This event is triggered when an employment user status is updated to invited.", "operationId": "employment.user_status.invited", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "event_type": "employment.user_status.invited" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "employment_id", "event_type", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.user_status.invited", "tags": [ "Employment Management" ] } }, "employment.work_email.updated": { "post": { "deprecated": false, "description": "This event is triggered when an employment work email is updated.\n", "operationId": "employment.work_email.updated", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "event_type": "employment.work_email.updated" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "event_type", "employment_id", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment.work_email.updated", "tags": [ "Employment Management" ] } }, "employment_basic_information.updated": { "post": { "deprecated": false, "description": "This event is triggered when the basic information for an employment is updated", "operationId": "employment_basic_information.updated", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "event_type": "employment_basic_information.updated" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "employment_id", "event_type", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "employment_basic_information.updated", "tags": [ "Employments" ] } }, "identity_verification.verification_required": { "post": { "deprecated": false, "description": "This event is triggered whenever an identity verification is required for an employment.", "operationId": "identity_verification.verification_required", "requestBody": { "content": { "application/json": { "schema": { "example": { "company_id": "d2091b1e-b1a4-437a-91ea-2809ffbb6d59", "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99", "event_type": "identity_verification.verification_required" }, "properties": { "company_id": { "description": "The unique identifier of the related company.", "type": "string" }, "employment_id": { "description": "The unique identifier of the related employment.", "type": "string" }, "event_type": { "description": "The webhook event type identifier.", "type": "string" } }, "required": [ "event_type", "employment_id", "company_id" ] } } } }, "responses": { "2XX": { "description": "Any 200 response confirms that the webhook was delivered." } }, "security": [], "summary": "identity_verification.verification_required", "tags": [ "Identity Verification" ] } } } } ```