---
title: "Search Payee by Name"
method: POST
path: "/programs/{programCode}/accounts/{accountIdentifier}/billpayPayees/search"
tags: ["BillPay"]
---

# Search Payee by Name

`POST /programs/{programCode}/accounts/{accountIdentifier}/billpayPayees/search`

This endpoint allows you to search for a payee in the payee directory by name.
            <br/>• To search the payee directory, you must enter a minimum of 3 characters and a maximum of 32 characters from the payee’s name.
            <br/>• Once the search is completed, a list of payee names that match the searched payee name will be returned.
            <br/>• This endpoint applies to merchant payees only. To add a payee, you must first use the search payee API to locate the payee and their merchantId in the directory.
            <br/>• The payee name search is a full text search, so the payee’s full name must be provided.
            <br/>• This endpoint is not designed for rapid asynchronous calls, because it pulls not only the payee’s names, but also the payee’s complete profile information. Requests may be denied if too many are called in a short period of time.
            <br/>• Therefore, a two second wait is required between each search.
            <br/>• Partners should submit payee search requests after the customer stops typing or after the response to the initial payee search request is received.

## Path parameters

- `programCode` string, required
- `accountIdentifier` string, required

## Headers

- `X-GD-RequestId` string, required

## Request body

- SearchPayeeRequest — Search Payee Request – Represents the data required to search for a payee in the payee directory by name. Used to request a list of payees matching the provided name for a specific account.
  - `accountIdentifier` string, nullable — The unique identifier of the account for which to search payees. Must be a valid GUID.
  - `name` string, nullable — The name or partial name of the payee to search for. Must be between 3 and 32 characters.

## Response `200`

OK

- SearchPayeeResponse — Search Payee Response – Contains the results of a payee directory search. Used to provide a list of payees matching the search criteria, including merchant and person payees with relevant details.
  - `payees` Payee[], nullable — The list of payees matching the search criteria. Each item contains payee details such as name, merchant ID, address, phone number, and merchant ZIP requirements.
    - `name` string, nullable — The name of the payee (merchant or person).
    - `merchantId` string, nullable — The unique merchant identifier for merchant payees. Null or empty for person payees.
    - `merchantZipRequired` boolean — Indicates whether the merchant requires a ZIP code for bill payments.
    - `address1` string, nullable — The first line of the payee's address.
    - `address2` string, nullable — The second line of the payee's address (optional).
    - `city` string, nullable — The city of the payee's address.
    - `state` string, nullable — The state or province of the payee's address.
    - `country` string, nullable — The country of the payee's address (e.g., "US").
    - `zip` string, nullable — The ZIP or postal code of the payee's address.
    - `phoneNumber` string, nullable — The payee's phone number.
  - `responseDetails` ResponseDetail[], nullable — Required: A list of response details providing status codes, descriptions, and additional information about the result of the operation.
    - `code` integer — The primary status or error code for the response (e.g., 200 for success, 400 for validation error).
    - `subCode` integer, nullable — An optional subcode providing more granular detail about the response or error.
    - `description` string, nullable — A human-readable description of the response, error, or status.
    - `url` string, nullable — A URL linking to documentation or a web page with more information about the response code.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.net/greendot/apis/baas-apis.md) · [All operations](https://skmtc.net/greendot/apis/baas-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/greendot/baas-apis/revisions/666553766b78/schema)