---
updatedAt: 2026-02-06T00:24:43.000Z
agentTools:
  projectIndex: https://developer.greendot.com/embedded-finance/llms.txt
---

# Search Payee by Name

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.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "BaaS APIs",
    "description": "Green Dot BaaS Partner API",
    "version": "v1",
    "x-generated-timestamp-utc": "2026-02-05T01:14:54.4774970Z"
  },
  "paths": {
    "/programs/{programCode}/accounts/{accountIdentifier}/billpayPayees/search": {
      "post": {
        "tags": [
          "BillPay"
        ],
        "summary": "Search Payee by Name",
        "description": "This endpoint allows you to search for a payee in the payee directory by name.\n            <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.\n            <br/>• Once the search is completed, a list of payee names that match the searched payee name will be returned.\n            <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.\n            <br/>• The payee name search is a full text search, so the payee’s full name must be provided.\n            <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.\n            <br/>• Therefore, a two second wait is required between each search.\n            <br/>• Partners should submit payee search requests after the customer stops typing or after the response to the initial payee search request is received.",
        "operationId": "BillPay_POST_SearchPayee",
        "parameters": [
          {
            "name": "X-GD-RequestId",
            "in": "header",
            "description": "The unique request identifier for idempotency and tracking. Must be provided in the X-GD-RequestId header.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "programCode",
            "in": "path",
            "description": "The program code associated with the partner implementation.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "accountIdentifier",
            "in": "path",
            "description": "The unique identifier of the account for which to search payees. Must be a valid GUID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "The Gd.Bos.DataTransfer.Request.SearchPayeeRequest object containing the payee name to search for.",
          "content": {
            "application/json-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/SearchPayeeRequest"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchPayeeRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchPayeeRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/SearchPayeeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchPayeeResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchPayeeResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchPayeeResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchPayeeResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchPayeeResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchPayeeResponse"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchPayeeResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchPayeeResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Payee": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the payee (merchant or person).",
            "nullable": true
          },
          "merchantId": {
            "type": "string",
            "description": "The unique merchant identifier for merchant payees.\r\nNull or empty for person payees.",
            "nullable": true
          },
          "merchantZipRequired": {
            "type": "boolean",
            "description": "Indicates whether the merchant requires a ZIP code for bill payments."
          },
          "address1": {
            "type": "string",
            "description": "The first line of the payee's address.",
            "nullable": true
          },
          "address2": {
            "type": "string",
            "description": "The second line of the payee's address (optional).",
            "nullable": true
          },
          "city": {
            "type": "string",
            "description": "The city of the payee's address.",
            "nullable": true
          },
          "state": {
            "type": "string",
            "description": "The state or province of the payee's address.",
            "nullable": true
          },
          "country": {
            "type": "string",
            "description": "The country of the payee's address (e.g., \"US\").",
            "nullable": true
          },
          "zip": {
            "type": "string",
            "description": "The ZIP or postal code of the payee's address.",
            "nullable": true
          },
          "phoneNumber": {
            "type": "string",
            "description": "The payee's phone number.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Payee – Represents a payee entity returned in payee search results.\r\nUsed to provide details about a merchant or person payee, including name, merchant information, address, and contact details."
      },
      "ResponseDetail": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "The primary status or error code for the response (e.g., 200 for success, 400 for validation error).",
            "format": "int32"
          },
          "subCode": {
            "type": "integer",
            "description": "An optional subcode providing more granular detail about the response or error.",
            "format": "int32",
            "nullable": true
          },
          "description": {
            "type": "string",
            "description": "A human-readable description of the response, error, or status.",
            "nullable": true
          },
          "url": {
            "type": "string",
            "description": "A URL linking to documentation or a web page with more information about the response code.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Represents a detailed status or error message for an API response.\r\nContains a code, optional subcode, human-readable description, and a URL for more information.\r\nUsed to provide granular feedback about the outcome of an operation, including success, warnings, or errors."
      },
      "SearchPayeeRequest": {
        "type": "object",
        "properties": {
          "accountIdentifier": {
            "type": "string",
            "description": "The unique identifier of the account for which to search payees.\r\nMust be a valid GUID.",
            "nullable": true
          },
          "name": {
            "type": "string",
            "description": "The name or partial name of the payee to search for.\r\nMust be between 3 and 32 characters.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Search Payee Request – Represents the data required to search for a payee in the payee directory by name.\r\nUsed to request a list of payees matching the provided name for a specific account."
      },
      "SearchPayeeResponse": {
        "type": "object",
        "properties": {
          "payees": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Payee"
            },
            "description": "The list of payees matching the search criteria.\r\nEach item contains payee details such as name, merchant ID, address, phone number, and merchant ZIP requirements.",
            "nullable": true
          },
          "responseDetails": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResponseDetail"
            },
            "description": "Required: A list of response details providing status codes, descriptions, and additional information about the result of the operation.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Search Payee Response – Contains the results of a payee directory search.\r\nUsed to provide a list of payees matching the search criteria, including merchant and person payees with relevant details."
      }
    },
    "securitySchemes": {
      "Bearer": {
        "type": "apiKey",
        "description": "bearer token",
        "name": "Authorization",
        "in": "header"
      }
    }
  },
  "security": [
    {
      "Bearer": []
    }
  ],
  "x-readme": {
    "explorer-enabled": false,
    "proxy-enabled": false,
    "samples-languages": [
      "csharp",
      "java",
      "python",
      "node",
      "objectivec"
    ]
  }
}
```