Key Benefits

• Track journey progress in real time without relying solely on redirects
• Detect terminal states — consent denial, failure, or session expiry — and handle them gracefully
• Use alongside webhook_url for push-based notifications to avoid polling overhead
• Single lightweight GET call — no request body required

Polling Strategy

Poll every 5–10 seconds after the user is redirected to journey_url. Stop polling when the status reaches any terminal state: analysis_complete, consent_denied, failed, or expired. To eliminate polling altogether, use the webhook_url parameter in /init to receive push notifications on every status change.
:::

Example Successful Response

{
  "success": true,
  "message": "Journey status fetched successfully",
  "data": {
    "client_id": "bsa_clnt_a1b2c3d4e5f6",
    "status": "analysis_complete",
    "consent_type": "loan_underwriting",
    "mobile_number": "98765*****",
    "updated_at": "2024-11-15T13:47:22Z"
  }
}

Possible Error Responses

Integration Best Practices

Code Samples

client_id = "bsa_clnt_a1b2c3d4e5f6"
url = f"https://api.finpass.ai/aa-bsa-journey/status?client_id={client_id}"

headers = {
"X-API-KEY": "<your_api_key>",
"X-API-SECRET": "<your_api_secret>"
}

terminal_statuses = {"analysis_complete", "consent_denied", "failed", "expired"}

while True:
response = requests.get(url, headers=headers)
data = response.json()
status = data["data"]["status"]
print("Current status:", status)

if status in terminal_statuses:
print("Terminal status reached:", status)
break

time.sleep(5)

</Tab>
<Tab title="Node.js">
```javascript
const axios = require("axios");

const clientId = "bsa_clnt_a1b2c3d4e5f6";
const url = `https://api.finpass.ai/aa-bsa-journey/status?client_id=${clientId}`;

const headers = {
  "X-API-KEY": "<your_api_key>",
  "X-API-SECRET": "<your_api_secret>"
};

const terminalStatuses = new Set(["analysis_complete", "consent_denied", "failed", "expired"]);

const pollStatus = async () => {
  const response = await axios.get(url, { headers });
  const { status } = response.data.data;
  console.log("Current status:", status);

  if (!terminalStatuses.has(status)) {
    setTimeout(pollStatus, 5000);
  } else {
    console.log("Terminal status reached:", status);
  }
};

pollStatus().catch(err => console.error("Error:", err.response?.data || err.message));