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

# Onboarding Init API

> Initialize the PFM onboarding process with redirection URL configuration

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

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

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api-uat.pfm.equal.in/pfm/onboarding/init', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'eyJhbGciOiJSUz..'
    },
    body: JSON.stringify({
      "redirection_url": "https://example.com/"
    })
  });

  const data = await response.json();
  console.log('Onboarding Init Response:', data);
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://api-uat.pfm.equal.in/pfm/onboarding/init"
  headers = {
      "Content-Type": "application/json",
      "Authorization": "eyJhbGciOiJSUz.."
  }

  payload = {
      "redirection_url": "https://example.com/"
  }

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```
</CodeGroup>

## Authentication

This API requires Bearer token authentication using a JWT token:

| Header          | Type   | Required | Description                             |
| --------------- | ------ | -------- | --------------------------------------- |
| `Authorization` | string | Yes      | JWT Bearer token for API authentication |
| `Content-Type`  | string | Yes      | Must be set to `application/json`       |

## Request Body

| Field             | Type   | Required | Description                                                                                                |
| ----------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------- |
| `redirection_url` | string | Yes      | The 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:

<ResponseExample>
  ```json Success Response theme={null}
  {
    "status": "SUCCESS",
    "onboarding_url": "https://uat.pfm.equal.in/pfm?access_token=eyJhbGciOiJSUz.."
  }
  ```
</ResponseExample>

| Field            | Type   | Description                                                                                                               |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| `status`         | string | Status of the API call. Will be `SUCCESS` for successful requests.                                                        |
| `onboarding_url` | string | The 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:

<CodeGroup>
  ```json Missing Redirection URL theme={null}
  {
    "status": "FAILED",
    "message": "Redirection URL is missing or empty",
    "status_code": "no_redirect_url"
  }
  ```

  ```json Invalid Session Token theme={null}
  {
    "status": "FAILED",
    "message": "INVALID SESSION TOKEN",
    "status_code": "invalid_session_token"
  }
  ```
</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.  |

## Error Handling

| Error Code              | HTTP Status      | Description                                                        | Resolution                                          |
| ----------------------- | ---------------- | ------------------------------------------------------------------ | --------------------------------------------------- |
| `no_redirect_url`       | 400 Bad Request  | The redirection URL is missing or empty in the request body        | Provide a valid redirection URL in the request body |
| `invalid_session_token` | 401 Unauthorized | The provided authorization token is invalid, expired, or malformed | Obtain 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](/pfm/api-encryption-overview) for details.