Skip to main content
Hidden
Note
This feature is currently in limited-availability alpha and subject to change. To learn more about the alpha program for this feature, contact your Marqeta representative.
Biller endpoints.

​
Search Billers

Action: POST
Endpoint: /billers/search You can perform a basic search using just the name field. You will receive a response containing a list of billers, where each biller may contain additional fields that should be passed when searching in order to get more detailed biller information for the user’s account to link a payee. If an empty body ( {} ) is provided with no biller name, a list of commonly used billers will be returned in the response. Detailed Search Many billers have multiple addresses. The user may need to pass in the account_number and zip_code fields to find the correct biller_token and address_token of the biller for the user’s account. In most cases when including these detail fields, a single biller will be returned with one more more addresses. An address_token is often needed to link a payee to the user’s account. The fastest way to get the correct biller_token and address_token for a biller is to provide the user’s account_number and the biller’s zip_code when searching.
Note
When passing in zip_code, it is recommended that you pass in the full zip_code of the biller for the user’s account, including the +4 extension, such as "94610-2468". This will allow the user to match directly to a biller’s address_token without needing further action from the user to find the correct address for their account with the biller.

​
Request body

FieldsDescription
name

string

Optional		Name of the biller to search for.

Allowable Values:

2 char min
page_size

integer

Optional		Number of results to show per page.

Allowable Values:

1 min
page_number

integer

Optional		Current page number of the returned results.

Allowable Values:

1 min
account_number

string

Optional		User’s billing account number.

Allowable Values:
zip_code

string

Optional		United States ZIP code of the biller.

Allowable Values:
biller_token

string

Optional		Unique identifier of the biller resource.

Allowable Values:

​
Sample request body

JSON
{
  "name": "Marqeta",
  "page_size": 10,
  "page_number": 1
}
JSON
{
  "name": "Marqeta",
  "page_size": 10,
  "page_number": 1,
  "account_number": "12345678",
  "zipCode": "94162",
  "biller_token": "a35Bcdi598sb="
}
JSON
{}

​
Response body

FieldsDescription
count

integer

Conditionally returned		Number of biller resources retrieved.

Allowable Values:

0 min
page_size

integer

Conditionally returned		Number of results to display per page.

Allowable Values:

1 min
page_number

integer

Conditionally returned		Current page of the search results.

Allowable Values:
has_more

boolean

Conditionally returned		A value of true indicates that more unreturned resources exist.

Allowable Values:
data

array of undefineds

Conditionally returned		Array of one or more biller objects.

Allowable Values:
data[].biller_token

string

Conditionally returned		Unique identifier of the biller resource.

Allowable Values:

2–36 chars
data[].name

string

Conditionally returned		Name of the biller.

Allowable Values:

2–124 chars
data[].logo

string

Conditionally returned		Logo of the biller.

Allowable Values:

255 char max
data[].logo_type

string

Conditionally returned		Specifies the type of string for the value returned in the logo field.

Allowable Values:

URL, BINARY
data[].addresses

array of objects

Conditionally returned		A list of addresses associated with the biller.

Allowable Values:
data[].addresses[].address1

string

Conditionally returned		Street address of the biller.

Allowable Values:

36 char max
data[].addresses[].address2

string

Conditionally returned		Additional address information.

Allowable Values:

36 char max
data[].addresses[].city

string

Conditionally returned		City of the biller.

Allowable Values:

36 char max
data[].addresses[].country

string

Conditionally returned		Country of the biller.

Allowable Values:

40 char max
data[].addresses[].zip_code

string

Conditionally returned		United States ZIP code of the address.

Allowable Values:

20 char max
data[].addresses[].state

string

Conditionally returned		State of the biller.

Allowable Values:

36 char max
data[].addresses[].address_token

string

Conditionally returned		Unique identifier of the address resource.

Allowable Values:

36 char max
data[].detail_search_fields

array of strings

Conditionally returned		Additional fields to pass in to the search request when getting details for a biller.

Allowable Values:

account_number, zip_code

​
Sample response body

JSON
{
  "data": [
    {
      "biller_token": "a35Bcdi598sb=",
      "name": "Marqeta",
      "logo": "https://images.ctfassets.net/wqi8u1luxsv0/logo.svg/8559a40e8a503b55eeec4852e60efd49/logo.svg",
      "logo_type": "URL",
      "addresses": [
        {
          "address1": "180 Grand Ave",
          "city": "Oakland",
          "country": "USA",
          "zip_code": "94612",
          "state": "CA",
          "address_token": "a35Bcdi598sb="
        }
      ],
      "detail_search_fields": [
        "account_number",
        "zip_code"
      ]
    }
  ],
  "count": 1,
  "page_size": 10,
  "page_number": 1,
  "has_more": false
}

​
Get Biller

Action: GET
Endpoint: /billers/{biller_token} Get a biller using the biller’s token.

​
URL path parameters

FieldsDescription
biller_token

string

Required		Allowable Values:

Existing biller resource token

​
Response body

FieldsDescription
biller_token

string

Conditionally returned		Unique identifier of the biller resource.

Allowable Values:

2–36 chars
name

string

Conditionally returned		Name of the biller.

Allowable Values:

2–124 chars
logo

string

Conditionally returned		Logo of the biller.

Allowable Values:

255 char max
logo_type

string

Conditionally returned		Specifies the type of string for the value returned in the logo field.

Allowable Values:

URL, BINARY

​
Sample response body

JSON
{
  "biller_token": "a35Bcdi598sb=",
  "name": "Marqeta",
  "logo": "https://images.ctfassets.net/wqi8u1luxsv0/logo.svg/8559a40e8a503b55eeec4852e60efd49/logo.svg",
  "logo_type": "URL"
}

Related topics

Introduction to Bill PayBill Pay UsersBill PaymentsPayeesEvent Types