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

# POST /flow/init — Initialize Chat Onboarding Flow

> Create a verification flow and primary applicant for chat-based onboarding. Every onboarding journey starts with a flow.

A flow represents a single loan application and applicant journey inside Atlas. Before documents can be uploaded or chat interactions can begin, you must create a flow using this endpoint.

A flow is uniquely identified by the combination of:

* `application_id`
* `external_reference_id`

## Endpoint

```text theme={null}
POST /verification/flow/init
```

## Request headers

<ParamField header="Token" type="string" required>
  JWT access token obtained from the authentication API.
</ParamField>

## Request body

<ParamField body="product_type" type="string" required>
  Product configuration assigned to your organization. This determines the onboarding journey, required documents, validations, and chat behaviour.
</ParamField>

<ParamField body="application_id" type="string" required>
  Your internal application identifier. This should uniquely identify the loan or onboarding case in your system.
</ParamField>

<ParamField body="external_reference_id" type="string" required>
  Unique identifier for the primary applicant within the application.
</ParamField>

<ParamField body="username" type="string" required>
  Name of the primary applicant.
</ParamField>

<ParamField body="user_docs" type="array">
  List of expected document types for the primary applicant.

  Example:

  ```json theme={null}
  [
    "PAN",
    "AADHAAR",
    "BANK_STATEMENT"
  ]
  ```
</ParamField>

<ParamField body="callback_url" type="string">
  URL where Atlas sends extracted document data and verification results once processing is complete.
</ParamField>

<ParamField body="chat_notification_url" type="string">
  Optional webhook URL that receives chat-related events and notifications from Atlas.
</ParamField>

<ParamField body="auth_token_url" type="string">
  Authentication endpoint Atlas can call to obtain authorization before sending callbacks to your systems.
</ParamField>

<ParamField body="flow_params" type="object">
  Optional key-value configuration object. Atlas stores and returns these parameters with the flow.
</ParamField>

## Response

<ResponseField name="flow_id" type="string">
  UUID generated by Atlas that uniquely identifies this onboarding flow.
</ResponseField>

<ResponseField name="application_id" type="string">
  Application identifier supplied during flow creation.
</ResponseField>

<ResponseField name="external_reference_id" type="string">
  Primary applicant identifier supplied during flow creation.
</ResponseField>

<ResponseField name="username" type="string">
  Applicant name associated with the flow.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.helloatlas.in/v2/verification/flow/init \
    --header "Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
    --header "Content-Type: application/json" \
    --data '{
      "product_type": "MSME_OD",
      "application_id": "APP-10001",
      "external_reference_id": "CUST-9283",
      "username": "Rahul Sharma",
      "user_docs": [
        "PAN",
        "AADHAAR",
        "BANK_STATEMENT"
      ],
      "callback_url": "https://your-system.com/atlas/callback",
      "chat_notification_url": "https://your-system.com/atlas/chat-events",
      "auth_token_url": "https://your-system.com/atlas/auth",
      "flow_params": {
        "branch": "Mumbai",
        "channel": "DSA"
      }
    }'
  ```

  ```json 201 Created theme={null}
  {
    "flow_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "application_id": "APP-10001",
    "external_reference_id": "CUST-9283",
    "username": "Rahul Sharma"
  }
  ```
</CodeGroup>

## Callback support

Atlas supports asynchronous delivery of verification results.

Provide the following URLs during flow creation:

| Field                   | Purpose                                                         |
| ----------------------- | --------------------------------------------------------------- |
| `callback_url`          | Receives extracted document data and verification results       |
| `auth_token_url`        | Used by Atlas to obtain authentication before posting callbacks |
| `chat_notification_url` | Receives chat events and onboarding notifications               |

Atlas maintains the callback configuration against the flow and automatically pushes updates as onboarding progresses.

## Error responses

| Status | Meaning                                                                                             |
| ------ | --------------------------------------------------------------------------------------------------- |
| `400`  | Missing or invalid request parameters.                                                              |
| `401`  | Invalid or expired access token.                                                                    |
| `409`  | A flow already exists for the supplied combination of `application_id` and `external_reference_id`. |

<Tip>
  Store the returned `flow_id` securely. Every subsequent onboarding API call—including uploads, chat messages, status checks, checklist retrieval, co-applicant management, and final submission—requires this identifier.
</Tip>