---
url: /software_partners/start/getting_started.md
---

# 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](/postman_collection.json){target="\_blank" download="download"} 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:

```bash
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:

```json
{
  "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:

```bash
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:

```json
{
  "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](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#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:

```bash
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:

```bash
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:

```json
{
  "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:

```bash
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:

```json
{
  "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:

```bash
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:

```json
{
  "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](https://github.com/supersimplesuper/super-api-embed) 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:

```bash
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](https://api.superapi.com.au/swaggerui) for the full set of fields you can pre-fill.

You should receive a response like:

```json
{
  "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:

```bash
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:

```json
{
  "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:

```bash
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:

```json
{
  "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](/software_partners/build/modules/index.html) 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](/software_partners/build/webhooks/security/index.html): verify incoming webhooks with HMAC
* [List of webhooks](/software_partners/build/webhooks/list_of_webhooks/index.html): understand the events and payloads
* [Work with webhooks locally](/software_partners/build/webhooks/work_locally/index.html): test with ngrok during development

## Next steps

* Browse the [available modules](/software_partners/build/modules/index.html) to see what you can include in onboarding
* Use [onboarding templates](/software_partners/build/onboarding_sessions/templates/index.html) to customise onboarding sessions with additional requirements like document uploads and policy acknowledgements
* [Customise the look and feel](/software_partners/build/products/customise_the_look_and_feel/index.html) to match your brand
* Read about [SuperAPI entities](/software_partners/start/entities/index.html) to understand the full data model
* Explore the [API reference](https://api.superapi.com.au/swaggerui) for all available endpoints
* Using TypeScript and want an opinionated experience integrating with our embeds? Install our library via [NPM](https://www.npmjs.com/package/@super-api/super-api-embed) and view the source on [Github](https://github.com/supersimplesuper/super-api-embed).