Getting Started

This guide walks you through everything you need to go from receiving your API keys to displaying a working onboarding session in the browser.

Prerequisites

You'll need:

• Your partner API key (provided by SuperAPI, email support@superapi.com.au if you don't have one)
• curl or a tool like Postman for making API requests
• A browser to view the employer and onboarding embeds

TIP

All new partners start in sandbox mode. Sandbox behaves identically to production but will not cause any side effects in the real world. For example, requests to the ATO stapling API and direct super fund integrations are simulated so you can develop safely.

Step 1: Verify your partner key

Your partner key manages the relationship between SuperAPI and your organisation. Test it by fetching your partner details:

curl -X GET https://api.superapi.com.au/api/v1/partner \
  -H "Content-Type: application/json" \
  -H "x-api-key: superapipartner_yourkeyhere"

You should receive a response like:

{
  "data": {
    "id": "a334d4cf-5599-4615-9616-991823eabbfb",
    "name": "YourCompanyName",
    "slug": "yourcompanyname",
    "custom_theme": null,
    "sandboxed": true
  },
  "version": "v1"
}

Step 2: Create a product

A product represents an instance of your application in SuperAPI. For example, if your application runs on a custom domain for each customer, each instance would be a separate product. The data stored on the product defines how SuperAPI delivers information to your system and how SuperAPI behaves when embedded in your application (e.g. the target_origin and webhook_url).

Create a product using your partner key:

curl -X POST https://api.superapi.com.au/api/v1/partner/product \
  -H "Content-Type: application/json" \
  -H "x-api-key: superapipartner_yourkeyhere" \
  -d '{
    "name": "My App",
    "target_origin": "http://localhost",
    "webhook_url": "https://example.com/webhooks/superapi"
  }'

You should receive a response like:

{
  "data": {
    "id": "a4c00787-2a87-43b7-bd47-c7c8c04e2f93",
    "name": "My App",
    "slug": "my-app",
    "target_origin": "http://localhost",
    "webhook_url": "https://example.com/webhooks/superapi",
    "webhook_signing_token": "FYgQ...R2MFw==",
    "bank_details_configuration": {
      "id": "80b81e0e-f142-43b3-9115-70674f0ff9c8",
      "max_percentage_accounts": null,
      "max_fixed_accounts": null,
      "max_bank_accounts": 3
    },
    "tfn_declarations_configuration": {
      "id": "bef7203c-baea-4ae6-b2a4-2a100e836582",
      "allow_user_edits": true
    }
  },
  "version": "v1"
}

Note the id from the response as you'll need it in the next step.

INFO

target_origin is the origin where you'll embed SuperAPI iFrames. For local development, use http://localhost. See the MDN docs on targetOrigin for more detail.

Step 3: Create a product API key

Your product API key is what you'll use for day-to-day operations (creating employers, onboarding sessions, etc.). Generate one using your partner key:

curl -X POST https://api.superapi.com.au/api/v1/partner/product/:id/product-api-key \
  -H "Content-Type: application/json" \
  -H "x-api-key: superapipartner_yourkeyhere"

Replace :id with the product ID from Step 2.

The response will include an api_key field. Save this securely. This is your product API key and is used for all subsequent steps.

DANGER

Your product API key is sensitive. Do not check it into source control.

Verify it works:

curl -X GET https://api.superapi.com.au/api/v1/product \
  -H "Content-Type: application/json" \
  -H "x-api-key: superapiproduct_yourproductkeyhere"

You should receive a response similar to:

{
  "data": {
    "id": "a4c00787-2a87-43b7-bd47-c7c8c04e2f93",
    "name": "My App",
    "slug": "my-app",
    "target_origin": "http://localhost",
    "webhook_url": "https://example.com/webhooks/superapi",
    "webhook_signing_token": "REDACTED",
    "bank_details_configuration": {
      "id": "80b81e0e-f142-43b3-9115-70674f0ff9c8",
      "max_percentage_accounts": null,
      "max_fixed_accounts": null,
      "max_bank_accounts": 3
    },
    "tfn_declarations_configuration": {
      "id": "bef7203c-baea-4ae6-b2a4-2a100e836582",
      "allow_user_edits": true
    }
  },
  "version": "v1"
}

Step 4: Create an employer

Employers represent the businesses using your software. Every onboarding session belongs to an employer, so you need to create one first:

