---
description: >-
  Look up recipient payout details before initiating a push transaction by
  querying country-specific instant payment alias directories such as PIX,
  UPI, PayNow, PromptPay, and InstaPay.
---

# Alias Directory

> **Access to the Alias Directory API is not widely available.** This endpoint is subject to quota limits and restricted to specific use cases. Contact your Inyo account manager to learn more.

The Alias Directory API lets you resolve a recipient's alias (such as a national ID, phone number, email, or tax ID) into their linked bank account and holder details **before** initiating a push transaction. This is useful for validating payout destinations and displaying confirmation details to the sender.

## What is an alias directory?

Instant payment rails — such as PIX in Brazil, UPI in India, or PayNow in Singapore — maintain centralized directories that map aliases (keys) to bank accounts. When a user registers for one of these systems, they link an alias (e.g., their CPF number, phone number, or email) to a specific bank account. The Alias Directory API queries these rail-specific registries and returns the matched account and holder information.

Common use cases:

- **Pre-flight validation** — Verify that an alias resolves to a valid account before submitting a push transaction
- **Recipient confirmation** — Display the holder name and masked account number so the sender can confirm the payout destination
- **Error prevention** — Catch typos or invalid keys early, avoiding failed transactions and refund cycles

## Endpoint

```
POST https://{FQDN}/v1/alias/directory
```

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |
| `Content-Type` | `application/json` |

## Request

| Field | Type | Required | Description |
|---|---|---|---|
| `countryCode` | string | ✅ | ISO Alpha-3 country code (e.g., `"BRA"`, `"SGP"`, `"IND"`) |
| `key` | string | ✅ | The alias value to look up (e.g., CPF number, phone, email, VPA) |
| `keyType` | string | ✅ | The type of alias — valid values depend on the instant payment rail (see table below) |

## Supported Rails and Key Types

Each country's instant payment system supports different alias types. Use the table below to determine which `keyType` values are valid for each rail.

| Country | `countryCode` | System | Supported `keyType` values |
|---|---|---|---|
| Brazil | `BRA` | PIX | `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP` |
| India | `IND` | UPI | `VPA`, `MOBILE`, `AADHAAR` |
| Singapore | `SGP` | PayNow | `NRIC_FIN`, `UEN`, `MOBILE`, `VPA` |
| Thailand | `THA` | PromptPay | `CITIZEN_ID`, `PHONE`, `TAX_ID` |
| Philippines | `PHL` | InstaPay | `MOBILE`, `EMAIL`, `ACCOUNT_NUMBER` |

## Response — Alias Found (HTTP 200)

When the alias is found in the directory, the API returns the linked account and holder details.

| Field | Type | Description |
|---|---|---|
| `found` | boolean | `true` — alias was resolved |
| `countryCode` | string | ISO Alpha-3 country code |
| `system` | string | Name of the instant payment rail (e.g., `"PIX"`, `"PayNow"`, `"UPI"`) |
| `keyType` | string | The key type that was queried |
| `key` | string | The alias value that was queried |
| `account` | object | Linked bank account details |
| `account.bankCode` | string | Bank institution code |
| `account.bankName` | string | Bank name |
| `account.accountType` | string | Account type (e.g., `"CHECKING"`, `"SAVINGS"`) |
| `account.accountNumber` | string | Masked account number |
| `account.branchCode` | string | Branch code (when applicable, e.g., Brazil) |
| `holder` | object | Account holder details |
| `holder.name` | string | Holder's full name |
| `holder.documentType` | string | Document type used for registration (e.g., `"CPF"`, `"NRIC"`) |
| `holder.document` | string | Masked document number |
| `holder.type` | string | `"INDIVIDUAL"` or `"BUSINESS"` |

## Response — Alias Not Found (HTTP 400)

When the alias cannot be resolved in the directory, the API returns a 400 status.

| Field | Type | Description |
|---|---|---|
| `found` | boolean | `false` — alias was not resolved |
| `countryCode` | string | ISO Alpha-3 country code |
| `system` | string | Name of the instant payment rail |
| `keyType` | string | The key type that was queried |
| `key` | string | The alias value that was queried |
| `message` | string | Human-readable error description |

## Examples

### PIX — Brazil (CPF lookup)

**Request:**

```bash
curl -X POST https://{FQDN}/v1/alias/directory \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "countryCode": "BRA",
    "key": "11122233344",
    "keyType": "CPF"
  }'
```

**Response (200):**

```json
{
  "found": true,
  "countryCode": "BRA",
  "system": "PIX",
  "keyType": "CPF",
  "key": "11122233344",
  "account": {
    "bankCode": "341",
    "bankName": "Itaú Unibanco",
    "accountType": "CHECKING",
    "accountNumber": "****-5",
    "branchCode": "1234"
  },
  "holder": {
    "name": "João da Silva",
    "documentType": "CPF",
    "document": "***.222.***-**",
    "type": "INDIVIDUAL"
  }
}
```

### PayNow — Singapore (NRIC/FIN lookup)

**Request:**

```bash
curl -X POST https://{FQDN}/v1/alias/directory \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "countryCode": "SGP",
    "key": "S1234567A",
    "keyType": "NRIC_FIN"
  }'
```

**Response (200):**

```json
{
  "found": true,
  "countryCode": "SGP",
  "system": "PayNow",
  "keyType": "NRIC_FIN",
  "key": "S1234567A",
  "account": {
    "bankCode": "7339",
    "bankName": "OCBC Bank",
    "accountType": "SAVINGS",
    "accountNumber": "XXXX-XXXX-5678"
  },
  "holder": {
    "name": "Lee Siew Ling",
    "documentType": "NRIC",
    "document": "S****567A",
    "type": "INDIVIDUAL"
  }
}
```

### Alias Not Found — InstaPay (Philippines)

**Request:**

```bash
curl -X POST https://{FQDN}/v1/alias/directory \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "countryCode": "PHL",
    "key": "jua2n@gcash",
    "keyType": "EMAIL"
  }'
```

**Response (400):**

```json
{
  "found": false,
  "countryCode": "PHL",
  "system": "InstaPay",
  "keyType": "EMAIL",
  "key": "jua2n@gcash",
  "message": "Alias not found in InstaPay directory"
}
```

### Alias Not Found — PromptPay (Thailand)

**Request:**

```bash
curl -X POST https://{FQDN}/v1/alias/directory \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "countryCode": "THA",
    "key": "+668123456S78",
    "keyType": "PHONE"
  }'
```

**Response (400):**

```json
{
  "found": false,
  "countryCode": "THA",
  "system": "PromptPay",
  "keyType": "PHONE",
  "key": "+668123456S78",
  "message": "Alias not found in PromptPay directory"
}
```

### Alias Not Found — PayNow (Singapore)

**Request:**

```bash
curl -X POST https://{FQDN}/v1/alias/directory \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "countryCode": "SGP",
    "key": "S1234S567A",
    "keyType": "NRIC_FIN"
  }'
```

**Response (400):**

```json
{
  "found": false,
  "countryCode": "SGP",
  "system": "PayNow",
  "keyType": "NRIC_FIN",
  "key": "S1234S567A",
  "message": "Alias not found in PayNow directory"
}
```