# User Check API Documentation

### Endpoint

`POST /check/user`

Perform real-time verification checks on IP addresses, email addresses, and phone numbers.

### Authentication

Requires a valid **User API Key** passed in the `X-API-Key` header.

```
X-API-Key: your_user_api_key_here
```

### Request Body

| Field          | Type    | Required | Description                                                                      |
| -------------- | ------- | -------- | -------------------------------------------------------------------------------- |
| `ip`           | string  | No\*     | Valid IPv4 or IPv6 address (e.g., `"1.1.1.1"`)                                   |
| `email`        | string  | No\*     | Valid email address (e.g., `"user@example.com"`)                                 |
| `phone`        | string  | No\*     | Phone number in E.123 format (e.g., `"+1 650-253-0000"`)                         |
| `include_slow` | boolean | No       | Include slower comprehensive checks (port scans and ping scans). Default: `true` |

\*At least one of `ip`, `email`, or `phone` must be provided.

### Example Request

```bash
curl -X POST "https://api.checkmyip.bot/check/user" \
  -H "X-API-Key: your_user_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "8.8.8.8",
    "email": "test@gmail.com",
    "phone": "+1 650-253-0000",
    "include_slow": false
  }'
```

```json
{
  "ip": "8.8.8.8",
  "email": "test@gmail.com",
  "phone": "+1 650-253-0000",
  "include_slow": false
}
```

#### Python Example

```python
import requests

url = "https://api.checkmyip.bot/check/user"
headers = {
    "X-API-Key": "your_user_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "ip": "8.8.8.8",
    "email": "test@gmail.com",
    "phone": "+1 650-253-0000",
    "include_slow": False
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

# Access results
for result in data["results"]:
    print(result)
```

### Response

Returns a JSON object containing an array of check results. The response includes:

* Individual check results for each requested verification type (IP, email, phone)
* Final status message indicating completion or failure

#### Response Format

```json
{
  "results": [
    {
      "email": {
        "service_name": {
          "status": "success",
          "data": { ... }
        }
      }
    },
    {
      "phone": {
        "service_name": {
          "status": "success",
          "data": { ... }
        }
      }
    },
    {
      "ip": {
        "fast": {
          "status": "success",
          "data": { ... },
          "checked_in_days": {
            "days": 30,
            "count": 5
          }
        },
        "slow": {
          "status": "success",
          "data": { ... }
        }
      }
    },
    {
      "type": "status",
      "status": "completed",
      "message": "Check completed successfully",
      "check_id": 12345
    }
  ]
}
```

#### Response Status Codes

* `200 OK` - Request successful
* `400 Bad Request` - Invalid request data
* `401 Unauthorized` - Invalid or missing API key
* `429 Too Many Requests` - Rate limiting

### Parameters

#### `include_slow`

* **Type**: `boolean`
* **Default**: `true`
* **Description**: Controls whether to include slower, more comprehensive checks including port scans and ping scans

When set to `false`:

* Returns faster results
* Skips port scans and ping scans

When set to `true` (default):

* Includes port scans and ping scans
* Waits for additional slower checks

### Validation Rules

#### IP Address

* Must be a valid IPv4 or IPv6 address
* Private IP addresses (e.g., `192.168.x.x`, `10.x.x.x`) are **not allowed**
* Loopback addresses (e.g., `127.0.0.1`) are **not allowed**
* Link-local IPv6 addresses are **not allowed**

#### Email Address

* Must be a valid email format
* Check availability depends on your subscription plan

#### Phone Number

* Must be in E.123 international format (e.g., `+1 650-253-0000`)
* Must include country code with `+` prefix
* Must be a valid phone number

### Error Responses

#### Quota Exceeded

```json
{
  "results": [
    {
      "type": "status",
      "status": "quota_exceeded",
      "message": "API quota exceeded for this user"
    }
  ]
}
```

#### No Valid Checks

```json
{
  "results": [
    {
      "type": "status",
      "status": "no_valid_checks",
      "message": "No valid checks can be performed with provided data",
      "checks": {
        "ip": { "provided": false, "allowed_by_plan": true, "can_perform": false },
        "email": { "provided": false, "allowed_by_plan": false, "can_perform": false },
        "phone": { "provided": false, "allowed_by_plan": false, "can_perform": false }
      }
    }
  ]
}
```