AssignRecipient

AssignRecipient

This endpoint assigns one or more existing recipients to a specific business (payer or employer). Recipients must be assigned to a business before filing any tax forms for them.

Key Points

• Bulk Assignment — Multiple recipients can be assigned in a single request by passing multiple objects in the AssignRecipients array.
• Identifiers — Each recipient can be identified using either its RecipientId or PayeeRef.

POST recipient/assignrecipients 

Run in Postman

Request Body

Field	Type	Description
BusinessId	GUID	TaxBandits-generated unique identifier for the business.
PayerRef	String	Optional Your unique identifier for the business.
AssignRecipients	Object []	An array of recipient objects to assign to the business.
SequenceId	String	Optional A unique reference ID for the submission that can be used to identify a particular record. The Sequence ID will be returned in the Response for your reference. Max 50 characters
RecipientId	GUID	Unique identifier of the recipient. Required if PayeeRef is not provided.
PayeeRef	String	Optional Your unique identifier for the recipient. Required if RecipientId is not provided.

Response Body

Field	Type	Description
BusinessId	GUID	TaxBandits-generated unique identifier for the business.
PayerRef	String	Your unique identifier for the business.
SuccessRecipients	Object []	Recipient records that were assigned successfully.
SequenceId	String	A unique reference ID for the submission that can be used to identify a particular record.
RecipientId	GUID	Unique identifier of the recipient.
PayeeRef	String	Your unique identifier for the recipient.
Status	String	Status of the operation.
StatusTs	String	Date and time the operation was completed.
ErrorRecipients	Object []	Records that failed, with details on why.
SequenceId	String	A unique reference ID for the submission that can be used to identify a particular record. The Sequence ID will be returned in the Response for your reference.
RecipientId	GUID	Identifier of the failed recipient.
PayeeRef	String	Your unique identifier for the recipient.
Errors	Object []	Validation error details.
Id	String	Validation error code.
Name	String	Name of the validation rule that failed.
Message	String	Description of the error.
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 the error.

Payload

Request JSON

Sample	Description	Action
Sample 1	Assigns one or more existing recipients to a specific business (payer or employer).

Sample 1

{
  "BusinessId": "09c218b3-15e4-4b3e-a0fe-8b2376098b99",
  "PayerRef": "PAYER105",
  "AssignRecipients": [
    {
      "SequenceId": "01",
      "RecipientId": "d67539c3-0603-4fb7-9a29-3ae15339269a",
      "PayeeRef": "PAYEE001"
    }
  ]
}

Response JSON

Response	Description	Action
200	Success Response - You'll get the below response when the request is processed successfully.
207	Multi-status Response - You'll get the below response when multiple statuses are included.
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

{
  "BusinessId": "09c218b3-15e4-4b3e-a0fe-8b2376098b99",
  "PayerRef": "PAYER105",
  "SuccessRecipients": [
    {
      "SequenceId": "01",
      "RecipientId": "d67539c3-0603-4fb7-9a29-3ae15339269a",
      "PayeeRef": "PAYEE001",
      "Status": "ASSIGNED",
      "StatusTs": "2026-07-09 06:41:18 -04:00"
    }
  ],
  "ErrorRecipients": null,
  "Errors": null
}

Go Lang

  package main

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

  func main() {
      url := "<APIURL>/v2.0.0/recipient/assignrecipients"
      method := "POST"

      payload := strings.NewReader(`{
          "BusinessId": "09c218b3-15e4-4b3e-a0fe-8b2376098b99",
          "PayerRef": "PAYER105",
          "AssignRecipients": [
              {
                  "SequenceId": "01",
                  "RecipientId": "d67539c3-0603-4fb7-9a29-3ae15339269a",
                  "PayeeRef": "PAYEE001"
              }
          ]
      }`)

      client := &http.Client{}

      req, err := http.NewRequest(method, url, payload)
      if err != nil {
          fmt.Println(err)
          return
      }

      req.Header.Add("Authorization", "<ACCESS_TOKEN>")
      req.Header.Add("Content-Type", "application/json")

      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 data = JSON.stringify({
  "BusinessId": "09c218b3-15e4-4b3e-a0fe-8b2376098b99",
  "PayerRef": "PAYER105",
  "AssignRecipients": [
      {
      "SequenceId": "01",
      "RecipientId": "d67539c3-0603-4fb7-9a29-3ae15339269a",
      "PayeeRef": "PAYEE001"
      }
  ]
  });

  let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: '<APIURL>/v2.0.0/recipient/assignrecipients',
  headers: { 
      'Authorization': '<ACCESS_TOKEN>', 
      'Content-Type': 'application/json'
  },
  data : data
  };

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

