# VIP API

#### GET /vip-report

Returns the Verified Income Profile for a user. The VIP is generated on-demand and cached for 24 hours. To force a refresh, pass `refresh=true`.

This endpoint requires both a wallet connection and a platform connection to be active. If either is missing, a `422 Unprocessable Entity` error is returned with the specific missing dependency. The platform connection may be a payroll provider, neobank, exchange, or any other supported source type.

http

```http
GET /vip-report?user_id=usr_01J2K...
Authorization: Bearer sk_live_xxxx
```

**Query parameters**

| Parameter         | Type    | Description                                                                   |
| ----------------- | ------- | ----------------------------------------------------------------------------- |
| `user_id`         | string  | Required.                                                                     |
| `refresh`         | boolean | Optional. Default `false`. Forces a full re-run of the verification pipeline. |
| `lookback_months` | integer | Optional. Default 6. Number of months of history to verify. Max 12.           |

**Response**

json

```json
{
  "vip_report": {
    "id": "vip_4DrM...",
    "user_id": "usr_01J2K...",
    "generated_at": "2024-12-01T09:00:00Z",
    "status": "verified",
    "verified_monthly_income_usd": 4500.00,
    "income_currency": "USDC",
    "verification_method": "deterministic_match",
    "data_source_type": "neobank_account",
    "data_source_platform": "dolarapp",
    "periods_verified": 6,
    "periods_requested": 6,
    "consistency_rate": 1.0,
    "average_verified_amount": 4500.00,
    "income_variance": 0.0,
    "verified_periods": [
      {
        "period": "2024-11",
        "expected_amount": 4500.00,
        "received_amount": 4500.00,
        "tx_hash": "0xabc123def456...",
        "payout_date": "2024-11-30",
        "block_timestamp": "2024-11-30T14:22:00Z",
        "origin_address": "0xDeel1234...AbCd",
        "match_confidence": "exact",
        "verified": true
      },
      {
        "period": "2024-10",
        "expected_amount": 4500.00,
        "received_amount": 4500.00,
        "tx_hash": "0xdef456ghi789...",
        "payout_date": "2024-10-31",
        "block_timestamp": "2024-10-31T13:55:00Z",
        "origin_address": "0xDeel1234...AbCd",
        "match_confidence": "exact",
        "verified": true
      }
    ],
    "unverified_periods": [],
    "fraud_flags": [],
    "wallet_address": "0xUser5678...EfGh",
    "network": "polygon"
  }
}
```

**VIP status values**

| Status               | Description                                                                                                                       |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `verified`           | All requested periods matched successfully.                                                                                       |
| `partially_verified` | Some periods matched; others could not be reconciled. `unverified_periods` array is populated.                                    |
| `unverified`         | No periods could be matched. May indicate a new user, incorrect wallet, platform data mismatch, or insufficient on-chain history. |
| `pending`            | Verification is in progress. Poll again after 30 seconds or await the `vip.generated` webhook.                                    |
| `error`              | The pipeline encountered an unrecoverable error. See `error_code` field.                                                          |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rupi.global/core-documentation/markdown/vip-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.