--- updatedAt: 2026-05-14T14:32:15.000Z agentTools: projectIndex: https://docs.oysterhr.com/v0.1/llms.txt --- # Create employment This API endpoint allows you to create a new employment record within your system and receive a complete response with the created record details. **This endpoint requires the `X-Oyster-Actor-Email` header when using client credentials authentication.** More details in this guide on creating and submitting an EOR employment. # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "Endpoints", "version": "v0.1" }, "components": { "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer" } }, "schemas": { "amount": { "type": "object", "properties": { "decimal": { "type": "string", "pattern": "^\\d+([.]\\d+)?$" }, "currencyCode": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "decimal", "currencyCode" ] }, "employmentPersonalDetails": { "type": "object", "properties": { "fullLegalName": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "workPermit": { "type": "object", "nullable": true, "properties": { "url": { "type": "string" } } } }, "required": [ "fullLegalName", "email", "nationality", "workPermit" ] }, "employment": { "type": "object", "properties": { "engagementId": { "type": "string" }, "countryCode": { "type": "string", "nullable": true }, "subdivisionCode": { "type": "string", "nullable": true }, "status": { "type": "string" }, "personalDetails": { "type": "object", "nullable": true, "$ref": "#/components/schemas/employmentPersonalDetails" }, "manager": { "type": "object", "properties": { "managerRole": { "type": "string", "nullable": true }, "managerName": { "type": "string", "nullable": true }, "managerEmailAddress": { "type": "string", "nullable": true }, "managerPhoneNumber": { "type": "string", "nullable": true }, "managerIsExpenseApprover": { "type": "boolean" } }, "required": [ "managerRole", "managerName", "managerEmailAddress", "managerPhoneNumber", "managerIsExpenseApprover" ] }, "role": { "type": "object", "properties": { "seniorityLevel": { "type": "string", "nullable": true }, "roleTypeId": { "type": "string", "nullable": true }, "role": { "type": "string", "nullable": true }, "jobDescription": { "type": "string", "nullable": true }, "startDate": { "type": "string", "format": "date", "nullable": true }, "initialStartDate": { "type": "string", "format": "date", "nullable": true }, "endDate": { "type": "string", "format": "date", "nullable": true }, "employmentType": { "type": "string", "nullable": true }, "cbaLevel": { "type": "string", "nullable": true }, "probationPeriod": { "type": "object", "nullable": true }, "terminationNotice": { "type": "object", "nullable": true }, "resignationNotice": { "type": "object", "nullable": true }, "fullTimeHoursPerWeek": { "type": "number", "format": "float", "nullable": true }, "partTimeDaysPerWeek": { "type": "number", "nullable": true }, "partTimeHoursPerDay": { "type": "number", "nullable": true }, "workSchedule": { "type": "array", "description": "Per-day work schedule. Present for employments whose country supports work schedules.", "items": { "type": "object", "properties": { "day": { "type": "string", "enum": [ "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY" ] }, "fromTime": { "type": "string", "format": "time", "description": "Working hours start time, in HH:MM format (e.g. 09:00)." }, "toTime": { "type": "string", "format": "time", "description": "Working hours end time, in HH:MM format (e.g. 17:00)." } }, "required": [ "day", "fromTime", "toTime" ] } } }, "required": [ "seniorityLevel", "roleTypeId", "role", "jobDescription", "startDate", "initialStartDate", "endDate", "employmentType", "probationPeriod", "terminationNotice", "resignationNotice" ] }, "compensation": { "type": "object", "properties": { "commissionPlanOffered": { "type": "boolean", "nullable": true }, "commissionPlan": { "type": "object", "nullable": true, "properties": { "url": { "type": "string", "nullable": true } } }, "salary": { "type": "object", "properties": { "decimal": { "type": "string", "nullable": true }, "currencyCode": { "type": "string", "nullable": true } } }, "paidHolidayDays": { "type": "number", "nullable": true }, "bonuses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "paymentFrequency": { "type": "string" }, "guaranteed": { "type": "boolean" }, "statutory": { "type": "boolean" }, "amountAsPercentage": { "type": "string" }, "amountDecimal": { "type": "string" }, "selectedMonths": { "type": "array", "items": { "type": "integer" } }, "prorated": { "type": "boolean" } }, "required": [ "id", "label", "paymentFrequency", "guaranteed", "statutory" ] } }, "allowances": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "paymentFrequency": { "type": "string" }, "statutory": { "type": "boolean" }, "amountAsPercentage": { "type": "string" }, "amountDecimal": { "type": "string" }, "selectedMonths": { "type": "array", "items": { "type": "integer" } }, "prorated": { "type": "boolean" } }, "required": [ "id", "label", "paymentFrequency", "statutory" ] } }, "reimbursementBudgets": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "customLabel": { "type": "string", "nullable": true }, "resetFrequency": { "type": "string" }, "amountDecimal": { "type": "boolean" } }, "required": [ "label", "customLabel", "resetFrequency", "amountDecimal" ] } }, "remoteWorkCosts": { "type": "object", "nullable": true, "properties": { "allowancePolicy": { "type": "object", "properties": { "allowancePolicy": { "type": "string", "enum": [ "MONTHLY_ALLOWANCE", "ONE_TIME_STIPEND", "BASIC_REIMBURSEMENT", "NO_REIMBURSEMENT" ] }, "amount": { "$ref": "#/components/schemas/amount", "nullable": true }, "statutoryAmount": { "$ref": "#/components/schemas/amount", "nullable": true } }, "required": [ "allowancePolicy", "amount", "statutoryAmount" ] }, "equipmentBudget": { "type": "object", "nullable": true, "properties": { "amount": { "$ref": "#/components/schemas/amount", "nullable": true } }, "required": [ "amount" ] }, "equipmentListOwnedByTeamMember": { "type": "object", "nullable": true, "properties": { "equipmentList": { "type": "array", "items": { "type": "string", "enum": [ "COMPUTER_MONITOR", "HEADSET", "KEYBOARD", "LAPTOP_COMPUTER", "MOBILE_PHONE", "MOUSE", "PRINTER", "OTHER" ] } }, "equipmentOther": { "type": "string", "nullable": true } }, "required": [ "equipmentList", "equipmentOther" ] }, "equipmentListProvidedByCustomer": { "type": "object", "nullable": true, "properties": { "equipmentList": { "type": "array", "items": { "type": "string", "enum": [ "COMPUTER_MONITOR", "HEADSET", "KEYBOARD", "LAPTOP_COMPUTER", "MOBILE_PHONE", "MOUSE", "PRINTER", "OTHER" ] } }, "equipmentOther": { "type": "string", "nullable": true } }, "required": [ "equipmentList", "equipmentOther" ] }, "equipmentOneTimePayment": { "type": "object", "nullable": true, "properties": { "amount": { "$ref": "#/components/schemas/amount", "nullable": true } }, "required": [ "amount" ] } }, "required": [ "allowancePolicy", "equipmentBudget", "equipmentListOwnedByTeamMember", "equipmentListProvidedByCustomer", "equipmentOneTimePayment" ] }, "privateNotes": { "type": "string", "nullable": true }, "sickPay": { "type": "object", "nullable": true, "properties": { "option": { "type": "string" }, "customDuration": { "type": "object", "nullable": true, "properties": { "value": { "type": "integer" }, "unit": { "type": "string", "enum": [ "DAYS", "WEEKS", "MONTHS" ] } } } }, "required": [ "option", "customDuration" ] } }, "required": [ "commissionPlanOffered", "commissionPlan", "salary", "paidHolidayDays", "bonuses", "allowances", "reimbursementBudgets", "remoteWorkCosts", "privateNotes", "sickPay" ] }, "documents": { "type": "array", "items": { "type": "object", "properties": { "documentId": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "filename": { "type": "string" } }, "required": [ "documentId", "title", "url", "filename" ] } }, "signer": { "type": "object", "nullable": true, "properties": { "fullName": { "type": "string" }, "email": { "type": "string" }, "jobTitle": { "type": "string" }, "phone": { "type": "object", "properties": { "countryCode": { "type": "string" }, "number": { "type": "string" } }, "required": [ "countryCode", "number" ] } }, "required": [ "fullName", "email", "jobTitle", "phone" ] }, "invitation": { "type": "object", "nullable": true, "properties": { "email": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "sentAt": { "type": "string", "format": "date", "nullable": true } }, "required": [ "email", "name", "sentAt" ] } }, "required": [ "engagementId", "countryCode", "subdivisionCode", "status", "personalDetails", "manager", "role", "compensation", "documents", "signer", "invitation" ] }, "fieldErrors": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } } }, "required": [ "errors" ] } } }, "paths": { "/v0.1/hiring/employments": { "post": { "summary": "Create employment", "tags": [ "Employments" ], "description": "This API endpoint allows you to create a new employment record within your system and receive a complete response with the created record details.\n\n**This endpoint requires the `X-Oyster-Actor-Email` header when using client credentials authentication.**", "security": [ { "bearer_auth": [ "manage" ] } ], "parameters": [], "responses": { "200": { "description": "Successfully created employment", "content": { "application/json": { "examples": { "Successfully created employment": { "value": { "data": { "engagementId": "A5540727", "countryCode": "US", "subdivisionCode": "CA", "status": "DRAFT", "billingFrequency": "MONTHLY", "personalDetails": { "fullLegalName": "John Doe", "email": "john@example.com", "nationality": "US", "workPermit": null }, "manager": { "managerRole": null, "managerName": null, "managerEmailAddress": null, "managerPhoneNumber": null, "managerIsExpenseApprover": false }, "role": { "seniorityLevel": null, "roleTypeId": null, "role": null, "jobDescription": null, "dailyResponsibility": null, "primaryDuty": null, "decisionMakingAuthority": null, "minimumQualification": null, "startDate": null, "initialStartDate": null, "endDate": null, "employmentType": null, "cbaLevel": null, "probationPeriod": null, "terminationNotice": null, "resignationNotice": null }, "compensation": { "commissionPlanOffered": null, "commissionPlan": null, "salary": { "decimal": null, "currencyCode": null }, "hourlyRate": null, "salaryPeriod": "ANNUAL", "paidHolidayDays": null, "bonuses": [], "allowances": [], "reimbursementBudgets": [], "remoteWorkCosts": null, "privateNotes": null, "sickPay": null }, "documents": [], "signer": null, "invitation": { "email": "john@example.com", "name": "John Doe", "sentAt": null } } } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/employment" } }, "required": [ "data" ] } } } }, "422": { "description": "Unprocessable entity", "content": { "application/json": { "examples": { "Unprocessable entity": { "value": { "errors": [ { "field": "countryCode", "message": "Unable to hire in Afghanistan (AF)" } ] } } }, "schema": { "$ref": "#/components/schemas/fieldErrors" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "subdivisionCode": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 3 }, "personalDetails": { "type": "object", "properties": { "fullLegalName": { "type": "string", "minLength": 3, "maxLength": 100 }, "email": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9.!\\\\#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$" }, "nationality": { "type": "string", "minLength": 2, "maxLength": 2 } }, "required": [ "fullLegalName", "email", "nationality" ] }, "billingFrequency": { "type": "string", "minLength": 1, "enum": [ "MONTHLY", "YEARLY" ] } }, "required": [ "countryCode", "subdivisionCode", "personalDetails" ] }, "examples": { "Successfully created employment": { "summary": "Successfully created employment", "value": { "personalDetails": { "fullLegalName": "John Doe", "email": "john@example.com", "nationality": "US" }, "countryCode": "US", "subdivisionCode": "CA" } } } } } } } } }, "servers": [ { "url": "https://api.oysterhr.com", "description": "Production server" }, { "url": "https://api-sandbox.oysterhr.com", "description": "Sandbox server" } ] } ```