> ## Documentation Index
> Fetch the complete documentation index at: https://developer.moneyone.in/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Init API

> Initialize PFM SDK session and retrieve authentication tokens for user onboarding

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

<CodeGroup>
  ```bash cURL theme={null}
  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"
      }
  }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

## 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:

<ResponseExample>
  ```json Success Response theme={null}
  {
    "status": "SUCCESS",
    "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
  ```
</ResponseExample>

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

<CodeGroup>
  ```json Invalid PAN Response theme={null}
  {
    "status": "FAILED",
    "message": "PAN can't be empty or null",
    "status_code": "invalid_pan_number",
    "is_retryable": false
  }
  ```

  ```json Invalid Mobile Number Response theme={null}
  {
    "status": "FAILED",
    "message": "Mobile Number can't be empty or null",
    "status_code": "invalid_mobile_number",
    "is_retryable": false
  }
  ```

  ```json Invalid Config ID Response theme={null}
  {
    "status": "FAILED",
    "message": "Invalid pfm_config_id value",
    "status_code": "invalid_pfm_config_id",
    "is_retryable": false
  }
  ```

  ```json Invalid Reference ID Response theme={null}
  {
    "status": "FAILED",
    "message": "reference_id can't be empty or null",
    "status_code": "invalid_reference_id",
    "is_retryable": false
  }
  ```
</CodeGroup>

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

1. **Store the Token**: Keep the session token secure and use it immediately as it has a limited validity period
2. **Launch SDK**: Use the session token to initialize and launch the PFM SDK in your client application
3. **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](/pfm/api-encryption-overview) for details.