> For the complete documentation index, see [llms.txt](https://developer.usemultiplier.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.usemultiplier.com/api-reference/employee-management/employee-employment-details.md).
# Employee Employment Details
Access employee employment history and status
## Retrieve employee employment details
> Get comprehensive employment information including job details,\
> employment status, and work history.\
> \
> This endpoint provides access to the employee's current employment details\
> and reporting structure.
```json
{"openapi":"3.0.1","info":{"title":"Multiplier Public REST API","version":"1.0.0"},"tags":[{"name":"Employee Employment Details","description":"Access employee employment history and status"}],"servers":[{"url":"https://api.usemultiplier.com","description":"Production API / Partner Sandbox"},{"url":"https://release-api-gateway.api.usemultiplier.com","description":"MPL internal release environment"},{"url":"https://api-gateway.api.acc.staging.usemultiplier.com","description":"MPL internal staging"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"JWT Bearer token authentication.\n\nTo authenticate:\n1. Obtain a JWT token from your authentication endpoint\n2. Click the \"Authorize\" button above\n3. Enter your token in the format: your-jwt-token\n4. Click \"Authorize\" to apply to all requests\n\nThe token will be automatically included in the Authorization header\nas: Authorization: Bearer {token}\n","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"V1EmployeesEmployeeIdEmploymentGetResponse":{"type":"object","properties":{"employeeCode":{"type":"string","description":"Human-readable employee code (optional)","nullable":true},"employeeId":{"type":"string","description":"Deprecated: Use employeeCode instead. Human-readable employee code (optional)","nullable":true,"deprecated":true},"workEmail":{"type":"string","description":"Employee's work email address","format":"email","nullable":true},"entity":{"type":"string","description":"Legal entity name for the employee's employment","nullable":true},"startDate":{"type":"string","description":"Date when employee joined the company (YYYY-MM-DD)","format":"date"},"status":{"type":"string","description":"Current employment status","enum":["ONBOARDING","ACTIVE","OFFBOARDING","ENDED","DELETED","UNKNOWN"]},"endDate":{"type":"string","description":"Date when employee left or will leave the company (optional)","format":"date","nullable":true},"designation":{"type":"string","description":"Job title or position"},"department":{"type":"string","description":"Department name (optional)","nullable":true},"type":{"type":"string","description":"Type of employment","enum":["EMPLOYEE","HR_MEMBER","FREELANCER","CONTRACTOR","UNKNOWN"]},"term":{"type":"string","description":"Employment term (fixed-term or permanent)","enum":["FIXED","PERMANENT","UNKNOWN"]},"noticePeriod":{"type":"object","properties":{"value":{"type":"string","description":"Notice period value"},"unit":{"type":"string","description":"Notice period unit","enum":["DAYS","WEEKS","MONTHS","UNKNOWN"]}},"description":"Notice period details (optional).","nullable":true},"exitDetails":{"type":"object","properties":{"type":{"type":"string","description":"Type of termination","enum":["RESIGNATION","TERMINATION","DID_NOT_JOIN","UNKNOWN"]},"reason":{"type":"string","description":"Reason for termination (optional)","nullable":true},"dateOfTermination":{"type":"string","description":"Last working day for terminated employees (optional)","format":"date","nullable":true}},"description":"Exit details for offboarded employees (optional)","nullable":true},"reportsTo":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the manager","format":"uuid"},"firstName":{"type":"string","description":"Manager's first name","nullable":true},"lastName":{"type":"string","description":"Manager's last name","nullable":true},"designation":{"type":"string","description":"Manager's job designation/position","nullable":true}},"description":"Manager/supervisor information for this employee","nullable":true}}},"ErrorResponse":{"required":["code","correlationId","message","path","timestamp"],"type":"object","properties":{"timestamp":{"type":"string","description":"ISO-8601 UTC timestamp of when the error occurred","format":"date-time"},"code":{"type":"string","description":"Machine-readable error category","enum":["BAD_REQUEST","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","CONFLICT","VALIDATION_ERROR","SERVICE_UNAVAILABLE","INTERNAL_SERVER_ERROR"]},"message":{"type":"string","description":"Human-readable description of the error"},"path":{"type":"string","description":"Request URI that produced the error"},"correlationId":{"type":"string","description":"Trace ID for correlating this error in logs"},"errors":{"type":"array","description":"Field-level error details. Present for validation errors; may be present for other errors.","items":{"$ref":"#/components/schemas/ErrorItem"}},"error":{"description":"Deprecated: Use errors instead. Backward-compatible error object.","nullable":true,"deprecated":true,"allOf":[{"$ref":"#/components/schemas/LegacyError"}]}}},"ErrorItem":{"required":["message"],"type":"object","properties":{"property":{"type":"string","description":"The field that caused the error (only present for validation errors)"},"message":{"type":"string","description":"Description of the error"}}},"LegacyError":{"required":["code","message"],"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"array","description":"Field-level error details. Only present for validation errors.","nullable":true,"items":{"$ref":"#/components/schemas/LegacyFieldError"}}},"deprecated":true},"LegacyFieldError":{"required":["field","message"],"type":"object","properties":{"field":{"type":"string","description":"The field that caused the error"},"message":{"type":"string","description":"Description of the field error"}},"deprecated":true}}},"paths":{"/v1/employees/{employeeId}/employment":{"get":{"tags":["Employee Employment Details"],"summary":"Retrieve employee employment details","description":"Get comprehensive employment information including job details,\nemployment status, and work history.\n\nThis endpoint provides access to the employee's current employment details\nand reporting structure.\n","operationId":"getEmployeeEmploymentDetails","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Employee employment details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdEmploymentGetResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Update employee employment details
> Update employment details for a specific employee.\
> \
> This endpoint allows partial updates to employment information. Only the fields\
> provided in the request body will be updated; other fields remain unchanged.\
> \
> \*\*Important:\*\* At least one field must be provided in the request body.\
> Empty requests (no-op operations) are not allowed and will return a 400 Bad Request.\
> \
> \*\*Currently Supported Fields (Phase 1):\*\*\
> \- \`employeeCode\` - The employee's unique identifier code within the organization\
> \
> \*\*Future Fields (Planned):\*\*\
> \- \`designation\` - Job title or position\
> \- \`department\` - Department name\
> \- \`workEmail\` - Work email address\
> \- \`noticePeriod\` - Notice period details\
> \
> \*\*Read-Only Fields (Not Updatable):\*\*\
> Fields such as \`entity\`, \`startDate\`, \`endDate\`, \`status\`, \`type\`, and \`term\`\
> are managed through other processes and cannot be updated via this endpoint.
```json
{"openapi":"3.0.1","info":{"title":"Multiplier Public REST API","version":"1.0.0"},"tags":[{"name":"Employee Employment Details","description":"Access employee employment history and status"}],"servers":[{"url":"https://api.usemultiplier.com","description":"Production API / Partner Sandbox"},{"url":"https://release-api-gateway.api.usemultiplier.com","description":"MPL internal release environment"},{"url":"https://api-gateway.api.acc.staging.usemultiplier.com","description":"MPL internal staging"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"JWT Bearer token authentication.\n\nTo authenticate:\n1. Obtain a JWT token from your authentication endpoint\n2. Click the \"Authorize\" button above\n3. Enter your token in the format: your-jwt-token\n4. Click \"Authorize\" to apply to all requests\n\nThe token will be automatically included in the Authorization header\nas: Authorization: Bearer {token}\n","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"V1EmployeesEmployeeIdEmploymentPatchRequest":{"minProperties":1,"type":"object","properties":{"employeeCode":{"maxLength":50,"minLength":1,"pattern":"^[a-zA-Z0-9\\-_]+$","type":"string","description":"The employee's unique identifier code within the organization.\nMust be alphanumeric with hyphens and underscores allowed.\n"}},"additionalProperties":false,"description":"Request body for updating employee employment details.\nCurrently supports updating employeeCode only (Phase 1).\nAdditional fields will be added in future phases.\n\nAt least one field must be provided; empty requests are not allowed.\n"},"V1EmployeesEmployeeIdEmploymentPatchResponse":{"required":["employeeCode","employeeId"],"type":"object","properties":{"employeeId":{"type":"string","description":"Unique identifier for the employee (employment public ID)","format":"uuid"},"employeeCode":{"type":"string","description":"The updated employee code"}},"description":"Response after successfully updating employee employment details."},"ErrorResponse":{"required":["code","correlationId","message","path","timestamp"],"type":"object","properties":{"timestamp":{"type":"string","description":"ISO-8601 UTC timestamp of when the error occurred","format":"date-time"},"code":{"type":"string","description":"Machine-readable error category","enum":["BAD_REQUEST","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","CONFLICT","VALIDATION_ERROR","SERVICE_UNAVAILABLE","INTERNAL_SERVER_ERROR"]},"message":{"type":"string","description":"Human-readable description of the error"},"path":{"type":"string","description":"Request URI that produced the error"},"correlationId":{"type":"string","description":"Trace ID for correlating this error in logs"},"errors":{"type":"array","description":"Field-level error details. Present for validation errors; may be present for other errors.","items":{"$ref":"#/components/schemas/ErrorItem"}},"error":{"description":"Deprecated: Use errors instead. Backward-compatible error object.","nullable":true,"deprecated":true,"allOf":[{"$ref":"#/components/schemas/LegacyError"}]}}},"ErrorItem":{"required":["message"],"type":"object","properties":{"property":{"type":"string","description":"The field that caused the error (only present for validation errors)"},"message":{"type":"string","description":"Description of the error"}}},"LegacyError":{"required":["code","message"],"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"array","description":"Field-level error details. Only present for validation errors.","nullable":true,"items":{"$ref":"#/components/schemas/LegacyFieldError"}}},"deprecated":true},"LegacyFieldError":{"required":["field","message"],"type":"object","properties":{"field":{"type":"string","description":"The field that caused the error"},"message":{"type":"string","description":"Description of the field error"}},"deprecated":true}}},"paths":{"/v1/employees/{employeeId}/employment":{"patch":{"tags":["Employee Employment Details"],"summary":"Update employee employment details","description":"Update employment details for a specific employee.\n\nThis endpoint allows partial updates to employment information. Only the fields\nprovided in the request body will be updated; other fields remain unchanged.\n\n**Important:** At least one field must be provided in the request body.\nEmpty requests (no-op operations) are not allowed and will return a 400 Bad Request.\n\n**Currently Supported Fields (Phase 1):**\n- `employeeCode` - The employee's unique identifier code within the organization\n\n**Future Fields (Planned):**\n- `designation` - Job title or position\n- `department` - Department name\n- `workEmail` - Work email address\n- `noticePeriod` - Notice period details\n\n**Read-Only Fields (Not Updatable):**\nFields such as `entity`, `startDate`, `endDate`, `status`, `type`, and `term`\nare managed through other processes and cannot be updated via this endpoint.\n","operationId":"updateEmployeeEmploymentDetails","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdEmploymentPatchRequest"}}},"required":true},"responses":{"200":{"description":"Employee employment details updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdEmploymentPatchResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - resource already exists or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developer.usemultiplier.com/api-reference/employee-management/employee-employment-details.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.