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

• 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.

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.

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.

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": "<UTC timestamp within 2 hours from now>"
  }'

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, 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.

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.

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 and follow its lifecycle. 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. Full field lists are in the API reference.