Verify with SEEK Pass

Verify with SEEK Pass provides a seamless way for verifying credentials (e.g. digital identity) via SEEK Pass. For this integration, partners embed a button in their application flow which directs users to the SEEK Pass app where they need to choose a credential to be verified (e.g. passport, driver's licence). Partners can integrate with SEEK Pass using REST APIs to authenticate and create a verification request, and redirect users to the SEEK Pass app. Verify with SEEK Pass - User Journey Flow

Verify with SEEK Pass - Digital Identify Workflow

Technical details

There are 3 phases for this integration:

Authenticating with SEEK Pass
Submitting a verification request
Retrieving verification result

SEEK Pass authenticates and authorises partner requests using the OAuth2 Client Credentials flow for server-to-server authentication. Upon onboarding, partners will be provided with OAuth credentials to obtain a JWT access token for subsequent API calls. The OAuth credentials will be provided via a secure channel (e.g. 1Password).

# POST /api/partner/v2/oauth/token

curl --location $SEEK_PASS_URL/api/partner/v2/oauth/token.json 
--header 'Accept: application/json' 
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode grant_type=client_credentials 
--data-urlencode client_id=$CLIENT_ID 
--data-urlencode client_secret=$CLIENT_SECRET 
--data-urlencode 'scope=write.digital_identity read.digital_identity'

Once authenticated, partners can submit a verification request using our verification API (POST /api/partner/v2/verify/requests/digital_identity.json). The request payload contains an optional callback URL which will be used to redirect users back to the partner's nominated location (e.g. web app) after a user has completed the verification flow. This API returns a redirect URI which must be used to direct users to SEEK Pass. Refer to next sections for more details on the redirect URI format.After users complete the verification flow, they will be redirected back to the partner callback URL and the verification result will be provided via an API or a registered webhook. The response payload contains a request ID, user's credential data, and verification result. Webhook security implementation is covered in the following sections.

Request payload

The request payload contains the following fields:

request_id (optional): It’s for partners to track their requests. If not provided, it will be auto-generated.
callback_url (optional): Users will be redirected back to this URL, if provided, after completing the flow.
display_options (required): The partner_name value which is mandatory, will be shown to users. partner_logo_url can also be provided.
request_source (optional): This field records any existing hirerachy of parties involved in the verification request (e.g. ATSs).
metadata (optional): This field captures any extra information that SEEK Pass needs for reporting or other purposes. For SEEK/Indirect, we’ll record job-related information.
options (optional): Optional parameters to configure the SEEK Pass experience.
- email_hint (optional): Pre-fills the user's email address on the login screen. The user is able to enter a different email address if they wish.
- locale (optional): Sets the initial language for the verification flow.

If a request_id is not provided in the request payload, SEEK Pass will auto-generate a unique request ID. We recommend using a globally unique value (e.g. UUID) for request_id to ensure proper tracking of user requests.

Sample verification request:

# POST /api/partner/v2/verify/requests/digital_identity.json

{
  "request_id": "7cbc7e51-82f5-43ec-8d63-b7cdf1170425",  // Optional. For tracking requests. If not passed, it will be auto-generated.
  "callback_url": "https://www.partner.com/callback",    // Optional. For redirecting users
  "display_options": {           // Required
    "partner_name": "string",    // Required
    "partner_logo_url": "string" // Optional
  },
  "request_source": [            // Optional
    {
      "name": "string"
    }
  ],
  "metadata": {                  // Optional - context about the verification
    "position_title": "string",
    "position_url": "string",
    "position_location": "string",
    "job_categories": "string",
    "applied_on_seek": true
  },
  "options": {                   // Optional - configure the SEEK Pass experience
    "email_hint": "string",      // Optional. Pre-fills the user's email address
    "locale": "string"           // Optional. Sets the language for the verification flow (e.g. en-AU)
  }
}

Sample verification response:

{
  "request_id": "7cbc7e51-82f5-43ec-8d63-b7cdf1170425",
  "redirect_uri": "https://app.seekpass.co/partner/verify/digitalIdentity?clientId=[CLIENT_ID]&requestId=fa651300-b91a-49cb-8ee7-cac68b3fdf74"
}

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.

Sequence diagram

SEEK Pass account

SEEK Pass will provide OAuth credentials for partners for authentication in staging and production environments:

OAuth token endpoint: POST /api/partner/v2/oauth/token.json
Host:
- Production: https://app.seekpass.co
- Staging: https://app.seekpass-staging.com
Client credentials will be provided via a secure channel (e.g. 1Password)

Verify with SEEK Pass button

SEEK Pass provides our partners with a selection of button images that can be embedded to display on your platform. These images will be rendered with SEEK Pass branding, ensuring consistency across user interactions. We recommend using the provided button assets wherever possible to maintain a cohesive, on-brand style. A sample button is shown below. For more details, please refer to our API documentation - Branding Guidelines.

Redirect URI structure

Path: /partner/verify/[Credential type]
Host:
- Production: https://app.seekpass.co
- Staging: https://app.seekpass-staging.com
Query: The below parameters as URL query parameters
- clientId: OAuth Application ID
- requestId: Verification request ID
Sample: https://app.seekpass-staging.com/partner/verify/digitalIdentity?clientId=[CLIENT_ID]&requestId=fa651300-b91a-49cb-8ee7-cac68b3fdf74

Verification result

The verification data and result of a request is provided via an API or a partner-registered webhook. SEEK Pass can provide webhook updates for various events at different stages of a verification workflow. Sample events are listed below:

incomplete
canceled (rejected, canceled, expired)
verified

Previous: Revoke request

Next: Check submission status