--- url: /software_partners/build/onboarding_sessions/intents.md --- # Onboarding session intents An onboarding session is normally created by you, in one request, with everything the session needs. An **onboarding session intent** splits that into two halves: you record that an employee is about to be onboarded, the employer fills in the rest inside a SuperAPI embed, and you turn the completed intent into a session. Use an intent when the employer, not your system, decides what a new starter has to do. In the intent embed the employer confirms the employee's identity details and picks the requirements for this hire: documents to upload, welcome videos, forms to sign, policies to acknowledge and fair work statements to show. None of that has to pass through your API integration. ## How an intent moves ```mermaid stateDiagram-v2 [*] --> pending: You create the intent pending --> complete: Employer finishes the intent embed complete --> complete: You create the session from it complete --> [*] ``` * **pending**: the intent exists and can be opened in the employer embed. * **complete**: the employer has finished. The `onboarding_intent_completed` webhook fires, and the intent can be turned into an onboarding session once. After that its `onboarding_session_id` is set. ## Step 1 - Create the intent Create the intent with your product API key, passing whatever you already know about the employee. Only `employer_id` and `remote_id` are required. If the employee already exists in SuperAPI, pass `employee_id` and their identity fields are prefilled from that record. ```bash curl -X POST https://api.superapi.com.au/api/v1/onboarding-session-intent \ -H "Content-Type: application/json" \ -H "x-api-key: superapiproduct_yourkeyQvyaXOF" \ -d '{ "employer_id": "45910b12-d2e7-4ebc-8033-f014a7efc88b", "remote_id": "hire-1", "email": "employee@example.com", "given_name": "Jane", "family_name": "Citizen", "phone_number": "+61491570006", "date_of_birth": "1990-04-12" }' ``` `remote_id` is your reference for this hire and must be unique within the employer. The response includes the intent `id` you need for the next steps. Optional fields worth knowing: * `abandons_at` sets when the eventual session should be abandoned. Set `allow_employer_abandons_at` to `true` to let the employer change it in the embed. * `employer_default_super_fund_product.brand_id` overrides the employer's default fund for this one session without changing the employer's own configuration. * `allow_employer_configuration: false` skips the employer step entirely. See [Skipping the employer step](#skipping-the-employer-step). ## Step 2 - Show the employer the intent embed Generate an employer embed URL with `app` set to `onboarding_intent` and the intent's id as `intent_id`. The other parameters are the same as any [employer embed](/software_partners/start/getting_started/index.html#step-5-show-the-employer-embed). ```bash curl -X POST https://api.superapi.com.au/api/v1/employer/45910b12-d2e7-4ebc-8033-f014a7efc88b/generate-embed-url \ -H "Content-Type: application/json" \ -H "x-api-key: superapiproduct_yourkeyQvyaXOF" \ -d '{ "app": "onboarding_intent", "intent_id": "a770d903-f852-4ef1-acb3-43cba5ecb74d", "session_id": "user-42", "valid_until": "" }' ``` Render the returned `embed_url` where the employer sets up a new starter in your product. The employer reviews the identity details, chooses the requirements for this hire and submits. ## Step 3 - Receive the completion webhook When the employer submits, SuperAPI sends an `onboarding_intent_completed` webhook with `subject` set to `onboarding_session_intent`. It follows the [standard payload](/software_partners/build/webhooks/list_of_webhooks/index.html#the-payload), and `url` points at the intent. Fetch the intent to see what the employer chose. The response carries the `file_uploads`, `welcome_videos`, `form_documents`, `policies` and `fair_work_statements` selected for this hire. ```bash curl -X GET https://api.superapi.com.au/api/v1/onboarding-session-intent/a770d903-f852-4ef1-acb3-43cba5ecb74d \ -H "Content-Type: application/json" \ -H "x-api-key: superapiproduct_yourkeyQvyaXOF" ``` ## Step 4 - Create the onboarding session from the intent A complete intent becomes a session with one request. Pass the `workflow_slug` you want the employee to go through. If the intent was created without an `employee_id`, SuperAPI creates the employee record for you, so you must supply the `remote_id` for that new employee. ```bash curl -X POST https://api.superapi.com.au/api/v1/onboarding-session-intent/a770d903-f852-4ef1-acb3-43cba5ecb74d/onboarding-session \ -H "Content-Type: application/json" \ -H "x-api-key: superapiproduct_yourkeyQvyaXOF" \ -d '{ "workflow_slug": "standard_onboarding", "remote_id": "onboarding-1", "employee": { "remote_id": "employee-1" } }' ``` The response is the intent with `onboarding_session_id` populated. From here the session behaves like any other: generate its embed URL, listen for the [onboarding session webhooks](/software_partners/build/webhooks/list_of_webhooks/index.html#onboarding-sessions) and follow its [lifecycle](/software_partners/build/onboarding_sessions/lifecycle/index.html). An intent can only be converted once. ## Skipping the employer step If there is nothing for the employer to decide, create the intent with `allow_employer_configuration: false`. It is created already `complete`, no webhook is sent, and you can go straight to Step 4. Such an intent cannot be reopened or shown in the employer embed later. ## Housekeeping * List an employer's intents with `GET /api/v1/employer/:id/onboarding-session-intents`, paginated with `?page=N`. * Delete an intent with `DELETE /api/v1/onboarding-session-intent/:id`. A complete intent that already has a linked session cannot be deleted. * Intents share the `remote_id` uniqueness rule with the rest of SuperAPI, described in [Common gotchas](/software_partners/operate/common_gotchas/index.html#remote-id-confusion). Full field lists are in the [API reference](https://api.superapi.com.au/swaggerui).