curl -X POST https://api.superapi.com.au/api/v1/employer \
  -H "Content-Type: application/json" \
  -H "x-api-key: superapiproduct_yourproductkeyhere" \
  -d '{
    "abn": "96878537596",
    "name": "Test Company",
    "remote_id": "employer-1",
    "country": "aus"
  }'

You should receive a response like:

{
  "data": {
    "id": "45910b12-d2e7-4ebc-8033-f014a7efc88b",
    "name": "Test Company",
    "address": null,
    "inserted_at": "2026-02-27T06:06:46Z",
    "updated_at": "2026-02-27T06:06:46Z",
    "country": "aus",
    "contact": null,
    "abn": "96878537596",
    "remote_id": "employer-1",
    "onboarding_status": "error",
    "onboarding_configuration": {
      "default_fund_configured": false,
      "stapling_enabled": false,
      "tfnd_enabled": false
    },
    "last_activity_at": null,
    "employer_default_super_fund_product": null,
    "abn_branch_number": null
  },
  "version": "v1"
}

Note the id from the response.

INFO

The remote_id is your internal identifier for this employer (e.g. a primary key from your database). It's returned in webhooks so you can match SuperAPI events back to your records.

Step 5: Show the employer embed

Before employees can be onboarded, the employer needs to configure their settings via the employer embed. This is where the employer selects their default super fund, which is used as the fallback when an employee does not make a super choice and does not have a stapled fund. The employer default super fund must be set before onboarding sessions can be created.

Generate an embed URL to display this configuration UI:

curl -X POST https://api.superapi.com.au/api/v1/employer/:id/generate-embed-url \
  -H "Content-Type: application/json" \
  -H "x-api-key: superapiproduct_yourproductkeyhere" \
  -d '{
    "app": "super_settings",
    "session_id": "test-session-1",
    "valid_until": "<UTC timestamp within 2 hours from now>"
  }'

Replace :id with the employer ID from Step 4.

You should receive a response like:

{
  "data": {
    "embed_url": "https://api.superapi.com.au/embed/v1/employer/:id/employer-embed?..."
  },
  "version": "v1"
}

Open the embed_url in a browser to see the employer configuration embed. Use our JavaScript library to embed this in your application via iFrame.

WARNING

Generated URLs are ephemeral. valid_until must be within 2 hours of the current time (UTC). Generated URLs are sensitive and should not be stored in a database.

Step 6: Create an employee

An employee represents one person's employment at one employer, and can have many onboarding sessions over time. Create the employee once and reuse it every time you start a session for that person.

Pass anything you already hold about them, so there is less for the employee to fill in themselves:

curl -X POST https://api.superapi.com.au/api/v1/employer/:id/employee \
  -H "Content-Type: application/json" \
  -H "x-api-key: superapiproduct_yourproductkeyhere" \
  -d '{
    "remote_id": "employee-1",
    "email": "employee@example.com",
    "data": {
      "identity": {
        "given_name": "Jane",
        "family_name": "Citizen",
        "date_of_birth": "1990-04-12"
      },
      "address": {
        "address_line_1": "1 Test Street",
        "locality": "Melbourne",
        "postcode": "3000",
        "state": "vic"
      },
      "phone_numbers": [
        { "phone_number": "+61491570006" }
      ]
    }
  }'

Replace :id with the employer ID from Step 4. Only remote_id and email are required, everything under data is optional. See the API reference for the full set of fields you can pre-fill.

You should receive a response like:

{
  "data": {
    "id": "a0c8056c-ef80-478a-8cbc-21f825f3bd60",
    "remote_id": "employee-1",
    "inserted_at": "2026-02-27T06:06:52Z",
    "updated_at": "2026-02-27T06:06:52Z",
    "identity": {
      "title": null,
      "given_name": "Jane",
      "middle_name": null,
      "family_name": "Citizen",
      "date_of_birth": "1990-04-12",
      "gender": null
    },
    "address": {
      "address_line_1": "1 Test Street",
      "address_line_2": null,
      "address_line_3": null,
      "address_line_4": null,
      "locality": "Melbourne",
      "postcode": "3000",
      "state": "vic"
    },
    "phone_numbers": [
      {
        "id": "d845d4fc-304c-4415-9941-291426f902b4",
        "inserted_at": "2026-02-27T06:06:52Z",
        "updated_at": "2026-02-27T06:06:52Z",
        "phone_number": "+61491570006",
        "verified_at": null,
        "partner_provided_at": null,
        "employee_provided_at": null
      }
    ],
    "tax_detail": null,
    "super_fund_details": {
      "super_fund_memberships": []
    },
    "employer": {
      "id": "45910b12-d2e7-4ebc-8033-f014a7efc88b",
      "name": "Test Company"
    }
  },
  "version": "v1"
}

