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

# FraudTrace AI Quickstart — Screen Your First UPI VPA

> Screen your first UPI VPA for mule activity in under five minutes using the FraudTrace AI MuleTrace API, your Bearer token, and a single GET request.

FraudTrace AI is designed to drop into your existing risk pipeline with minimal friction. This guide walks you through obtaining an API key, running your first UPI lookup against the MuleTrace database, interpreting the response, and wiring the call into your onboarding or transaction screening flow.

<Steps>
  <Step title="Get your API key">
    Access to FraudTrace AI is gated by a Bearer token issued to your organisation. To request one, reach out to the FraudTrace team through [fraudtraceai.com](https://fraudtraceai.com). Once your account is provisioned you will receive a token that looks like this:

    ```
    ft_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    ```

    Store this token in a secure secrets manager or environment variable — never commit it to source control.

    <Tip>
      If you need a sandbox key for testing before going live, mention that when you contact the team. Sandbox responses mirror the production schema but draw from a static fixture dataset.
    </Tip>
  </Step>

  <Step title="Make your first UPI lookup">
    Send a GET request to the `/v1/verify/upi` endpoint, passing the UPI VPA you want to screen as the `upi` query parameter. Include your Bearer token in the `Authorization` header on every request.

    ```bash theme={null}
    curl --request GET \
      --url "https://api.fraudtraceai.com/v1/verify/upi?upi=example@ybl" \
      --header "Authorization: Bearer YOUR_API_KEY"
    ```

    A successful call returns an HTTP `200` with a JSON body. Here is a representative **FLAGGED** response for a VPA that belongs to a known mule cluster:

    ```json theme={null}
    {
      "upi": "xxxxx@ybl",
      "status": "FLAGGED",
      "confidence": 0.94,
      "risk_category": "mule",
      "cluster_id": "MC-2104",
      "cluster_size": 7,
      "first_seen": "2025-11-14T08:22:00Z",
      "last_seen": "2026-04-01T16:45:00Z",
      "sources": [
        {
          "url": "https://bet-quick-in.com",
          "category": "gambling",
          "captured_at": "2025-12-01T10:00:00Z"
        },
        {
          "url": "https://spinwin-247.net",
          "category": "gambling",
          "captured_at": "2026-01-15T14:30:00Z"
        }
      ],
      "evidence_count": 3
    }
    ```

    And here is a **CLEARED** response for a VPA with no fraud signals:

    ```json theme={null}
    {
      "upi": "merchant@okicici",
      "status": "CLEARED",
      "confidence": 0.97,
      "risk_category": null,
      "cluster_id": null,
      "cluster_size": null,
      "first_seen": null,
      "last_seen": null,
      "sources": [],
      "evidence_count": 0
    }
    ```
  </Step>

  <Step title="Interpret the result">
    Use the following fields to drive your downstream risk decision:

    | Field            | Description                                                                                                                                      |
    | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `status`         | `FLAGGED` — the VPA has fraud signals. `CLEARED` — no signals found.                                                                             |
    | `confidence`     | A float from `0.0` to `1.0` indicating the model's certainty. Values above `0.90` warrant immediate action.                                      |
    | `cluster_id`     | Identifier for the mule cluster this VPA belongs to (e.g. `MC-2104`). A single cluster groups VPAs that share behavioural or network links.      |
    | `cluster_size`   | Number of VPAs in the same cluster. Larger clusters indicate organised mule networks.                                                            |
    | `sources`        | Array of evidence objects — each includes the source URL, category (e.g. `gambling`, `investment_scam`), and the timestamp when it was captured. |
    | `evidence_count` | Total number of discrete evidence items tied to this VPA across all sources.                                                                     |

    <Warning>
      A `CLEARED` result means the VPA is not present in the FraudTrace database at this time — it does not guarantee the account is legitimate. Always combine FraudTrace signals with your own transaction monitoring and KYC controls.
    </Warning>
  </Step>

  <Step title="Integrate into your risk flow">
    The MuleTrace API is stateless and low-latency, which makes it suitable for synchronous integration at the following control points:

    * **UPI payee screening** — call the API before you initiate a P2P or P2M transfer to verify the destination VPA.
    * **Merchant onboarding** — screen the settlement UPI ID provided during merchant sign-up. A `FLAGGED` result with high confidence should trigger manual review or rejection.
    * **Payout and disbursement checks** — validate beneficiary VPAs in lending, insurance, and government disbursement workflows before funds leave your ledger.
    * **Batch risk re-scoring** — periodically re-screen your existing beneficiary database to catch VPAs that were clean at onboarding but have since been flagged.

    <Tip>
      Set a confidence threshold in your code rather than hard-coding a binary check on `status`. For example, auto-block above `0.95`, route to manual review between `0.75` and `0.95`, and pass through below `0.75`.
    </Tip>
  </Step>
</Steps>