> ## 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 the onboarding of a joiner from an HR system event > Start the onboarding of a joiner who is not an employee in Primo yet, from what an HR system or an automation knows: first name, last name, work email, the start date, and a free `data` object with everything else. Primo starts the whole flow, the way an admin does from the cockpit short form: the onboarding ticket and its steps, or the Onboarding Agent when it runs the onboardings of the company. `data` is kept on the onboarding as the hire text the agent reads. Refused with 409 `DUPLICATE_ONBOARDING` when an open onboarding already has this email, or the same name and start date, so a repeated call creates nothing; 502 `FAIL_TO_CREATE_ONBOARDING_TICKET` and 503 `ONBOARDING_AGENT_STATUS_UNAVAILABLE` created nothing, call again. For an employee who already exists in Primo, use `createOnboarding` with their id instead. Key: WriteScope: Company ## OpenAPI ````yaml https://api.getprimo.com/openapi.json post /employee-onboardings 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-onboardings: post: tags: - Onboardings summary: Create the onboarding of a joiner from an HR system event description: >- Start the onboarding of a joiner who is not an employee in Primo yet, from what an HR system or an automation knows: first name, last name, work email, the start date, and a free `data` object with everything else. Primo starts the whole flow, the way an admin does from the cockpit short form: the onboarding ticket and its steps, or the Onboarding Agent when it runs the onboardings of the company. `data` is kept on the onboarding as the hire text the agent reads. Refused with 409 `DUPLICATE_ONBOARDING` when an open onboarding already has this email, or the same name and start date, so a repeated call creates nothing; 502 `FAIL_TO_CREATE_ONBOARDING_TICKET` and 503 `ONBOARDING_AGENT_STATUS_UNAVAILABLE` created nothing, call again. For an employee who already exists in Primo, use `createOnboarding` with their id instead. operationId: createEmployeeOnboarding parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateEmployeeOnboardingBody' responses: default: description: '' content: application/json: schema: $ref: '#/components/schemas/GetOnboarding_Output' components: schemas: CreateEmployeeOnboardingBody: type: object properties: firstName: description: First name of the joiner type: string minLength: 1 lastName: description: Last name of the joiner type: string minLength: 1 email: description: Work email of the joiner 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,}$ startDate: description: >- First day of the joiner (YYYY-MM-DD or ISO 8601). Required by the classic onboarding, read by the agent. anyOf: - anyOf: - type: string format: date 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])))$ - 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' data: description: >- Everything else the caller knows about the joiner, as a free JSON object (job title, team, manager, location, contract…), at most 20000 characters once serialized. Kept on the onboarding and read by the Onboarding Agent. May hold personal data. anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' required: - firstName - lastName - email GetOnboarding_Output: type: object properties: id: type: string employeeId: anyOf: - type: string - type: 'null' ticketId: anyOf: - type: string - type: 'null' status: type: string enum: - PENDING - SCHEDULED - IN_PROGRESS - CLOSED - CANCELED stepModel: description: >- How the onboarding holds its steps: ACTIONS (the onboarding steps and their plain tasks) or INTENTS (typed tasks under its ticket, run through the intent tools such as `executeEmployeeCreationIntent`). Null while it has neither a ticket nor a step, and for an onboarding run by the agent. anyOf: - type: string enum: - ACTIONS - INTENTS - type: 'null' stepProgress: description: >- How many of its steps are through, out of how many: on ACTIONS its steps done, scheduled or skipped; otherwise the typed tasks of its ticket completed or cancelled. Null while it has no step. anyOf: - type: object properties: done: type: integer minimum: -9007199254740991 maximum: 9007199254740991 total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - done - total additionalProperties: false - type: 'null' source: type: string enum: - COCKPIT - MERGE - KOMBO - API 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' 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))$ hrRecords: description: HR records from the connected HRIS (Kombo) for this onboarding type: array items: type: object properties: id: type: string remoteId: anyOf: - type: string - type: 'null' 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' terminationDate: 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: - id additionalProperties: false hire: description: >- The hire an admin added by hand in the cockpit short form, before they are an employee in Primo anyOf: - type: object properties: firstName: type: string lastName: type: string emails: description: >- Every address the admin gave for the hire, to reach them until their work mailbox exists type: array items: type: string rawText: description: What the admin wrote about the hire, in their own words anyOf: - type: string - type: 'null' jobTitle: anyOf: - type: string - type: 'null' teamId: description: The Primo team the note names, when exactly one matches anyOf: - type: string - type: 'null' teamName: anyOf: - type: string - type: 'null' managerId: description: >- The Primo employee the note names as manager, when exactly one matches anyOf: - type: string - type: 'null' managerName: anyOf: - type: string - type: 'null' workLocationId: description: >- The Primo work location the note names, when exactly one matches anyOf: - type: string - type: 'null' workLocationName: anyOf: - type: string - type: 'null' workMode: anyOf: - type: string enum: - REMOTE - ON_SITE - HYBRID - type: 'null' city: anyOf: - type: string - type: 'null' agentNotes: description: >- What the note left ambiguous or could not file in a field, to ask or act on type: array items: type: string required: - firstName - lastName - emails - agentNotes additionalProperties: false - type: 'null' emails: type: array description: >- Every email address of the employee being onboarded. Empty while the onboarding has no employee. items: type: string required: - id - status - source - createdAt - hrRecords - emails 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.