# Mobile API: Verify Endpoint Documentation

## Overview

The Verify endpoint validates an API key and returns comprehensive user information along with associated stores and any linked employee records. This is useful for app initialization, validating stored credentials, and determining user permissions per store.

## Endpoint

```
POST /api/mobile/verify
```

## Authentication

Requires the `APIKey` parameter in the POST body.

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `APIKey` | string | Yes | The API key to verify |

## Example Request

```bash
curl -X POST "https://buyerkiosk.com/api/mobile/verify" \
  -d "APIKey=your_api_key_here"
```

## Success Response (HTTP 200)

```json
{
  "success": true,
  "user": {
    "id": 4,
    "username": "rvanvuren",
    "email": "ryan@v2ts.com",
    "displayName": "Ryan VanVuren",
    "firstName": "Ryan",
    "lastName": "VanVuren",
    "title": "BuyerKiosk Admin",
    "locale": "en_US"
  },
  "stores": [
    {
      "typeNum": "ou00",
      "storeType": 2,
      "storeCity": "Demo",
      "storeName": "Once Upon a Child",
      "employee": null
    },
    {
      "typeNum": "pc00",
      "storeType": 1,
      "storeCity": "Anna",
      "storeName": "Plato's Closet",
      "employee": {
        "employeeId": 35194463,
        "firstName": "Ryan",
        "lastName": "VanVuren",
        "fullName": "Ryan VanVuren",
        "role": 4,
        "active": true,
        "linkType": "manual",
        "linkedAt": "2025-12-01 20:02:22"
      }
    },
    {
      "typeNum": "se00",
      "storeType": 3,
      "storeCity": "Demo",
      "storeName": "Style Encore",
      "employee": null
    }
  ],
  "storeCount": 3
}
```

## Response Fields

### User Object

| Field | Type | Description |
|-------|------|-------------|
| `id` | int | User ID in the system |
| `username` | string | Login username |
| `email` | string | User's email address |
| `displayName` | string | Full display name |
| `firstName` | string | First name (parsed from displayName) |
| `lastName` | string | Last name (parsed from displayName) |
| `title` | string | User's title/role description |
| `locale` | string | User's locale setting (e.g., "en_US") |

### Store Object

| Field | Type | Description |
|-------|------|-------------|
| `typeNum` | string | Store identifier (e.g., "pc00", "ou01") |
| `storeType` | int | Store type code (1=Plato's Closet, 2=Once Upon, 3=Style Encore, etc.) |
| `storeCity` | string | City where store is located |
| `storeName` | string | Full store/company name |
| `employee` | object\|null | Linked employee record, or null if not linked |

### Employee Object (when linked)

| Field | Type | Description |
|-------|------|-------------|
| `employeeId` | int | Employee ID in the store's database |
| `firstName` | string | Employee's first name |
| `lastName` | string | Employee's last name |
| `fullName` | string | Combined first and last name |
| `role` | int | Employee role level (1=Admin, 2=Manager, 3=Buyer, 4=Employee) |
| `active` | bool | Whether the employee record is active |
| `linkType` | string | How the link was created (see Link Types below) |
| `linkedAt` | string | Timestamp when the link was created |

### Link Types

| Type | Description |
|------|-------------|
| `manual` | Manually linked by an administrator |
| `auto_name` | Automatically linked by matching display name |
| `auto_login` | Automatically linked by matching username/login |
| `promotion` | Created when employee was promoted to user account |

## Error Responses

### Invalid API Key Format (HTTP 400)

```json
{
  "success": false,
  "error": "Invalid API key format"
}
```

### Invalid API Key (HTTP 401)

```json
{
  "success": false,
  "error": "Invalid API key"
}
```

### User Account Not Found (HTTP 401)

```json
{
  "success": false,
  "error": "User account not found"
}
```

### User Account Disabled (HTTP 403)

```json
{
  "success": false,
  "error": "User account is disabled"
}
```

### Missing API Key (HTTP 400)

```json
{
  "error": "Missing APIKey parameter"
}
```

### Server Error (HTTP 500)

```json
{
  "error": "An internal error occurred"
}
```

## Store Type Codes

| Code | Brand |
|------|-------|
| 1 | Plato's Closet |
| 2 | Once Upon a Child |
| 3 | Style Encore |
| 4 | Clothes Mentor |
| 5 | Home Once More |
| 6 | Play It Again Sports |

## Usage Notes

1. **App Initialization**: Call this endpoint when the app starts to verify the stored API key is still valid and get current user/store information.

2. **Employee Links**: The `employee` field in each store indicates whether the user has a linked employee record. This is important for:
   - Determining if the user can perform employee-specific actions (e.g., clock in, complete tasks)
   - Pre-filling the `employeeId` parameter in other API calls
   - Showing employee-specific UI features

3. **Inactive Stores**: Stores that are inactive in the system are automatically filtered out of the response.

4. **Role Levels**: The employee `role` field indicates permission level:
   - 1 = Administrator (full access)
   - 2 = Manager (most features)
   - 3 = Buyer (buying-specific features)
   - 4 = Employee (basic features)

5. **Caching**: Consider caching the verify response locally and refreshing periodically or on app foreground to reduce API calls.

## Example: Checking for Employee Access

```dart
// Flutter/Dart example
final response = await api.verify(apiKey);

if (response.success) {
  final user = response.user;

  for (final store in response.stores) {
    if (store.employee != null) {
      print('${store.storeName}: Linked as ${store.employee.fullName}');
      // User can perform employee actions in this store
    } else {
      print('${store.storeName}: No employee link');
      // User has view-only access or needs to be linked
    }
  }
}
```