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/v1/oauth/token

curl --location $SEEK_PASS_URL/api/partner/v1/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.

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
  }
}

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 within 48 hours: Submitting a request with an existing ID within 48 hours returns the original `redirect_uri`.
ID Reuse after 48 hours: After 48 hours, the original data is permanently deleted. Resubmitting with the same ID creates a new credential request with a distinct SEEK Pass ID and generates a new `redirect_uri`.
User Association: When a user accesses the `redirect_uri` and authenticates, the credential data becomes associated with their account.
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, subsequent API requests return the same URL, directing users 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: Check submission status

Next: Check submission status