> 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/create-gp-employment.md).
# Create GP Employment
Create and onboard Global Payroll employees
## Get employee creation form schema
> Returns the form schema (field definitions and validation rules) needed to create an employee\
> under a specific employment context.\
> \
> The schema describes required and optional fields, their types, validation constraints,\
> and allowed values for the given context.\
> \
> \*\*Context Types:\*\*\
> \- \*\*GP Employment\*\*: Provide \`entity\` to get the schema for a Global Payroll employee creation.
```json
{"openapi":"3.0.1","info":{"title":"Multiplier Public REST API","version":"1.0.0"},"tags":[{"name":"Create GP Employment","description":"Create and onboard Global Payroll employees"}],"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":{"EmploymentType":{"type":"string","description":"Type of employment context","enum":["GLOBAL_PAYROLL"]},"V1GetEmployeeDynamicDetailsSchemaResponse":{"required":["customFields","legalDetails"],"type":"object","properties":{"legalDetails":{"$ref":"#/components/schemas/EmployeeSchemaSection"},"customFields":{"$ref":"#/components/schemas/EmployeeSchemaSection"}}},"EmployeeSchemaSection":{"required":["fields","required"],"type":"object","properties":{"required":{"type":"boolean","description":"Whether the section is required"},"fields":{"type":"array","description":"List of fields in the section","items":{"$ref":"#/components/schemas/FieldDefinition"}}}},"FieldDefinition":{"required":["key","required","type"],"type":"object","properties":{"key":{"type":"string","description":"Machine-readable field key"},"label":{"type":"string","description":"Human-readable field label"},"type":{"type":"string","description":"Definition type"},"required":{"type":"boolean","description":"Whether the Definition is required"}},"discriminator":{"propertyName":"type","mapping":{"TEXT":"#/components/schemas/TextDefinition","NUMBER":"#/components/schemas/NumberDefinition","BOOLEAN":"#/components/schemas/BooleanDefinition","DATE":"#/components/schemas/DateDefinition","SELECT":"#/components/schemas/SelectDefinition"}}},"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/dynamic-details/schema":{"get":{"tags":["Create GP Employment"],"summary":"Get employee creation form schema","description":"Returns the form schema (field definitions and validation rules) needed to create an employee\nunder a specific employment context.\n\nThe schema describes required and optional fields, their types, validation constraints,\nand allowed values for the given context.\n\n**Context Types:**\n- **GP Employment**: Provide `entity` to get the schema for a Global Payroll employee creation.\n","operationId":"getEmployeeDynamicDetailsSchema","parameters":[{"name":"employmentType","in":"query","description":"Type of employment. Required for all contexts.\n","required":true,"style":"form","explode":true,"schema":{"$ref":"#/components/schemas/EmploymentType"}},{"name":"entity","in":"query","description":"Legal entity name. Required for GP employment context.\nWhen provided, the schema returned is for creating a GP employee under this entity.\n","required":false,"style":"form","explode":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Form schema retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1GetEmployeeDynamicDetailsSchemaResponse"}}}},"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"}}}},"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"}}}}}}}}}
```
## Create a GP (Global Payroll) employee
> Creates, onboards a Global Payroll employee in a single call.\
> \
> Handles the full onboarding flow including personal details, contact information,\
> employment terms, compensation, and compliance setup.
```json
{"openapi":"3.0.1","info":{"title":"Multiplier Public REST API","version":"1.0.0"},"tags":[{"name":"Create GP Employment","description":"Create and onboard Global Payroll employees"}],"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":{"V1GpEmploymentsPostRequest":{"required":["compensation","contact","employment","personal"],"type":"object","properties":{"personal":{"$ref":"#/components/schemas/V1GpEmploymentsPersonalInput"},"contact":{"$ref":"#/components/schemas/V1GpEmploymentsContactInput"},"employment":{"$ref":"#/components/schemas/V1GpEmploymentsEmploymentInput"},"compensation":{"$ref":"#/components/schemas/V1GpEmploymentsCompensationInput"},"address":{"$ref":"#/components/schemas/V1GpEmploymentsAddressInput"}}},"V1GpEmploymentsPersonalInput":{"required":["dateOfBirth","firstName","fullLegalName","gender","lastName"],"type":"object","properties":{"firstName":{"type":"string","description":"Employee's first name"},"middleName":{"type":"string","description":"Employee's middle name (optional)","nullable":true},"lastName":{"type":"string","description":"Employee's last name"},"fullLegalName":{"type":"string","description":"Employee's full legal name"},"nameInNativeLanguage":{"type":"string","description":"Employee's name in native language"},"dateOfBirth":{"type":"string","description":"Employee's date of birth (YYYY-MM-DD)","format":"date"},"gender":{"type":"string","description":"Employee's gender","enum":["FEMALE","MALE","UNSPECIFIED"]},"maritalStatus":{"type":"string","description":"Employee's marital status","enum":["DIVORCED","MARRIED","SINGLE","UNSPECIFIED"]},"religion":{"type":"string","description":"Employee's religion (optional)","nullable":true},"nationality":{"pattern":"^[A-Z]{3}$","type":"string","description":"Employee's nationality. ISO 3166-1 alpha-3 country code"}}},"V1GpEmploymentsContactInput":{"required":["personalEmail"],"type":"object","properties":{"personalEmail":{"type":"string","description":"Employee's personal email address","format":"email"},"personalPhoneNumber":{"pattern":"^\\+[1-9]\\d{1,14}$","type":"string","description":"Employee's personal phone number"},"emergencyContact":{"required":["name","phoneNumber","relationship"],"type":"object","properties":{"name":{"type":"string","description":"Name of the emergency contact person"},"phoneNumber":{"pattern":"^\\+[1-9]\\d{1,14}$","type":"string","description":"Phone number of the emergency contact"},"relationship":{"type":"string","description":"Relationship to the employee","enum":["SPOUSE","DAUGHTER","SON","FATHER","MOTHER"]}},"description":"Emergency contact information","nullable":true}}},"V1GpEmploymentsEmploymentInput":{"required":["department","designation","employeeCode","entity","startDate","term"],"type":"object","properties":{"employeeCode":{"type":"string","description":"Human-readable employee code"},"entity":{"type":"string","description":"Legal entity name for the employee's employment"},"workEmail":{"type":"string","description":"Employee's work email address","format":"email"},"startDate":{"type":"string","description":"Date when employee joined the company (YYYY-MM-DD)","format":"date"},"term":{"type":"string","description":"Employment term (fixed-term or permanent)","enum":["FIXED","PERMANENT"]},"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"},"reportsTo":{"type":"string","description":"Work email of the manager/supervisor","format":"email"}}},"V1GpEmploymentsCompensationInput":{"required":["baseSalary"],"type":"object","properties":{"baseSalary":{"$ref":"#/components/schemas/V2CompensationComponent"},"additionalPays":{"type":"array","items":{"$ref":"#/components/schemas/V2CompensationComponent"}}}},"V2CompensationComponent":{"required":["billingRate","billingRateType","currency","frequency","name","payScheduleName","startDate"],"type":"object","properties":{"name":{"type":"string","description":"Name of the compensation component"},"billingRate":{"type":"number","description":"Amount/rate of the compensation component"},"billingRateType":{"type":"string","description":"Rate type of the compensation component.","enum":["VALUE","PERC_BASE_PAY","BASE_PAY_DAYS","CTC_DAYS","CTC_PERCENTAGE","EARNINGS_PERCENTAGE","BASIC_SALARY_PERCENTAGE","QUALIFYING_EARNINGS_PERCENTAGE"]},"currency":{"pattern":"^[A-Z]{3}$","type":"string","description":"ISO 4217 currency code"},"frequency":{"type":"string","description":"Payment frequency","enum":["WEEKLY","SEMIMONTHLY","BIWEEKLY","MONTHLY","ANNUALLY","SEMIANNUALLY","QUARTERLY","DAILY","ONETIME","HOURLY"]},"payScheduleName":{"type":"string","description":"Pay schedule name of the compensation component"},"startDate":{"type":"string","description":"Start date of the compensation component. YYYY-MM-DD","format":"date"},"endDate":{"type":"string","description":"End date of the compensation component. YYYY-MM-DD","format":"date","nullable":true},"isInstallment":{"type":"boolean","description":"Whether the compensation component is an installment. Defaults to false.","nullable":true},"numberOfInstallments":{"minimum":1,"type":"integer","description":"Number of installments.","nullable":true},"notes":{"type":"string","description":"Notes for the compensation component","nullable":true}}},"V1GpEmploymentsAddressInput":{"type":"object","properties":{"addressLine1":{"maxLength":200,"minLength":1,"type":"string","description":"Address line 1 (street address)"},"addressLine2":{"maxLength":200,"type":"string","description":"Address line 2 (apartment, suite, etc.) - optional","nullable":true},"streetName":{"maxLength":200,"type":"string","description":"Street name (optional)","nullable":true},"city":{"maxLength":100,"minLength":1,"type":"string","description":"City name"},"subdivision":{"maxLength":100,"type":"string","description":"State, province, or canton (optional)","nullable":true},"country":{"pattern":"^[A-Z]{3}$","type":"string","description":"Country (ISO 3166-1 alpha-3 code)"},"postalCode":{"maxLength":20,"minLength":1,"type":"string","description":"Postal or ZIP code"}}},"V1GpEmploymentsPostResponse":{"required":["id"],"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the employee","format":"uuid"}}},"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/gp-employments":{"post":{"tags":["Create GP Employment"],"summary":"Create a GP (Global Payroll) employee","description":"Creates, onboards a Global Payroll employee in a single call.\n\nHandles the full onboarding flow including personal details, contact information,\nemployment terms, compensation, and compliance setup.\n","operationId":"createGpEmployment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1GpEmploymentsPostRequest"}}},"required":true},"responses":{"201":{"description":"GP employee created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1GpEmploymentsPostResponse"}}}},"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"}}}}}}}}}
```
## Submit dynamic data for employee creation
> Submits dynamic field values (as required by the schema returned from \`GET /v1/employees/schema\`)\
> for a GP employment record.\
> \
> Use this endpoint \*\*after\*\* getting the schema to know which fields are required, and after\
> creating the basic employment record. The submitted values populate the dynamic sections:\
> legal details and custom fields.
```json
{"openapi":"3.0.1","info":{"title":"Multiplier Public REST API","version":"1.0.0"},"tags":[{"name":"Create GP Employment","description":"Create and onboard Global Payroll employees"}],"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":{"V1SubmitEmployeesDynamicDetailsRequest":{"type":"object","properties":{"legalDetails":{"type":"object","additionalProperties":{"type":"string"},"description":"Flat key-value map of legal detail field values as defined by the schema.\nKeys correspond to `key` fields returned in `legalDetails.fields` from `GET /v1/employees/schema`.\n"},"customFields":{"type":"object","additionalProperties":{"type":"string"},"description":"Flat key-value map of custom field values as defined by the schema.\nKeys correspond to `key` fields returned in `customFields.fields` from `GET /v1/employees/schema`.\n"}}},"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}/dynamic-details":{"patch":{"tags":["Create GP Employment"],"summary":"Submit dynamic data for employee creation","description":"Submits dynamic field values (as required by the schema returned from `GET /v1/employees/schema`)\nfor a GP employment record.\n\nUse this endpoint **after** getting the schema to know which fields are required, and after\ncreating the basic employment record. The submitted values populate the dynamic sections:\nlegal details and custom fields.\n","operationId":"submitEmployeeDynamicDetails","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/V1SubmitEmployeesDynamicDetailsRequest"}}},"required":true},"responses":{"204":{"description":"Dynamic data submitted successfully"},"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"}}}}}}}}}
```
---
# 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/create-gp-employment.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.