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:

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):

{
  "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:

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):

{
  "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:

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):

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

Alias Not Found — PromptPay (Thailand)

Request:

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):

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

Alias Not Found — PayNow (Singapore)

Request:

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):

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