List

List

This endpoint returns a paginated list of recipients created within a specified date range. Use this to audit your recipient records, check active/inactive status, or build a directory view within your application.

In the request, you must provide the date range and the number of recipients you want to be listed on each page.

GET recipient/list

Run in Postman

Request Params

Field	Type	Description
BusinessId	Guid	Optional TaxBandits-generated unique identifier for the business to filter by.
PayeeRef	String	Optional Your unique identifier for the business to filter by.
IsActive	Boolean	Optional When TRUE, only active recipients are returned. When FALSE, only deactivated recipients are returned. Omit to return all.
Last4Digit	String	Optional Filter by the last 4 digits of the recipient TIN.
FromDate	String	Optional Return recipients created on or after this date. Format: MM-DD-YYYY
ToDate	String	Optional Return recipients created on or before this date. Format: MM-DD-YYYY
Page	Int	Optional Page number to retrieve. Starts at 1.
PageSize	Int	Optional Number of records per page. Maximum: 100.

Response Body

Field	Type	Description
Business	Object	Details of the business the recipients are associated with.
BusinessId	GUID	TaxBandits-generated unique identifier for the business.
PayerRef	String	Your unique identifier for the business.
TINType	String	TIN type of the business.
Last4DigitTIN	String	Last 4 digits of the business TIN.
Recipient	Object []	Array of matching recipient records.
RecipientId	GUID	TaxBandits-generated unique identifier for the recipient.
PayeeRef	String	Your unique identifier for the recipient.
IsActive	Boolean	Identifies whether this recipient is currently active.
TINDetails	Object	TIN details of the recipient.
TINType	String	TIN type of the recipient.
TIN	String	Taxpayer identification number of the recipient.
Last4Digit	String	Last 4 digits of the recipient TIN.
TINMatchStatus	String	TIN matching status of the recipient.
IndividualNm	Object	If the TINType is SSN, ITIN, or ATIN.
FirstNm	String	First name of the individual.
MiddleNm	String	Middle name of the individual.
LastNm	String	Last name of the individual.
Suffix	String	Suffix of the individual's name.
BusinessNm	String	Name of the recipient business.
DBADetails	Object []	DBA details of the recipient.
Email	String	Email address of the recipient.
Address	Object	Address of the recipient.
Address1	String	Street address or PO Box of the recipient.
Address2	String	Suite or apartment of the recipient.
City	String	City of the recipient.
ProvinceOrState	String	Province or state name of the recipient.
ZipCd	String	ZIP code of the recipient.
Country	String	Country code of the recipient.
CreatedTime	String	Date and time the recipient was created.
LastUpdatedTime	String	Date and time the recipient was last updated.
TotalRecords	number	Total number of records returned in the response.
TotalPages	number	Number of pages with records.
Page	number	Requested page number.
PageSize	number	Requested page size.
Errors	Object []	Top-level request errors if the entire request cannot be processed.
Id	String	Validation error code.
Name	String	Name of the validation rule that failed.
Message	String	Description of what went wrong.

Payload

Request Params

Sample	Description	Action
Sample 1	List recipients using active status, TIN, date range, and pagination filters.

Sample 1

recipient/list?businessId=dd07107c-29ce-485e-aefe-5f46d8923ae3&payeeref=DA4011

Response Json

Sample	Description	Action
200	Success Response - This is a sample response for successful API requests.
400	Bad Request Response - You'll get the below response when your API requests contain any validation errors.
401	Unauthorized Response - You'll get the below response when your API requests don't contain valid authentication credentials.

Response: 200