Note the id from the response as you'll need it in the next step.

INFO

remote_id is your identifier for this employee at this employer and must be unique within that employer. Reusing one you have already sent for the same employer is rejected.

Step 7: Create an onboarding session

TIP

Creating an onboarding session will fail if the employer hasn't been fully configured. Make sure the employer entity has been created and the employer has completed their configuration via the employer embed before you attempt to create onboarding sessions.

An onboarding session is the workflow you hand to one employee, once. Create it against the employee from Step 6 and the employer from Step 4:

curl -X POST https://api.superapi.com.au/api/v1/onboarding-session \
  -H "Content-Type: application/json" \
  -H "x-api-key: superapiproduct_yourproductkeyhere" \
  -d '{
    "employer": {
      "id": "your-employer-id"
    },
    "employee": {
      "id": "your-employee-id"
    },
    "email": "employee@example.com",
    "remote_id": "onboarding-1",
    "email_validated": true,
    "phone_number": "+61491570006",
    "phone_number_validated": false,
    "workflow_slug": "standard_onboarding"
  }'

You should receive a response like:

{
  "data": {
    "id": "22803658-b5ba-473b-9f81-50879ea7f385",
    "inserted_at": "2026-02-27T06:06:58",
    "email": "employee@example.com",
    "expires_at": "2026-03-29T06:06:59Z",
    "abandons_at": "2026-03-13T06:06:59Z",
    "employee_id": "a0c8056c-ef80-478a-8cbc-21f825f3bd60",
    "remote_id": "onboarding-1",
    "template_id": null,
    "email_validated": true,
    "phone_number": "+61491570006",
    "phone_number_validated": false,
    "progression": {
      "is_abandoned": false,
      "completion_percentage": 0.0
    },
    "data_delivery_state": "initial"
  },
  "version": "v1"
}

Note the id from the response. employee_id is the employee the session belongs to, and you can fetch that record at any time from GET /api/v1/employee/:id.

INFO

Instead of employee.id, you can pass employee.remote_id. SuperAPI will attach the session to the employee already holding that remote_id for this employer, or create one if there isn't one yet. Supply one or the other, sending both is rejected.

Step 8: Show the onboarding embed

Generate an embed URL for the onboarding session:

curl -X POST https://api.superapi.com.au/api/v1/onboarding-session/:id/generate-embed-url \
  -H "Content-Type: application/json" \
  -H "x-api-key: superapiproduct_yourproductkeyhere" \
  -d '{
    "valid_until": "<UTC timestamp within 2 hours from now>"
  }'

You should receive a response like:

{
  "data": {
    "embed_url": "https://api.superapi.com.au/embed/v1/onboarding-session/:id/edit?..."
  },
  "version": "v1"
}

Open the returned embed_url in a browser. You'll see the onboarding experience your employees will go through, including super choice, tax details, bank accounts, and whatever other modules are configured.

What happens next?

When an employee completes their onboarding session, SuperAPI will:

1. Send a webhook to the webhook_url you configured on your product. The webhook is an event notification and does not contain the session data itself. When you receive a webhook, you should fetch the relevant data from SuperAPI using the ID included in the event.
2. Emit a post-message via the iFrame so your frontend can react immediately (e.g. close the iFrame, show a success message)

To handle these in your integration:

• Webhook security: verify incoming webhooks with HMAC
• List of webhooks: understand the events and payloads
• Work with webhooks locally: test with ngrok during development

Next steps

• Browse the available modules to see what you can include in onboarding
• Use onboarding templates to customise onboarding sessions with additional requirements like document uploads and policy acknowledgements
• Customise the look and feel to match your brand
• Read about SuperAPI entities to understand the full data model
• Explore the API reference for all available endpoints
• Using TypeScript and want an opinionated experience integrating with our embeds? Install our library via NPM and view the source on Github.

Getting help

Stuck with something and need help? Please contact us at support@superapi.com.au or by phone on 0405 472 748 (Sam). Have you setup a shared Slack or Teams channel with us? If not, please reach out so we can provide realtime support.