Redirect user

There have been important recent changes on this page, please see the release notes for information

Request details fetching

Fetch existing request data from SEEK Pass using the status or bulk status endpoints. These endpoints return information about one or multiple requests, such as their status, when they were finalised, and a redirect URI for the user.

This is the recommended way to redirect a user who already has an existing request to complete or view their credential submission on SEEK Pass. Attempting to create a new request in order to generate a redirect URI is not recommended.

Data submission

Submit user data to SEEK Pass using the correct endpoint based on credential type. For example, for the Education credential type the endpoint to call is: /api/partner/v1/add/education.json.

Environments

The staging and production environment endpoints are provided below:

Staging: https://app.seekpass-staging.com
Production: https://app.seekpass.co

Sample request

export CREDENTIAL_TYPE=education

export PAYLOAD='{
  "id": "seek-pass-test-a9a4839f-53d9-4064-8b0b-1348113a33f8",
  "document_type": "open_cert",
  "credential_type": "education",
  "data": {
    "credential": {
      "full_name": "John Smith",
      "education_provider": "University of Melbourne",
      "course_name": "Bachelor of Commerce",
      "conferral_year": "2024",
      "has_majors": true,
      "majors": ["Finance"],
      "with_honours": true
    },
    "document": "<OPEN_CERTS>"
  }
}'

curl -L $SEEK_PASS_URL/api/partner/v1/add/$CREDENTIAL_TYPE.json \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
--data "$PAYLOAD"

We recommend using a globally unique value (e.g. UUID) for id to ensure proper tracking of user requests.

When calling this endpoint with an ID that already exists, you must be aware of the status of the existing request. IDs linked to requests which are in-progress will be rejected, and the user should in stead be redirected to complete their submission on SEEK Pass using the request status endpoint(s) to fetch the relevant URI.

To upload files (PDF, JPG, PNG, etc.) that are passed as a URL in the document field, ensure the following requirements are met:

1.
Public accessibility: The URL must be accessible without additional header or browser based authentication
2.
Domain whitelisting: The domain must be whitelisted by SEEK Pass

Please contact our team to request domain whitelisting.

Response codes

201 Created: Successful request

{
    "redirect_uri": "https://app.seekpass-staging.com/partner/add/education#clientId=730845ab-0a0d-4f4d-9c98-d871755d3ce9&documentType=open_cert&content=d8a8eb57-c64f-4fc1-b362-b8df28fbf0a3"
}

URL format

The redirect URL is generated with this format:

Path: /partner/add/[CREDENTIAL TYPE]
Examples:
- For Education: /partner/add/education
- For English proficiency: /partner/add/englishProficiency
- For Learning and Development: /partner/add/microcredential
Hash: the parameters below, encoded as URL query parameters
- clientId: The partner's OAuth client ID
- documentType: The expected document type
- content: The SEEK Pass request ID

Note: CURL returns invalid \u0026 instead of &. Please replace \u0026 with & in the redirect URL. Other clients should not have this issue.

Behaviour

ID Reuse While a Request is Pending: Creating a request with an existing ID at any point while the request is not finalised will result in an error. Always check the status of existing requests and decide whether to direct the user to an existing request or create a new one.
User Association: When a user accesses the redirect_uri and authenticates, the credential data becomes associated with their account.
Unassociated Request Expiry: If the user fails to access the redirect_uri and begin their submission within 48 hours, the request will be automatically cancelled and the original data is permanently deleted. After this point the existing request will be finalised and cancelled, and you may reuse the same ID to create a new request to send to the user.
Associated Request Expiry: The user may access the redirect_uri, but then drop out and fail to confirm adding the credential to their account. The user has up to 30 days to come back to the platform and confirm, depending on the credential type. After this period, the request is finalised and cancelled, and you may reuse the same ID to create a new request to send to the user.
Consent Flow: Credential data is associated with the user's account upon authentication, regardless of consent status. If consent has not been granted, the redirect_uri will prompt the user to accept.
Post-Consent Behavior: Once consent is granted, when the user accesses the same redirect_uri, users will be directed to their submitted credentials.
Data Retention Policy: If a user completes the user flow but does not download and authenticate via the mobile application within 48 hours, all associated documents are securely deleted in accordance with data protection policies.

Once a user clicks the link and logs into the system, the data is associated only with them. If another user attempts to use the same link, they will be redirected to an error page.

Updating existing credentials

When re-issuing a credential, regardless of whether it has changed, all requests should reuse the same unique ID to refer to the same credential. Re-issuing a credential cannot be done while the current request is in-progress.

To update a credential with new contents, partners must submit a new request with the same values for specific fields used in the original submission.

Scenarios where this may be necessary include:

A user updating a credential as the original one is about to expire
A user retaking assessment based credential and has received a new score
A user with an Education Qualification in an 'awaiting graduation' has now been conferred

For a newer version of the same credential to replace an existing one rather than appearing as a new credential, the following fields need to remain the same:

Education: course_name, conferral_year, majors (if applicable), with_honours (if applicable)
English Proficiency: test_name, test_provider
Learning and Development: microcredential_name, issuer_name

Previous: Expiry & revocation

Next: Check submission status