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

# schemas

# Customer Device Management Schemas

API endpoints for linking and managing customer devices for seamless merchant interactions.

## Endpoints

| Method | Endpoint                          | Description                    |
| ------ | --------------------------------- | ------------------------------ |
| POST   | `/v1/bank/customer/device/link`   | Link device to customer phrase |
| POST   | `/v1/bank/customer/device/unlink` | Unlink device from customer    |
| GET    | `/v1/bank/devices/list`           | List customer devices          |
| POST   | `/v1/customer/device/lookup`      | Lookup customer by device      |

## POST /v1/bank/customer/device/link

Link a customer's device to their unique phrase for merchant recognition.

### Request Body

```json theme={null}
{
  "customerId": "string",
  "phrase": "string",
  "deviceId": "string"
}
```

### Request Schema

| Field        | Type   | Required | Description               |
| ------------ | ------ | -------- | ------------------------- |
| `customerId` | string | Yes      | Customer identifier       |
| `phrase`     | string | Yes      | Customer's unique phrase  |
| `deviceId`   | string | Yes      | Device identifier to link |

### Response Schema

```json theme={null}
{
  "statusCode": 200,
  "success": true,
  "message": "Device linked successfully"
}
```

## POST /v1/bank/customer/device/unlink

Remove the link between a customer's device and their phrase.

### Request Body

```json theme={null}
{
  "customerId": "string",
  "phrase": "string",
  "deviceId": "string"
}
```

### Request Schema

| Field        | Type   | Required | Description                 |
| ------------ | ------ | -------- | --------------------------- |
| `customerId` | string | Yes      | Customer identifier         |
| `phrase`     | string | Yes      | Customer's unique phrase    |
| `deviceId`   | string | Yes      | Device identifier to unlink |

### Response Schema

```json theme={null}
{
  "statusCode": 200,
  "success": true,
  "message": "Device unlinked successfully"
}
```

## GET /v1/bank/devices/list

Retrieve list of customer devices linked to your bank.

### Query Parameters

| Parameter   | Type   | Required | Description                              |
| ----------- | ------ | -------- | ---------------------------------------- |
| `page`      | number | No       | Page number for pagination (default: 1)  |
| `limit`     | number | No       | Number of results per page (default: 20) |
| `search`    | string | No       | Search by customer or device information |
| `sortBy`    | string | No       | Field to sort by                         |
| `sortOrder` | string | No       | Sort order (asc or desc)                 |

### Response Schema

```json theme={null}
{
  "statusCode": 200,
  "success": true,
  "data": {
    "devices": [
      {
        "deviceId": "string",
        "customerId": "string",
        "phrase": "string",
        "linkedAt": "string"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}
```

### Device List Schema

| Field        | Type   | Description              |
| ------------ | ------ | ------------------------ |
| `deviceId`   | string | Device identifier        |
| `customerId` | string | Associated customer ID   |
| `phrase`     | string | Customer's unique phrase |
| `linkedAt`   | string | Device linking timestamp |

## POST /v1/customer/device/lookup

Lookup customer information using device identifier (used by merchants).

### Request Body

```json theme={null}
{
  "deviceId": "string"
}
```

### Request Schema

| Field      | Type   | Required | Description                  |
| ---------- | ------ | -------- | ---------------------------- |
| `deviceId` | string | Yes      | Device identifier for lookup |

### Response Schema

```json theme={null}
{
  "statusCode": 200,
  "success": true,
  "message": "Device lookup successful",
  "data": {
    "deviceId": "string",
    "phrase": "string",
    "customerId": "string",
    "bankId": "string"
  }
}
```

### Device Lookup Response Schema

| Field        | Type   | Description          |
| ------------ | ------ | -------------------- |
| `deviceId`   | string | Device identifier    |
| `phrase`     | string | Customer's lookup ID |
| `customerId` | string | Customer identifier  |
| `bankId`     | string | Bank identifier      |

## Device Management Use Cases

### Device Linking Process

1. Customer registers device with bank app
2. Bank captures device fingerprint/ID
3. Bank links device to customer's unique phrase
4. Merchants can now identify customer by device

### Security Considerations

* Device IDs are anonymized and encrypted
* No sensitive customer data exposed to merchants
* Phrase associations are securely stored
* Regular security monitoring for suspicious activity

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "statusCode": 400,
  "success": false,
  "message": "Invalid device ID format"
}
```

### 404 Not Found

```json theme={null}
{
  "statusCode": 404,
  "success": false,
  "message": "Device not found in system"
}
```

### 409 Conflict

```json theme={null}
{
  "statusCode": 409,
  "success": false,
  "message": "Device already linked to another customer"
}
```