---
description: >-
  Retrieve country-specific schemas for accounts, payouts, and persons using
  GET /schema endpoints. Use these to build dynamic forms and validate data
  before submitting to the API.
---

# Schemas

The Schema endpoints return country-specific field definitions for accounts, payouts, and persons. Query these before creating resources to determine which fields are required, optional, and what validation rules apply.

Use schemas to:

- **Build dynamic forms** that adapt to country-specific requirements
- **Validate input** before submitting to creation endpoints
- **Display the correct fields** for each payout corridor

---

## Account Schema

Returns the required and optional fields for creating a bank account in a given country.

### Endpoint

```
GET https://{FQDN}/schema/account
```

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |

### Query Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `countryCode` | string | ✅ | Country code (e.g., `"BR"`, `"US"`, `"SG"`) |

### Example Request

```bash
curl -X GET 'https://{FQDN}/schema/account?countryCode=BR' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'
```

### Response (200)

```json
{
  "countryCode": "BR",
  "fields": [
    {
      "name": "accountNumber",
      "type": "string",
      "required": true,
      "label": "Account Number",
      "maxLength": 20
    },
    {
      "name": "branchCode",
      "type": "string",
      "required": true,
      "label": "Branch Code",
      "maxLength": 6
    },
    {
      "name": "accountType",
      "type": "enum",
      "required": true,
      "label": "Account Type",
      "values": ["CHECKING", "SAVINGS"]
    },
    {
      "name": "bankCode",
      "type": "string",
      "required": true,
      "label": "Bank Code",
      "maxLength": 5
    }
  ]
}
```

---

## Payout Schema

Returns the required and optional fields for creating a payout in a given country.

### Endpoint

```
GET https://{FQDN}/schema/payout
```

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |

### Query Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `countryCode` | string | ✅ | Country code (e.g., `"BR"`, `"US"`, `"PH"`) |

### Example Request

```bash
curl -X GET 'https://{FQDN}/schema/payout?countryCode=PH' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'
```

### Response (200)

```json
{
  "countryCode": "PH",
  "fields": [
    {
      "name": "destinationType",
      "type": "enum",
      "required": true,
      "label": "Destination Type",
      "values": ["BANK_ACCOUNT", "WALLET", "INSTAPAY"]
    },
    {
      "name": "bankCode",
      "type": "string",
      "required": false,
      "label": "Bank Code",
      "dependsOn": "destinationType=BANK_ACCOUNT"
    },
    {
      "name": "accountNumber",
      "type": "string",
      "required": false,
      "label": "Account Number",
      "dependsOn": "destinationType=BANK_ACCOUNT"
    },
    {
      "name": "walletId",
      "type": "string",
      "required": false,
      "label": "Wallet ID",
      "dependsOn": "destinationType=WALLET"
    }
  ]
}
```

---

## Person Schema

Returns the required and optional fields for creating a payment person (KYC) in a given country.

### Endpoint

```
GET https://{FQDN}/schema/person
```

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |

### Query Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `countryCode` | string | ✅ | Country code (e.g., `"BR"`, `"US"`, `"IN"`) |

### Example Request

```bash
curl -X GET 'https://{FQDN}/schema/person?countryCode=IN' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'
```

### Response (200)

```json
{
  "countryCode": "IN",
  "fields": [
    {
      "name": "firstName",
      "type": "string",
      "required": true,
      "label": "First Name",
      "maxLength": 50
    },
    {
      "name": "lastName",
      "type": "string",
      "required": true,
      "label": "Last Name",
      "maxLength": 50
    },
    {
      "name": "identificationType",
      "type": "enum",
      "required": true,
      "label": "ID Type",
      "values": ["PAN", "AADHAAR", "PASSPORT"]
    },
    {
      "name": "identification",
      "type": "string",
      "required": true,
      "label": "ID Number",
      "maxLength": 20
    },
    {
      "name": "phoneNumber",
      "type": "string",
      "required": true,
      "label": "Phone Number"
    }
  ]
}
```

### Response Fields

| Field | Type | Description |
|---|---|---|
| `countryCode` | string | The queried country code |
| `fields` | array | Array of field definitions |
| `fields[].name` | string | Field name to use in API requests |
| `fields[].type` | string | Data type: `"string"`, `"enum"`, `"number"`, `"boolean"` |
| `fields[].required` | boolean | Whether the field is mandatory |
| `fields[].label` | string | Human-readable label for form display |
| `fields[].maxLength` | integer | Maximum character length (when applicable) |
| `fields[].values` | array | Allowed values (for `enum` type fields) |
| `fields[].dependsOn` | string | Conditional requirement (e.g., `"destinationType=BANK_ACCOUNT"`) |

## What's Next

- [Payment Person](../payment-person.md) — Create and validate persons using the schema fields
- [Banks](banks.md) — Look up bank codes to populate bank selection fields
- [Check Account](../check-account.md) — Validate account details before transacting