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

# Request Status

> Get request status and results by ID

# Request Status

Retrieve the status and results of a verification request by its ID. Use this endpoint to poll for results if you're not using webhooks.

## Overview

After submitting a verification request, you receive a request ID. Use this endpoint to:

* Check the current status of a request
* Retrieve verification results when completed
* Get error details if the request failed
* Verify webhook delivery status

## Request

### Path Parameters

<ParamField path="id" type="string" required>
  The unique request ID (UUID) returned when the verification request was submitted.
</ParamField>

### Headers

| Header      | Value        | Required |
| ----------- | ------------ | -------- |
| `X-API-Key` | Your API key | Yes      |

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.txncheck.in/api/v1/requests/550e8400-e29b-41d4-a716-446655440000" \
    -H "X-API-Key: fb_your_api_key_here"
  ```

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

  request_id = "550e8400-e29b-41d4-a716-446655440000"
  response = requests.get(
      f"https://api.txncheck.in/api/v1/requests/{request_id}",
      headers={"X-API-Key": "fb_your_api_key_here"}
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const requestId = '550e8400-e29b-41d4-a716-446655440000';
  const response = await axios.get(
    `https://api.txncheck.in/api/v1/requests/${requestId}`,
    {
      headers: { 'X-API-Key': 'fb_your_api_key_here' }
    }
  );
  console.log(response.data);
  ```

  ```php PHP theme={null}
  <?php
  $requestId = "550e8400-e29b-41d4-a716-446655440000";
  $ch = curl_init("https://api.txncheck.in/api/v1/requests/{$requestId}");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "X-API-Key: fb_your_api_key_here"
  ]);
  $response = curl_exec($ch);
  curl_close($ch);
  echo $response;
  ```

  ```go Go theme={null}
  requestId := "550e8400-e29b-41d4-a716-446655440000"
  req, _ := http.NewRequest("GET", fmt.Sprintf("https://api.txncheck.in/api/v1/requests/%s", requestId), nil)
  req.Header.Set("X-API-Key", "fb_your_api_key_here")

  client := &http.Client{}
  resp, _ := client.Do(req)
  ```
</CodeGroup>

## Response

### 200 OK - Queued

Request is waiting for processing.

```json theme={null}
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "upi-by-mobile",
  "status": "QUEUED",
  "webhookStatus": "PENDING",
  "createdAt": "2025-01-11T10:30:00.000Z"
}
```

### 200 OK - Processing

Request is currently being processed.

```json theme={null}
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "upi-by-mobile",
  "status": "PROCESSING",
  "webhookStatus": "PENDING",
  "createdAt": "2025-01-11T10:30:00.000Z"
}
```

### 200 OK - Completed

Request completed successfully with results.

```json theme={null}
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "upi-by-mobile",
  "status": "COMPLETED",
  "result": {
    "name": "JOHN DOE",
    "upi": [
      "johndoe@upi",
      "9876543210@paytm"
    ],
    "status": "1"
  },
  "webhookStatus": "SENT",
  "createdAt": "2025-01-11T10:30:00.000Z",
  "completedAt": "2025-01-11T10:30:05.000Z"
}
```

### 200 OK - Failed

Request failed with error details.

```json theme={null}
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "upi-by-mobile",
  "status": "FAILED",
  "error": {
    "class": "PROVIDER_BUSINESS_ERROR",
    "message": "Mobile number not found in UPI system"
  },
  "webhookStatus": "SENT",
  "createdAt": "2025-01-11T10:30:00.000Z",
  "completedAt": "2025-01-11T10:30:05.000Z"
}
```

### 200 OK - Partial (Full Check)

Some steps completed, others failed.

```json theme={null}
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "full-check",
  "status": "PARTIAL",
  "stepStatuses": {
    "upiByMobile": "ok",
    "kycByMobile": "failed",
    "vpaChargebackCheck": "ok"
  },
  "result": {
    "upiByMobile": { ... },
    "vpaChargebackCheck": {
      "vpas": [
        {"vpa": "johndoe@upi", "isBlocklisted": false}
      ]
    }
  },
  "error": {
    "kycByMobile": {
      "class": "PROVIDER_TEMPORARY",
      "message": "Service temporarily unavailable"
    }
  },
  "webhookStatus": "SENT",
  "createdAt": "2025-01-11T10:30:00.000Z",
  "completedAt": "2025-01-11T10:30:10.000Z"
}
```

### Response Fields

| Field           | Type   | Description                               |
| --------------- | ------ | ----------------------------------------- |
| `requestId`     | string | Unique request identifier                 |
| `method`        | string | Verification method used                  |
| `status`        | string | Current status (see below)                |
| `result`        | object | Verification results (if completed)       |
| `error`         | object | Error details (if failed)                 |
| `stepStatuses`  | object | Individual step statuses (for full-check) |
| `webhookStatus` | string | Webhook delivery status                   |
| `createdAt`     | string | Request creation timestamp                |
| `completedAt`   | string | Request completion timestamp              |

### Request Statuses

| Status       | Description                                     |
| ------------ | ----------------------------------------------- |
| `QUEUED`     | Request received and waiting for processing     |
| `PROCESSING` | Request is being processed                      |
| `COMPLETED`  | Request completed successfully                  |
| `FAILED`     | Request failed (check error details)            |
| `PARTIAL`    | Request partially completed (some steps failed) |

### Webhook Statuses

| Status     | Description                               |
| ---------- | ----------------------------------------- |
| `PENDING`  | Webhook not yet sent                      |
| `SENT`     | Webhook delivered successfully            |
| `RETRYING` | Webhook delivery failed, retrying         |
| `FAILED`   | Webhook delivery failed after all retries |

## Error Responses

### 401 Unauthorized

Invalid or missing API key.

```json theme={null}
{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}
```

### 404 Not Found

Request not found or doesn't belong to your merchant.

```json theme={null}
{
  "statusCode": 404,
  "message": "Request not found",
  "error": "Not Found"
}
```

## Polling Best Practices

When polling for results:

<CardGroup cols={2}>
  <Card title="Use Exponential Backoff" icon="clock">
    Start with 1-2 seconds, increase delay progressively
  </Card>

  <Card title="Set a Timeout" icon="stopwatch">
    Don't poll indefinitely - set a maximum duration
  </Card>

  <Card title="Prefer Webhooks" icon="webhook">
    Webhooks are more efficient than polling
  </Card>

  <Card title="Check Terminal States" icon="flag-checkered">
    Stop polling when status is COMPLETED, FAILED, or PARTIAL
  </Card>
</CardGroup>

### Example Polling Implementation

```javascript theme={null}
async function pollForResult(requestId, maxAttempts = 30, initialDelay = 1000) {
  let attempt = 0;
  let delay = initialDelay;
  
  while (attempt < maxAttempts) {
    const response = await fetch(
      `https://api.txncheck.in/api/v1/requests/${requestId}`,
      { headers: { 'X-API-Key': API_KEY } }
    );
    
    const data = await response.json();
    
    // Check for terminal states
    if (['COMPLETED', 'FAILED', 'PARTIAL'].includes(data.status)) {
      return data;
    }
    
    // Wait before next attempt
    await new Promise(resolve => setTimeout(resolve, delay));
    
    // Increase delay (max 10 seconds)
    delay = Math.min(delay * 1.5, 10000);
    attempt++;
  }
  
  throw new Error('Polling timeout - request still processing');
}

// Usage
try {
  const result = await pollForResult('550e8400-e29b-41d4-a716-446655440000');
  console.log('Verification result:', result);
} catch (error) {
  console.error('Polling failed:', error.message);
}
```