> ## Documentation Index > Fetch the complete documentation index at: https://docs.getprimo.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an employee creation intent > Create the employee of an onboarding as a task the ticket tracks, from the HR information (name, emails, phone, start date, job, legal entity, work location, teams, manager, address). Creates the intent and its EMPLOYEE_CREATION task. Without `scheduleDate` the employee is created right away — a real employee and Clerk user, so confirm the information first; with one, the task sleeps until that date and the employee is created when it wakes up — nobody has to execute it. A field you leave out is read from the onboarding HRIS record, so send only what differs from it; null clears a field. Read the returned intent to see what was filled in. Pass the ticket the task belongs to as `parentTicketId`; without one Primo opens a ticket for it. `createTicket` and `createTask` cannot make a typed task. Returns the intent `id`, its `taskId` and the `ticketId` holding it. When the employee cannot be created (for instance `EMPLOYEE_INFORMATION_INCOMPLETE`), the task stays PENDING with an internal comment: fix the intent with `updateEmployeeCreationIntent`, then `executeEmployeeCreationIntent`. The task cannot be marked done by hand: `updateTaskStatus` refuses it, and it completes once Primo has created the employee. `createEmployee` only creates a record with no onboarding or task, and `completeOnboarding` closes the whole onboarding without this task; use the employee creation intent for an EMPLOYEE_CREATION task a ticket tracks. Refused with `ONBOARDING_NOT_FOUND`, `ONBOARDING_HAS_EMPLOYEE_CREATION` (the onboarding already has a live one, whose id comes back as `intentId`: update or execute it), `MANAGER_NOT_FOUND`, `PARENT_TICKET_IS_TYPED` or `PARENT_TICKET_IS_A_TASK` (pass the untyped ticket instead), `PARENT_TICKET_NOT_FOUND`. ## OpenAPI ````yaml https://api.getprimo.com/openapi.json post /employee-creation-intents openapi: 3.1.1 info: title: Public API - BETA description: Read docs on https://docs.getprimo.com/ version: '1.0' contact: {} servers: - url: https://api.getprimo.com security: - apikey: [] tags: [] paths: /employee-creation-intents: post: tags: - Onboardings summary: Create an employee creation intent description: >- Create the employee of an onboarding as a task the ticket tracks, from the HR information (name, emails, phone, start date, job, legal entity, work location, teams, manager, address). Creates the intent and its EMPLOYEE_CREATION task. Without `scheduleDate` the employee is created right away — a real employee and Clerk user, so confirm the information first; with one, the task sleeps until that date and the employee is created when it wakes up — nobody has to execute it. A field you leave out is read from the onboarding HRIS record, so send only what differs from it; null clears a field. Read the returned intent to see what was filled in. Pass the ticket the task belongs to as `parentTicketId`; without one Primo opens a ticket for it. `createTicket` and `createTask` cannot make a typed task. Returns the intent `id`, its `taskId` and the `ticketId` holding it. When the employee cannot be created (for instance `EMPLOYEE_INFORMATION_INCOMPLETE`), the task stays PENDING with an internal comment: fix the intent with `updateEmployeeCreationIntent`, then `executeEmployeeCreationIntent`. The task cannot be marked done by hand: `updateTaskStatus` refuses it, and it completes once Primo has created the employee. `createEmployee` only creates a record with no onboarding or task, and `completeOnboarding` closes the whole onboarding without this task; use the employee creation intent for an EMPLOYEE_CREATION task a ticket tracks. Refused with `ONBOARDING_NOT_FOUND`, `ONBOARDING_HAS_EMPLOYEE_CREATION` (the onboarding already has a live one, whose id comes back as `intentId`: update or execute it), `MANAGER_NOT_FOUND`, `PARENT_TICKET_IS_TYPED` or `PARENT_TICKET_IS_A_TASK` (pass the untyped ticket instead), `PARENT_TICKET_NOT_FOUND`. operationId: createEmployeeCreationIntent parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateEmployeeCreationIntentBody' responses: default: description: '' content: application/json: schema: $ref: '#/components/schemas/EmployeeCreationIntent_Output' components: schemas: CreateEmployeeCreationIntentBody: type: object properties: firstName: anyOf: - type: string minLength: 1 - type: 'null' lastName: anyOf: - type: string minLength: 1 - type: 'null' email: description: Work email address the employee is created with. anyOf: - type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ - type: 'null' personalEmail: anyOf: - type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ - type: 'null' phone: anyOf: - type: string - type: 'null' startDate: description: First day of the employee (ISO 8601), past or future. anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' employmentType: anyOf: - type: string enum: - INTERNAL - CONTRACTOR - type: 'null' job: description: Job title. anyOf: - type: object properties: id: description: >- Id of an existing record, when there is one. Omit it to create or match by name. anyOf: - type: string - type: 'null' name: type: string minLength: 1 required: - name - type: 'null' legalEntity: anyOf: - type: object properties: id: description: >- Id of an existing record, when there is one. Omit it to create or match by name. anyOf: - type: string - type: 'null' name: type: string minLength: 1 required: - name - type: 'null' workLocation: description: Office. Null for a remote employee. anyOf: - type: object properties: id: description: >- Id of an existing record, when there is one. Omit it to create or match by name. anyOf: - type: string - type: 'null' name: type: string minLength: 1 required: - name - type: 'null' teams: description: Teams the employee joins, replaced whole. type: array items: type: object properties: id: description: >- Id of an existing record, when there is one. Omit it to create or match by name. anyOf: - type: string - type: 'null' name: type: string minLength: 1 required: - name managerId: description: Primo employee id of the manager, from `getEmployees`. anyOf: - type: string pattern: ^[a-f\d]{24}$ - type: 'null' address: description: Personal (home) address of the employee. anyOf: - type: object properties: name: anyOf: - type: string - type: 'null' contactName: anyOf: - type: string - type: 'null' phone: anyOf: - type: string - type: 'null' street: type: string minLength: 1 complement: anyOf: - type: string - type: 'null' postalCode: type: string minLength: 1 city: type: string minLength: 1 country: anyOf: - type: string minLength: 1 - type: 'null' countryCode: description: ISO 3166-1 alpha-2 country code anyOf: - type: string - type: 'null' required: - street - postalCode - city - type: 'null' onboardingId: description: >- The onboarding the employee is created for, from `getOnboardings`. Fixed once created. type: string pattern: ^[a-f\d]{24}$ parentTicketId: description: >- The untyped ticket the task belongs to. Omit it and Primo opens a ticket to hold the task. anyOf: - type: string pattern: ^[a-f\d]{24}$ - type: 'null' scheduleDate: description: >- Creates the task SCHEDULED until this date: it cannot be executed before it wakes up as PENDING. anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' required: - onboardingId EmployeeCreationIntent_Output: type: object properties: id: type: string description: >- Intent id — pass it to `updateEmployeeCreationIntent` and `executeEmployeeCreationIntent` taskId: description: The EMPLOYEE_CREATION task that tracks this employee creation anyOf: - type: string - type: 'null' ticketId: description: >- The ticket holding that task: the parentTicketId sent, or the one Primo opened. Null if it could not be read back. anyOf: - type: string - type: 'null' onboardingId: type: string firstName: anyOf: - type: string - type: 'null' lastName: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' personalEmail: anyOf: - type: string - type: 'null' phone: anyOf: - type: string - type: 'null' startDate: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' employmentType: anyOf: - type: string enum: - INTERNAL - CONTRACTOR - type: 'null' job: anyOf: - type: object properties: id: anyOf: - type: string - type: 'null' name: type: string required: - id - name additionalProperties: false - type: 'null' legalEntity: anyOf: - type: object properties: id: anyOf: - type: string - type: 'null' name: type: string required: - id - name additionalProperties: false - type: 'null' workLocation: anyOf: - type: object properties: id: anyOf: - type: string - type: 'null' name: type: string required: - id - name additionalProperties: false - type: 'null' teams: type: array items: type: object properties: id: anyOf: - type: string - type: 'null' name: type: string required: - id - name additionalProperties: false managerId: anyOf: - type: string - type: 'null' address: anyOf: - type: object properties: name: anyOf: - type: string - type: 'null' contactName: anyOf: - type: string - type: 'null' phone: anyOf: - type: string - type: 'null' street: type: string minLength: 1 complement: anyOf: - type: string - type: 'null' postalCode: type: string minLength: 1 city: type: string minLength: 1 country: anyOf: - type: string - type: 'null' countryCode: anyOf: - type: string - type: 'null' required: - name - contactName - phone - street - complement - postalCode - city - country - countryCode additionalProperties: false - type: 'null' employeeId: description: The employee created on execute, null until then anyOf: - type: string - type: 'null' executedAt: description: When the intent was executed; null while it can still change anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - id - taskId - ticketId - onboardingId - firstName - lastName - email - personalEmail - phone - startDate - employmentType - job - legalEntity - workLocation - teams - managerId - address - employeeId - executedAt - createdAt - updatedAt additionalProperties: false securitySchemes: apikey: scheme: bearer bearerFormat: API key type: http description: >- Use your Primo API key in the Authorization header as `Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.