{
  "Recipient": [
    {
      "RecipientId": "d67539c3-0603-4fb7-9a29-3ae15339269a",
      "PayeeRef": "PAYEE001",
      "IsActive": true,
      "TINDetails": {
        "TINType": "SSN",
        "Last4Digit": "6000",
        "TINMatchStatus": null
      },
      "IndividualNm": {
        "FirstNm": "John",
        "MiddleNm": "Michael",
        "LastNm": "Smith",
        "Suffix": null
      },
      "BusinessNm": null,
      "DBADetails": {
        "DBANm": "Smith Consulting",
        "DBARef": "SC001",
        "DBAId": "a32b351f-00b6-4639-a1ec-835b10ee8dae"
      },
      "Email": "john.smith@example.com",
      "Address": {
        "Address1": "123 Main Street",
        "Address2": "Apt 4B",
        "City": "Austin",
        "ProvinceOrState": "TX",
        "ZipCd": "78701",
        "Country": "US"
      },
      "CreatedTime": "2026-07-09 02:28:06 -04:00",
      "LastUpdatedTime": "2026-07-09 02:28:06 -04:00"
    }
  ]
}

Go Lang

  package main

  import (
  "fmt"
  "net/http"
  "io"
  )

  func main() {

  url := "<APIURL>/v2.0.0/recipient/list?BusinessId=77cabe33-ce9f-4d65-83ea-1d3d67d4a11a&payeeref=DA4011"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
      fmt.Println(err)
      return
  }
  req.Header.Add("Authorization", "<ACCESS_TOKEN>")

  res, err := client.Do(req)
  if err != nil {
      fmt.Println(err)
      return
  }
  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
      fmt.Println(err)
      return
  }
  fmt.Println(string(body))
  }  

Node.js

  const axios = require('axios');

  let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: '<APIURL>/v2.0.0/recipient/list?BusinessId=77cabe33-ce9f-4d65-83ea-1d3d67d4a11a&payeeref=DA4011',
  headers: { 
      'Authorization': '<ACCESS_TOKEN>'
  }
  };

  axios.request(config)
  .then((response) => {
  console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
  console.log(error);
  });

Python

  import http.client

  conn = http.client.HTTPSConnection("<APIURL>")
  payload = ''
  headers = {
  'Authorization': '<ACCESS_TOKEN>'
  }
  conn.request("GET", "/v2.0.0/recipient/list?BusinessId=77cabe33-ce9f-4d65-83ea-1d3d67d4a11a&payeeref=DA4011", payload, headers)
  res = conn.getresponse()
  data = res.read()
  print(data.decode("utf-8"))
  

.NET C#

  var client = new HttpClient();
  var request = new HttpRequestMessage(HttpMethod.Get, "<APIURL>/v2.0.0/recipient/list?BusinessId=77cabe33-ce9f-4d65-83ea-1d3d67d4a11a&payeeref=DA4011");
  request.Headers.Add("Authorization", "<ACCESS_TOKEN>");
  var response = await client.SendAsync(request);
  response.EnsureSuccessStatusCode();
  Console.WriteLine(await response.Content.ReadAsStringAsync());
  

Ruby

  require "uri"
  require "net/http"

  url = URI("<APIURL>/v2.0.0/recipient/list?BusinessId=77cabe33-ce9f-4d65-83ea-1d3d67d4a11a&payeeref=DA4011")

  http = Net::HTTP.new(url.host, url.port);
  request = Net::HTTP::Get.new(url)
  request["Authorization"] = "<ACCESS_TOKEN>"

  response = http.request(request)
  puts response.read_body
  

Java

  OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
  MediaType mediaType = MediaType.parse("text/plain");
  RequestBody body = RequestBody.create(mediaType, "");
  Request request = new Request.Builder()
  .url("<APIURL>/v2.0.0/recipient/list?BusinessId=77cabe33-ce9f-4d65-83ea-1d3d67d4a11a&payeeref=DA4011")
  .method("GET", body)
  .addHeader("Authorization", "<ACCESS_TOKEN>")
  .build();
  Response response = client.newCall(request).execute();
  

cURL

  curl --location '<APIURL>/v2.0.0/recipient/list?BusinessId=77cabe33-ce9f-4d65-83ea-1d3d67d4a11a&payeeref=DA4011'   --header 'Authorization: <ACCESS_TOKEN>'