--- updatedAt: 2026-09-29T13:23:07.000Z agentTools: projectIndex: https://docs.oysterhr.com/llms.txt --- # Creating and submitting an EOR employment This guide will show you how to create a draft EOR employment, update the job details, and submit the employment to kick off the employment onboarding and contract generation. Note for Reseller partners using the API - you will need to use the `X-Oyster-Customer-Id` header for all of the calls in this guide. For more information, see the [Reseller guide to using the Oyster API](https://docs.oysterhr.com/docs/reseller-guide-to-using-the-oyster-api). *** ## **1. Create Employment** First you need to [create an employment record](https://docs.oysterhr.com/reference/post_v1-hiring-employments), which represents the start of the hiring process for an EOR engagement. In your request, you will need to include the employment’s [ISO-3166 Alpha country code](https://www.iban.com/country-codes), full legal name, email, and nationality. ### **Example Request** ```bash curl --request POST \ --url https://api.oysterhr.com/v0.1/hiring/employments/ \ --header 'accept: application/json' \ --header 'authorization: Bearer BEARER_TOKEN_GOES_HERE' \ --header 'content-type: application/json' \ --data ' { "personalDetails": { "fullLegalName": "Test Hire", "email": "test@test.com", "nationality": "US" }, "countryCode": "US", "subdivisionCode": "CA" } ' ``` ### **Response** If successful, the API will return a `200 OK` response with the newly created employment details, including an `id` that you will need for future updates and submission. The employment will then be in a `draft` phase and ready to continue filling the contractual details. ### **Example Response** ```json { "data": { "engagementId": "urY7zKOm", "countryCode": "US", "subdivisionCode": "CA", "personalDetails": { "fullLegalName": "Test Hire", "email": "test@test.com", "nationality": "US", "workPermit": null }, "manager": { "managerRole": null, "managerName": null, "managerEmailAddress": null, "managerPhoneNumber": null, "managerIsExpenseApprover": false }, "role": { "newHireStatus": "new_hire", "seniorityLevel": null, "roleTypeId": null, "role": null, "jobDescription": null, "startDate": null, "endDate": null, "employmentType": null, "probationPeriod": null, "terminationNotice": null, "resignationNotice": null }, "compensation": { "commissionPlanOffered": null, "commissionPlan": null, "salary": { "decimal": "", "currencyCode": "USD" }, "paidHolidayDays": null, "bonuses": [], "allowances": [], "reimbursementBudgets": [], "remoteWorkCosts": null, "privateNotes": null, "sickPay": null }, "documents": [], "signer": null } } ``` *** ## **2. Update Employment** Once you’ve created the employment, you will need to [update the employment](https://docs.oysterhr.com/reference/patch_v1-hiring-employments-id) with details related to the job position. In the request body, only include the fields you want to update (e.g., `job_title`, `annual_salary`, etc.). ### **Example Request** ```bash curl --request PATCH \ --url https://api.oysterhr.com/v0.1/hiring/employments/urY7zKOm \ --header 'accept: application/json' \ --header 'authorization: Bearer BEARER_TOKEN_GOES_HERE' \ --header 'content-type: application/json' \ --data ' { "role": { "role": "Senior Software Engineer" }, "compensation": { "salary": { "decimal": "95000", "currencyCode": "USD" }, } } ' ```
The update employment endpoint can be used to make partial updates to the employment in separate API calls. However, to successfully submit an Employment in the next step, certain objects are required based on the Employment's designated country and `employmentType`. The schema includes 5 principle objects, some of which are required for employment submission. The required fields, possible values and field validations often vary by country, use the [Rulesets for updating employment of particular country and subdivision](https://docs.oysterhr.com/reference/get_v1-hiring-employments-rulesets#/) and the [Understanding rulesets](https://docs.oysterhr.com/update/docs/understanding-rulesets#/) guide to get the information you need. | **Name** | **Required?** | | --------------- | ------------- | | manager | No | | role | Yes | | personalDetails | Yes | | compensation | Yes | | signer | Yes | Within the required objects, not all items are required. The following tables show the required items for each required object. For more information about the objects structure and required fields for the different objects in the following tables, see the documentation. Within the `role` object, the following are required: | **Name** | **Type** | **Notes** | | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | seniorityLevel | field | | | roleTypeId / role | field | Job title can be looked up using the [Role Types](https://docs.oysterhr.com/reference/get_v1-hiring-role-types) endpoint or can be provided as free text (`role`) | | jobDescription | field | | | startDate | field | | | endDate | field | Only for fixed-term employments | | employmentType | field | This must be either `FULL_TIME` or `PART_TIME`. | | fullTimeHoursPerWeek | object | Only required for `FULL_TIME` employments. | | partTimeDaysPerWeek | object | Only required for `PART_TIME` employments. | | partTimeHoursPerWeek | object | Only required for `PART_TIME` employments. | | probationPeriod | object | | | terminationNotice | object | This field is required in: Australia, UK, Ireland, India. | | resignationNotice | object | This field is required in: Australia, UK, Ireland, India. | Within the `compensation` object, the following are required: | Name | Type | Notes | | :-------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | salary | object | | | paidHolidayDays | field | | | remoteWorkCosts | object | This covers equipment policy ("bring your own" or "equipment provided by the employer"), equipment reimbursement (budget or one-time payment), and allowance policy (statutory minimum present in some countries). Use the [Update employment](https://docs.oysterhr.com/reference/patch_v1-hiring-employments-id) to see the object structure and the [ruleset](https://docs.oysterhr.com/reference/get_v1-hiring-employments-rulesets#/) to get valid values for its properties. | | sickPay | object | This field is supported and required only in: UK, Ireland, Netherlands. Use the Update employment endpoint documentation to see the object structure and the [ruleset](https://docs.oysterhr.com/reference/get_v1-hiring-employments-rulesets#/) to get valid values for `option` and `customDuration`. For other countries this object is not supported, and supplying it would result in 422 Unprocessable Entity. | Within the `signer` object, the following are required: | **Name** | **Type** | **Notes** | | -------- | -------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | fullName | string | | | jobTitle | string | | | email | string | If company signatory exists with matching email, the point of contact record is updated with remaining fields in `signer` payload. If no signatory with matching email is found, a new one is created. | | phone | object | | ### **Response** A successful update returns the modified employment details. The `status` will still be `draft` until the employment is submitted in the following step. ### **Example Response** ```json { "data": { "engagementId": "urY7zKOm", "countryCode": "US", "subdivisionCode": "CA", "personalDetails": { "fullLegalName": "Test Hire", "email": "test@test.com", "nationality": "US", "workPermit": null }, "manager": { "managerRole": null, "managerName": null, "managerEmailAddress": null, "managerPhoneNumber": null, "managerIsExpenseApprover": false }, "role": { "newHireStatus": "new_hire", "seniorityLevel": "SENIOR", "roleTypeId": null, "role": "Senior Software Engineer", "jobDescription": null, "startDate": null, "endDate": null, "employmentType": null, "probationPeriod": null, "terminationNotice": null, "resignationNotice": null, "fullTimeHoursPerWeek": null }, "compensation": { "commissionPlanOffered": null, "commissionPlan": null, "salary": { "decimal": "95000", "currencyCode": "USD" }, "paidHolidayDays": null, "bonuses": [], "allowances": [], "reimbursementBudgets": [], "remoteWorkCosts": null, "privateNotes": null, "sickPay": null }, "documents": [], "signer": null } } ``` ### Optional steps Depending on the desired contract conditions, the following optional endpoints can be used: * [Upload Employment Work Permit](https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-work-permit) - used if the employment requires a work permit for the employment country. This can be deleted using the [Delete the uploaded employment work permit](https://docs.oysterhr.com/reference/delete_v1-hiring-employments-id-work-permit) endpoint. * [Upload Employment Commission Plan](https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-commission-plan) - This API endpoint allows you to upload a custom commission plan for the employment. This can be deleted using the [Delete The Uploaded Employment Commission Plan](https://docs.oysterhr.com/reference/delete_v1-hiring-employments-id-commission-plan) endpoint. * [Upload Employment Document](https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-document) - This API endpoint allows you to upload any additional documents for the employment. This can be deleted using the [Delete The Uploaded Employment Document](https://docs.oysterhr.com/reference/delete_v1-hiring-employments-id-document-document-id) endpoint. * [Provision benefits](https://docs.oysterhr.com/v0.1/reference/put_v0-1-benefits-employments-employment-id-provisionings) - This API endpoint, in conjunction with the [Retrieve an employment's available benefits offerings](https://docs.oysterhr.com/v0.1/reference/get_v0-1-benefits-employments-employment-id-offerings) endpoint allow you to configure any non-statutory benefits for the employment. *** ## **3. Submit Employment** Once all the necessary information is submitted, you can [submit the employment](https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-submit) for processing. This marks the employment as `In Progress`, at which point the employment onboarding can take place before the contracts are sent out for signature. ### **Example Request** ```bash curl --request POST \ --url https://api.oysterhr.com/v0.1/hiring/employments/urY7zKOm/submit \ --header 'accept: application/json' \ --header 'authorization: Bearer BEARER_TOKEN_GOES_HERE' ``` ### **Response** If successful, you will receive a 200 response with the employment information. ### **Example Response** ```json { "data": { "engagementId": "urY7zKOm", "countryCode": "US", "subdivisionCode": "CA", "personalDetails": { "fullLegalName": "Test Hire", "email": "test@test.com", "nationality": "US", "workPermit": null }, "manager": { "managerRole": null, "managerName": null, "managerEmailAddress": null, "managerPhoneNumber": null, "managerIsExpenseApprover": false }, "role": { "newHireStatus": "new_hire", "seniorityLevel": "SENIOR", "roleTypeId": 05, "role": "Senior Software Engineer", "jobDescription": "job description", "startDate": "2024-10-14", "endDate": null, "employmentType": "FULL_TIME", "probationPeriod": { "value": 12, "unit": "MONTHS" }, "terminationNotice": null, "resignationNotice": null, "fullTimeHoursPerWeek": 40 }, "compensation": { "commissionPlanOffered": null, "commissionPlan": null, "salary": { "decimal": "95000", "currencyCode": "USD" }, "paidHolidayDays": 14, "bonuses": [], "allowances": [], "reimbursementBudgets": [], "remoteWorkCosts": { "allowancePolicy": { "allowancePolicy": "MONTHLY_ALLOWANCE", "amount": null, "statutoryAmount": null }, "equipmentBudget": null, "equipmentListOwnedByTeamMember": null, "equipmentListProvidedByCustomer": { "equipmentList": [ "KEYBOARD", "MOUSE", "PRINTER" ], "equipmentOther": null }, "equipmentOneTimePayment": null }, "privateNotes": null, "sickPay": null }, "documents": [], "signer": { "fullName": "Graham Vandervort", "email": "graham.v@test.com", "jobTitle": "Engineering Manager", "phone": { "countryCode": "US", "number": "555 654 5568" } } } } ``` ### Notes: * Unless [otherwise configured](https://docs.oysterhr.com/docs/creating-and-submitting-an-eor-employment#optional-steps) using the Benefits API or UI, hires submitted via API will have statutory Benefits applied. *** ## **Conclusion** Once you have successfully submitted an employment and it is in the `In Progress` state, the employment onboarding can begin. That can either be achieved via the platform by sending the team member an invitation or via API by following the [Completing EOR employment onboarding via API](https://docs.oysterhr.com/docs/completing-eor-employment-onboarding-via-api) guide.