> ## 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 Management Schemas

API endpoints for managing bank customers within the Peere Network.

## Endpoints

| Method | Endpoint             | Description                   |
| ------ | -------------------- | ----------------------------- |
| GET    | `/v1/bank/customer`  | Get specific customer details |
| GET    | `/v1/bank/customers` | List customers with filters   |
| POST   | `/v1/bank/customers` | Create customers in batch     |
| PATCH  | `/v1/bank/customer`  | Update customer information   |

## GET /v1/bank/customer

Retrieve details for a specific customer in your bank.

### Query Parameters

| Parameter | Type   | Required | Description                                        |
| --------- | ------ | -------- | -------------------------------------------------- |
| `id`      | string | No       | Customer ID (one of id, email, or phrase required) |
| `email`   | string | No       | Customer email address                             |
| `phrase`  | string | No       | Customer phrase                                    |

### Response Schema

```json theme={null}
{
  "statusCode": 200,
  "success": true,
  "message": "Customer retrieved successfully",
  "data": {
    "id": "string",
    "accountName": "string",
    "gender": "male | female | other",
    "displayPicture": "string",
    "bankId": "string",
    "phrase": "string",
    "country": "string"
  }
}
```

## GET /v1/bank/customers

List customers in your bank with optional filters and pagination.

### Query Parameters

| Parameter | Type      | Required | Description                 |
| --------- | --------- | -------- | --------------------------- |
| `ids`     | string\[] | No       | Filter by customer IDs      |
| `phrases` | string\[] | No       | Filter by customer phrases  |
| `sortBy`  | string    | No       | Field to sort by            |
| `limit`   | number    | No       | Number of results to return |
| `page`    | number    | No       | Page number for pagination  |

### Response Schema

```json theme={null}
[
  {
    "id": "string",
    "accountName": "string",
    "gender": "male | female | other",
    "displayPicture": "string",
    "bankId": "string",
    "phrase": "string",
    "country": "string"
  }
]
```

## POST /v1/bank/customers

Create multiple customers in batch for your bank.

### Request Body

```json theme={null}
{
  "customers": [
    {
      "clientRef": "string",
      "firstname": "string",
      "lastname": "string",
      "middlename": "string",
      "accountName": "string",
      "email": "string",
      "country": "string",
      "address": "string",
      "gender": "male | female | other",
      "phone": "string",
      "accountNumber": "string",
      "reference": "string"
    }
  ]
}
```

### Request Schema

| Field                       | Type   | Required | Description                       |
| --------------------------- | ------ | -------- | --------------------------------- |
| `customers`                 | array  | Yes      | Array of customer objects         |
| `customers[].clientRef`     | string | Yes      | Client reference identifier       |
| `customers[].firstname`     | string | Yes      | Customer first name               |
| `customers[].lastname`      | string | Yes      | Customer last name                |
| `customers[].middlename`    | string | No       | Customer middle name              |
| `customers[].accountName`   | string | Yes      | Full account name                 |
| `customers[].email`         | string | Yes      | Customer email address            |
| `customers[].country`       | string | Yes      | Country code (ISO 3166-1 alpha-2) |
| `customers[].address`       | string | No       | Customer address                  |
| `customers[].gender`        | string | No       | Customer gender                   |
| `customers[].phone`         | string | No       | Customer phone number             |
| `customers[].accountNumber` | string | Yes      | Bank account number               |
| `customers[].reference`     | string | Yes      | Internal reference                |

### Response Schema

```json theme={null}
{
  "success": true,
  "message": "Batch processed, customers will reflect shortly",
  "statusCode": 201,
  "data": {
    "batchId": "string",
    "status": "PROCESSING",
    "summary": {
      "total": 10,
      "successful": 10,
      "failed": 0,
      "duplicates": 0,
      "invalidData": 0
    },
    "failures": [],
    "failuresInline": true,
    "inlineFailureLimit": 50,
    "data": {
      "createdCount": 10,
      "customerIds": ["string"]
    }
  }
}
```

## PATCH /v1/bank/customer

Update information for an existing customer.

### Request Body

```json theme={null}
{
  "id": "string",
  "update": {
    "firstname": "string",
    "middlename": "string",
    "lastname": "string",
    "accountName": "string",
    "address": "string",
    "phone": "string",
    "displayPicture": "string"
  }
}
```

### Request Schema

| Field                   | Type   | Required | Description                 |
| ----------------------- | ------ | -------- | --------------------------- |
| `id`                    | string | Yes      | Customer identifier         |
| `update`                | object | Yes      | Fields to update            |
| `update.firstname`      | string | No       | Updated first name          |
| `update.middlename`     | string | No       | Updated middle name         |
| `update.lastname`       | string | No       | Updated last name           |
| `update.accountName`    | string | No       | Updated account name        |
| `update.address`        | string | No       | Updated address             |
| `update.phone`          | string | No       | Updated phone number        |
| `update.displayPicture` | string | No       | Updated profile picture URL |

### Response Schema

```json theme={null}
{
  "statusCode": 200,
  "success": true,
  "message": "Customer updated successfully",
  "data": {
    "id": "string",
    "email": "string",
    "phone": "string"
  }
}
```

## Customer Schema (Sensitive Fields Hidden)

When retrieving customer information as a bank, sensitive fields are filtered based on context:

### Standard Fields (Always Visible)

| Field            | Type   | Description            |
| ---------------- | ------ | ---------------------- |
| `id`             | string | Customer identifier    |
| `accountName`    | string | Full customer name     |
| `gender`         | string | Customer gender        |
| `displayPicture` | string | Profile picture URL    |
| `bankId`         | string | Bank identifier        |
| `phrase`         | string | Customer unique phrase |
| `country`        | string | Country code           |

### Extended Fields (Non-Sensitive Context)

| Field       | Type   | Description           |
| ----------- | ------ | --------------------- |
| `state`     | string | State/region          |
| `email`     | string | Email address         |
| `phone`     | string | Phone number          |
| `address`   | string | Physical address      |
| `createdAt` | string | Account creation date |

## Batch Processing Error Codes

| Error Code           | Description                                    |
| -------------------- | ---------------------------------------------- |
| `DUPLICATE_IN_BATCH` | Duplicate customer found within the same batch |
| `INVALID_DATA`       | Missing or invalid required fields             |
| `EXISTING_CUSTOMER`  | Customer already exists in the system          |
| `VALIDATION_ERROR`   | Data format or constraint violations           |

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "statusCode": 400,
  "success": false,
  "message": "Invalid customer data"
}
```

### 404 Not Found

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

### 409 Conflict

```json theme={null}
{
  "statusCode": 409,
  "success": false,
  "message": "Customer with this email already exists"
}
```