Python

  import http.client
  import json

  conn = http.client.HTTPSConnection("<APIURL>")
  payload = json.dumps({
  "BusinessId": "09c218b3-15e4-4b3e-a0fe-8b2376098b99",
  "PayerRef": "PAYER105",
  "AssignRecipients": [
      {
      "SequenceId": "01",
      "RecipientId": "d67539c3-0603-4fb7-9a29-3ae15339269a",
      "PayeeRef": "PAYEE001"
      }
  ]
  })
  headers = {
  'Authorization': '<ACCESS_TOKEN>',
  'Content-Type': 'application/json'
  }
  conn.request("POST", "/v2.0.0/recipient/assignrecipients", payload, headers)
  res = conn.getresponse()
  data = res.read()
  print(data.decode("utf-8"))

.NET C#

  var client = new HttpClient();
  var request = new HttpRequestMessage(HttpMethod.Post, "<APIURL>/v2.0.0/recipient/assignrecipients");
  request.Headers.Add("Authorization", "<ACCESS_TOKEN>");
  var content = new StringContent("{
    "BusinessId": "09c218b3-15e4-4b3e-a0fe-8b2376098b99",
    "PayerRef": "PAYER105",
    "AssignRecipients": [
        {
            "SequenceId": "01",
            "RecipientId": "d67539c3-0603-4fb7-9a29-3ae15339269a",
            "PayeeRef": "PAYEE001"
        }
    ]
}", null, "application/json");
  request.Content = content;
  var response = await client.SendAsync(request);
  response.EnsureSuccessStatusCode();
  Console.WriteLine(await response.Content.ReadAsStringAsync());

Ruby

  require "uri"
  require "json"
  require "net/http"

  url = URI("<APIURL>/v2.0.0/recipient/assignrecipients")

  http = Net::HTTP.new(url.host, url.port);
  request = Net::HTTP::Post.new(url)
  request["Authorization"] = "<ACCESS_TOKEN>"
  request["Content-Type"] = "application/json"
  request.body = JSON.dump({
  "BusinessId": "09c218b3-15e4-4b3e-a0fe-8b2376098b99",
  "PayerRef": "PAYER105",
  "AssignRecipients": [
      {
      "SequenceId": "01",
      "RecipientId": "d67539c3-0603-4fb7-9a29-3ae15339269a",
      "PayeeRef": "PAYEE001"
      }
  ]
  })

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

Java

  OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
  MediaType mediaType = MediaType.parse("application/json");
  RequestBody body = RequestBody.create(mediaType, "{
    "BusinessId": "09c218b3-15e4-4b3e-a0fe-8b2376098b99",
    "PayerRef": "PAYER105",
    "AssignRecipients": [
        {
            "SequenceId": "01",
            "RecipientId": "d67539c3-0603-4fb7-9a29-3ae15339269a",
            "PayeeRef": "PAYEE001"
        }
    ]
}");
  Request request = new Request.Builder()
  .url("<APIURL>/v2.0.0/recipient/assignrecipients")
  .method("POST", body)
  .addHeader("Authorization", "<ACCESS_TOKEN>")
  .addHeader("Content-Type", "application/json")
  .build();
  Response response = client.newCall(request).execute();

cURL

  curl --location '<APIURL>/v2.0.0/recipient/assignrecipients'   --header 'Authorization: <ACCESS_TOKEN>'   --header 'Content-Type: application/json'   --data '{
      "BusinessId": "09c218b3-15e4-4b3e-a0fe-8b2376098b99",
      "PayerRef": "PAYER105",
      "AssignRecipients": [
          {
              "SequenceId": "01",
              "RecipientId": "d67539c3-0603-4fb7-9a29-3ae15339269a",
              "PayeeRef": "PAYEE001"
          }
      ]
  }'