Transmit

Transmit

This endpoint can be used to transmit Form W-2 returns to the federal and/or state agencies.

Key Points:

• Call this endpoint only after all validation errors are resolved. If errors exist, review and correct them before transmitting.
• To transmit all returns under a submission, provide only the SubmissionId in the request.
• To transmit specific returns within a submission, provide the SubmissionId along with the RecordIds of the returns as an array.
• Once a form is transmitted, it cannot be edited or deleted.

POST formw2/transmit 

Run in Postman

Request Body

Field	Type	Description
SubmissionId	Guid	A unique identifier of a submission.
RecordIds	Guid[]	Optional A unique identifier generated by TaxBandits when a return is created. Mention the return's RecordId that you want to transmit.
WebhookRef	String	Optional A unique identifier of the Webhooks that TaxBandits generates against each Callback URL when adding it to the console site. If you pass the WebhookRef in the request JSON, we will post the webhook response to the corresponding Callback URL. If you don't pass one, the webhook response will be posted to the default Callback URL.

Response Body

Field	Type	Description
FormW2Records	object[]	Returns the transmitted Form W-2 records along with their federal, state, and distribution statuses.
FormType	string	Denotes the type of W-2 form that was transmitted
BusinessId	Guid	Unique identifier generated for the business associated with the transmitted return.
SubmissionId	Guid	Unique identifier of the submission containing the transmitted record.
RecordId	Guid	Unique identifier generated for the transmitted tax form record.
FederalStatus	object	Returns the federal transmission status of the record.
Code	string	Status code representing the federal transmission status.
Status	string	Current status of the federal transmission. For example, TRANSMITTED, ACCEPTED, REJECTED.
Message	string	Additional information related to the federal transmission status. Returns null if no additional information is available.
StatusTs	string	Date and time when the federal transmission status was last updated.
WebhookRef	string	Unique reference identifier associated with the webhook notification for the federal status update.
StatesStatus	object[]	Returns a collection of state transmission status information.
StateCd	string	Two-letter state abbreviation for which the return was transmitted.
Code	string	Status code representing the state transmission status.
Status	string	Current transmission status for the specified state.
Message	string	Additional information related to the state transmission status. Returns null if no additional information is available.
StatusTs	string	Date and time when the state transmission status was last updated.
WebhookRef	string	Unique reference identifier associated with the webhook notification for the state status update.
Distribution	object	Returns information about the employee distribution service.
DistributionType	string	Specifies the distribution method selected for the employee copy (for example, POSTAL_AND_ONLINE, POSTAL_ONLY, or ONLINE_ONLY).
PostalStatus	object	Returns the postal mailing status information.
PostalType	string	Specifies the postal delivery service selected for mailing the employee copy (for example, USPS_FIRST_CLASS).
Code	string	Status code representing the postal distribution status.
Status	string	Current status of the postal distribution (for example, ORDER_CREATED, IN_TRANSIT, DELIVERED).
Message	string	Additional information related to the postal distribution status. Returns null if no additional information is available.
StatusTs	string	Date and time when the postal distribution status was last updated.
WebhookRef	string	Unique reference identifier associated with the webhook notification for the postal status update.
OnlineAccessStatus	object	Returns the online access status information for the employee.
Email	string	Email address to which online access has been provided.
Code	string	Status code representing the online access status.
Status	string	Current online access status (for example, ORDER_CREATED, EMAIL_SENT, or VIEWED_FORM).
Message	string	Additional information related to the online access status. Returns null if no additional information is available.
StatusTs	string	Date and time when the online access status was last updated.
WebhookRef	string	Unique reference identifier associated with the webhook notification for the online access status update.

Payload

Request Json

Sample	Description	Action
Sample 1	Transmit Form W2 returns using SubmissionId and optional RecordIds.

Sample 1

{
  "SubmissionId": "e50c27b8-631c-45f0-be19-f786fc69ba60",
  "RecordIds": [
    "cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b",
    "a1be3c36-1111-2222-3333-4445556666"
  ],
  "WebhookRef": "Webhook_5fghr6"
}

Response JSON

Response	Description	Action
200	Success Response - This is a sample response for successful API requests.

Response: 200

