Skip to main content

​
Overview

The Onboarding Init API provides the PFM WebRD for initiating the user onboarding process. This API sets up the initial configuration including the redirection URL where users will be redirected after completing the onboarding process. It’s the first step in the PFM user journey and prepares the system for subsequent PFM operations.

​
Example Request

curl --location 'https://api-uat.pfm.equal.in/pfm/onboarding/init' \
--header 'Content-Type: application/json' \
--header 'Authorization: eyJhbGciOiJSUz..' \
--data '{
    "redirection_url": "https://example.com/"
}'

​
Authentication

This API requires Bearer token authentication using a JWT token:
HeaderTypeRequiredDescription
AuthorizationstringYesJWT Bearer token for API authentication
Content-TypestringYesMust be set to application/json

​
Request Body

FieldTypeRequiredDescription
redirection_urlstringYesThe URL where users will be redirected after completing the onboarding process. Must be a valid HTTPS URL.

​
Response

​
Success Response (200 OK)

When the onboarding initialization is successful, the API returns configuration details: 
{
  "status": "SUCCESS",
  "onboarding_url": "https://uat.pfm.equal.in/pfm?access_token=eyJhbGciOiJSUz.."
}
FieldTypeDescription
statusstringStatus of the API call. Will be SUCCESS for successful requests.
onboarding_urlstringThe complete URL to redirect users to for starting the onboarding process. Contains an access token as a query parameter.

​
Error Responses (400 Bad Request / 401 Unauthorized)

When the request fails due to authentication or validation issues, the API returns specific error responses: 
{
  "status": "FAILED",
  "message": "Redirection URL is missing or empty",
  "status_code": "no_redirect_url"
}
FieldTypeDescription
statusstringStatus of the API call. Will be FAILED for failed requests.
messagestringHuman-readable error message explaining what went wrong.
status_codestringMachine-readable error code for programmatic error handling.

​
Error Handling

Error CodeHTTP StatusDescriptionResolution
no_redirect_url400 Bad RequestThe redirection URL is missing or empty in the request bodyProvide a valid redirection URL in the request body
invalid_session_token401 UnauthorizedThe provided authorization token is invalid, expired, or malformedObtain a new valid JWT token for API authentication

​
Usage Flow

  1. Initialize Onboarding: Call this API with your redirection URL to get the link to PFM WebRD
  2. Redirect User: Use the returned onboarding_url to redirect users to the PFM onboarding flow
  3. Handle Completion: Users will be redirected back to your redirection_url when they close the WebRD. The redirection URL will include a query parameter journey_status with the following values:
    • journey_status=success: At least one consent was approved by the user and was successful
    • journey_status=failure: No consents were successfully approved
  4. Continue Flow: Use the session details to proceed with subsequent PFM operations

​
Security Considerations

  • HTTPS Only: Always use HTTPS for redirection URLs to ensure secure data transmission
  • Token Security: Handle JWT tokens securely and avoid logging them
  • Session Expiry: Monitor session expiry times and implement appropriate timeout handling
  • URL Validation: Validate that redirection URLs belong to your domain for security
  • Encryption Support: This API supports encryption. When encryption is enabled for your integration, both request and response payloads will be encrypted. See API Encryption Guide for details.