Open the employer embed on a specific page
By default the employer embed opens on its dashboard. When you send an employer to the embed for a particular reason, such as an issue that needs their attention, you can open it on the relevant page instead by setting an entry point when you generate the embed URL. The employer can still go back to the dashboard from there.
Entry points
Set entry_route on the super_settings app, along with the id it needs:
entry_route | Id parameter | Opens on |
|---|---|---|
employer_issues | employer_issue_id (optional) | The page for that employer issue, showing what went wrong, the recommended actions and its current status. Without employer_issue_id, the list of the employer's issues. |
employee_history | employee_id (required) | The history of that employee, a timeline of what has happened during their onboarding. |
curl -X POST https://api.superapi.com.au/api/v1/employer/9f1d8e2a-0b3c-4d5e-8f6a-7b8c9d0e1f2a/generate-embed-url \
-H "Content-Type: application/json" \
-H "x-api-key: superapiproduct_yourkeyQvyaXOF" \
-d '{
"app": "super_settings",
"session_id": "<a new random id for this URL>",
"valid_until": "<UTC timestamp within 2 hours from now>",
"entry_route": "employee_history",
"employee_id": "2b3c4d5e-6f70-4a1b-9c2d-3e4f5a6b7c8d"
}'We may add entry points over time. Each one is a stable public value, so the pages behind it can change without breaking your integration.
Entry points and session_id
The embed remembers where the employer has navigated, keyed on the session_id. The entry point only applies when there is no navigation history for that session_id. If the same session_id was used recently, the embed resumes where that session left off and ignores the entry point.
To make sure the employer lands on the page you chose, use a new random session_id (for example a UUID) each time you generate a URL with an entry point. Reloading the embed with the same URL then keeps the employer on whatever page they had navigated to, rather than sending them back to the entry point.
Linking from an email or notification
Don't put an embed URL in an email, a notification or anywhere else that outlives the page view. It expires within 2 hours and is sensitive. Link to a page in your own product, behind your own login, that generates the embed URL with the entry point when it loads. See Link straight to the issue in the employer embed for this pattern applied to employer issues.
Errors
| Response | When |
|---|---|
404 | The issue or employee doesn't belong to this employer. employer_requires_support_with_stapling issues aren't shown in the embed, so they return 404 too. |
422 | entry_route isn't one of the supported values, app isn't super_settings, employee_id is missing for employee_history, employer_issue_id or employee_id is passed without its matching entry_route, or entry points aren't yet available for this employer. |