SDK Init API

Overview

The SDK Init API initializes a PFM SDK session for a specific user and returns a session token that can be used to launch the PFM interface. This API must be called from your backend server before launching the PFM SDK on the client side.

Example Request

curl --location 'https://api-uat.pfm.equal.in/pfm/sdk/init' \
--header 'authorization: Basic {{base64_encoded_clientId:clientSecret}}' \
--header 'content-type: application/json' \
--data '{
    "reference_id": "user_ref_12345",
    "pfm_config_id": "your_pfm_config_id",
    "user_profile": {
        "mobile_number": "9876543210",
        "name": "John Doe",
        "dob": "15-01-1990",
        "pan": "ABCDE1234F"
    }
}'

const response = await fetch('https://api-uat.pfm.equal.in/pfm/sdk/init', {
  method: 'POST',
  headers: {
    'authorization': 'Basic ' + btoa(clientId + ':' + clientSecret),
    'content-type': 'application/json'
  },
  body: JSON.stringify({
    reference_id: 'user_ref_12345',
    pfm_config_id: 'your_pfm_config_id',
    user_profile: {
      mobile_number: '9876543210',
      name: 'John Doe',
      dob: '15-01-1990',
      pan: 'ABCDE1234F'
    }
  })
});

const data = await response.json();
console.log('Session Token:', data.session_token);

import requests
import base64

# Encode credentials
credentials = base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()

url = "https://api-uat.pfm.equal.in/pfm/sdk/init"
headers = {
    "authorization": f"Basic {credentials}",
    "content-type": "application/json"
}
payload = {
    "reference_id": "user_ref_12345",
    "pfm_config_id": "your_pfm_config_id",
    "user_profile": {
        "mobile_number": "9876543210",
        "name": "John Doe",
        "dob": "15-01-1990",
        "pan": "ABCDE1234F"
    }
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Authentication

This API requires authentication through the following headers that must be included in every request:

Header	Type	Required	Description
`authorization`	string	Yes	Basic authentication header with base64 encoded `clientId:clientSecret`
`content-type`	string	Yes	Must be set to `application/json`

Request Body

The request body must be a JSON object containing the following parameters:

Parameter	Type	Required	Description
`reference_id`	string	Yes	Unique identifier for an user. Use this to track users as your end.
`pfm_config_id`	string	Yes	PFM configuration identifier that determines the specific PFM setup to use for this user.
`user_profile`	object	Yes	User profile information required for PFM initialization.
`user_profile.mobile_number`	string	Yes	User’s mobile number for identification and communication.
`user_profile.name`	string	No	User’s full name as it appears in their identity documents.
`user_profile.dob`	string	No	User’s date of birth in DD-MM-YYYY format.
`user_profile.pan`	string	Yes	User’s PAN (Permanent Account Number) for identity verification.

Response

Success Response (200 OK)

When the SDK initialization is successful, the API returns a session token:

{
  "status": "SUCCESS",
  "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Field	Type	Description
`status`	string	Status of the API call. Will be `SUCCESS` for successful requests.
`session_token`	string	JWT session token to be used for launching the PFM SDK. This token has a limited validity period.

Error Responses (400 Bad Request)

When the request contains invalid data or missing required fields, the API returns specific error responses:

{
  "status": "FAILED",
  "message": "PAN can't be empty or null",
  "status_code": "invalid_pan_number",
  "is_retryable": false
}

{
  "status": "FAILED",
  "message": "Mobile Number can't be empty or null",
  "status_code": "invalid_mobile_number",
  "is_retryable": false
}

{
  "status": "FAILED",
  "message": "Invalid pfm_config_id value",
  "status_code": "invalid_pfm_config_id",
  "is_retryable": false
}

{
  "status": "FAILED",
  "message": "reference_id can't be empty or null",
  "status_code": "invalid_reference_id",
  "is_retryable": false
}

Field	Type	Description
`status`	string	Status of the API call. Will be `FAILED` for failed requests.
`message`	string	Human-readable error message explaining what went wrong.
`status_code`	string	Machine-readable error code for programmatic error handling.
`is_retryable`	boolean	Indicates whether the request can be retried. `false` means the request should not be retried without fixing the input.

Error Handling

Error Code	HTTP Status	Description	Resolution
`invalid_pan_number`	400 Bad Request	PAN number is missing or empty	Ensure the `user_profile.pan` field is provided with a valid PAN number
`invalid_mobile_number`	400 Bad Request	Mobile number is missing or empty	Ensure the `user_profile.mobile_number` field is provided with a valid mobile number
`invalid_pfm_config_id`	400 Bad Request	PFM configuration ID is invalid or missing	Verify the `pfm_config_id` value with your PFM configuration setup
`invalid_reference_id`	400 Bad Request	Reference ID is missing or empty	Ensure the `reference_id` field is provided with a unique identifier

Next Steps

After successfully obtaining the session token from this API:

Store the Token: Keep the session token secure and use it immediately as it has a limited validity period
Launch SDK: Use the session token to initialize and launch the PFM SDK in your client application
Handle Expiry: If the token expires, call this API again to get a new session token

Security Considerations

Client Credentials: Never expose your client ID and secret in client-side code
Token Storage: Handle session tokens securely and avoid logging them
HTTPS Only: Always use HTTPS when calling this API
Token Expiry: Implement proper token refresh logic for long-running sessions
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.

PFM Overview

Architecture

Analytics Data Dictionary

Integration Guide

API Encryption Guide

PFM APIs

Scheduled Data Sharing

Overview

Example Request

Authentication

Request Body

Response

Success Response (200 OK)

Error Responses (400 Bad Request)

Error Handling

Next Steps

Security Considerations

​Overview

​Example Request

​Authentication

​Request Body

​Response

​Success Response (200 OK)

​Error Responses (400 Bad Request)

​Error Handling

​Next Steps

​Security Considerations

Overview

Example Request

Authentication

Request Body

Response

Success Response (200 OK)

Error Responses (400 Bad Request)

Error Handling

Next Steps

Security Considerations