{
  "FormW2Records": [
    {
      "FormType": "FormW2",
      "BusinessId": "bbd57dc2-d948-40cd-b67b-9fe06cc62218",
      "SubmissionId": "cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b",
      "RecordId": "a1be3c36-1111-2222-3333-4445556666",
      "FederalStatus": {
        "Code": "FED-005",
        "Status": "TRANSMITTED",
        "Message": null,
        "StatusTs": "2026-01-25T11:42:00-05:00",
        "WebhookRef": "Web001_845834gdfgked"
      },
      "StatesStatus": [
        {
          "StateCd": "AZ",
          "Code": "ST-005",
          "Status": "TRANSMITTED",
          "Message": null,
          "StatusTs": "2026-01-25T13:08:00-05:00",
          "WebhookRef": "Webhook_845834gfdgkdf"
        }
      ],
      "Distribution": {
        "DistributionType": "POSTAL_AND_ONLINE",
        "PostalStatus": {
          "PostalType": "USPS_FIRST_CLASS",
          "Code": "POS-007",
          "Status": "ORDER_CREATED",
          "Message": null,
          "StatusTs": "2026-01-30T16:00:00-05:00",
          "WebhookRef": "Webhook_845834gfdgkdf"
        },
        "OnlineAccessStatus": {
          "Email": "shawn@sample.com",
          "Code": "OA-004",
          "Status": "ORDER_CREATED",
          "Message": null,
          "StatusTs": "2026-01-26T08:15:00-05:00",
          "WebhookRef": "Webhook_845834gfdgkdf"
        }
      }
    }
  ]
}

Go Lang

package main

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

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

  payload := strings.NewReader(`{
    "SubmissionId": "e50c27b8-631c-45f0-be19-f786fc69ba60",
    "RecordIds": [
      "cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b",
      "a1be3c36-1111-2222-3333-4445556666"
    ],
    "WebhookRef": "Webhook_5fghr6"
  }`)

  client := &http.Client{}

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

  req.Header.Add("Content-Type", "application/json")
  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 data = JSON.stringify({
  "SubmissionId": "e50c27b8-631c-45f0-be19-f786fc69ba60",
  "RecordIds": [
    "cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b",
    "a1be3c36-1111-2222-3333-4445556666"
  ],
  "WebhookRef": "Webhook_5fghr6"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: '<APIURL>/v2.0.0/Formw2/transmit',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': '<ACCESS_TOKEN>'
  },
  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({
  "SubmissionId": "e50c27b8-631c-45f0-be19-f786fc69ba60",
  "RecordIds": [
    "cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b",
    "a1be3c36-1111-2222-3333-4445556666"
  ],
  "WebhookRef": "Webhook_5fghr6"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': '<ACCESS_TOKEN>'
}
conn.request("POST", "/v2.0.0/Formw2/transmit", 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/Formw2/transmit");
request.Headers.Add("Authorization", "<ACCESS_TOKEN>");
var content = new StringContent("{
  "SubmissionId": "e50c27b8-631c-45f0-be19-f786fc69ba60",
  "RecordIds": [
    "cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b",
    "a1be3c36-1111-2222-3333-4445556666"
  ],
  "WebhookRef": "Webhook_5fghr6"
}", 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/Formw2/transmit")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "<ACCESS_TOKEN>"
request.body = JSON.dump({
  "SubmissionId": "e50c27b8-631c-45f0-be19-f786fc69ba60",
  "RecordIds": [
    "cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b",
    "a1be3c36-1111-2222-3333-4445556666"
  ],
  "WebhookRef": "Webhook_5fghr6"
})

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, "{
  "SubmissionId": "e50c27b8-631c-45f0-be19-f786fc69ba60",
  "RecordIds": [
    "cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b",
    "a1be3c36-1111-2222-3333-4445556666"
  ],
  "WebhookRef": "Webhook_5fghr6"
}");
Request request = new Request.Builder()
  .url("<APIURL>/v2.0.0/Formw2/transmit")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "<ACCESS_TOKEN>")
  .build();
Response response = client.newCall(request).execute();

cURL

curl --location '<APIURL>/v2.0.0/Formw2/transmit' --header 'Content-Type: application/json' --header 'Authorization: <ACCESS_TOKEN>' --data '{
  "SubmissionId": "e50c27b8-631c-45f0-be19-f786fc69ba60",
  "RecordIds": [
    "cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b",
    "a1be3c36-1111-2222-3333-4445556666"
  ],
  "WebhookRef": "Webhook_5fghr6"
}'