The IRISfile API

The beta runs on sandbox keys

Base URL and authentication

Quick start: from a file to an IRS acknowledgement

These steps file two test 1099-NEC records with the IRS sandbox using curl. Each step uses the values the step before it returned.

1. 1

   Create a sandbox key

   In the dashboard, open API keys, choose Sandbox and click Create key. Copy the key: IRISfile shows it once. The API key help article shows each screen.

   export IRISFILE_API_KEY=irf_test_...   # your sandbox key
   export BASE=https://irisfile.co/api/v1

2. 2

   Register a webhook endpoint

   Register an https endpoint before you send a file: IRISfile sends an event only to the endpoints that exist when it happens. Copy the secret from the response: it is not shown again. Send a test event, then check the delivery.

   curl -s "$BASE/webhook-endpoints" \
     -H "Authorization: Bearer $IRISFILE_API_KEY" \
     -H "content-type: application/json" \
     -d '{"url":"https://example.com/irisfile/webhook","description":"Staging"}'

   {
     "endpoint": { "id": "0b7d...", "url": "https://example.com/irisfile/webhook", "environment": "sandbox", ... },
     "secret": "whsec_..."
   }

   export ENDPOINT=0b7d...   # endpoint.id
   curl -s -X POST "$BASE/webhook-endpoints/$ENDPOINT/test" -H "Authorization: Bearer $IRISFILE_API_KEY"
   curl -s "$BASE/webhook-endpoints/$ENDPOINT/deliveries" -H "Authorization: Bearer $IRISFILE_API_KEY"

3. 3

   Validate a test file

   Save these two records as sandbox-nec.csv. They use the IRISfile CSV template columns and IRS test TINs. Validating stores nothing.

   form_type,tax_year,payer_tin,payer_tin_type,payer_name,payer_address,payer_city,payer_state,payer_zip,payer_phone,payee_tin,payee_tin_type,payee_name,payee_address,payee_city,payee_state,payee_zip,account_number,box_1
   NEC,2025,00-0111111,EIN,Harbor Light Bookkeeping LLC,40 Wharf St,Portland,ME,04101,2075550100,000-11-1112,SSN,Dana M Whitfield,18 Spring St,Portland,ME,04102,HL-001,8400.00
   NEC,2025,00-0111111,EIN,Harbor Light Bookkeeping LLC,40 Wharf St,Portland,ME,04101,2075550100,000-11-1113,SSN,Luis A Ferreira,7 Ocean Ave,South Portland,ME,04106,HL-002,12650.00
   

   curl -s "$BASE/validate" \
     -H "Authorization: Bearer $IRISFILE_API_KEY" \
     -F "file=@sandbox-nec.csv"

   {
     "validation": {
       "source": "csv",
       "recordCount": 2,
       "counts": { "parseErrors": 0, "validationErrors": 0, "warnings": 0, "infos": 1, "excludedRecords": 0 },
       "readyToConvert": true,
       "diagnostics": [{
         "recordIndex": null, "sourceRow": null, "field": null,
         "severity": "info", "code": "cfsf.auto_elected",
         "message": "CF/SF elected from the payee's state for 2 records (ME 2)."
       }],
       "diagnosticsTruncated": false
     }
   }

4. 4

   Create a submission

   The same file, sent to /submissions, is stored and converted to IRIS XML in the same request. The answer is 201 with the submission. A file over 4.5 MB goes through /uploads first, and that submission converts in the background (202).

   curl -s "$BASE/submissions" \
     -H "Authorization: Bearer $IRISFILE_API_KEY" \
     -F "file=@sandbox-nec.csv"

   {
     "submission": {
       "id": "6f1c2a9e-...",
       "status": "xml_generated",
       "stage": "ready_to_file",
       "counts": { "records": 2, "validationErrors": 0, "lockedForms": 0, ... },
       "transmissions": [{ "sequence": 1, "taxYear": 2025, "records": 2, "status": "not_filed", ... }],
       ...
     }
   }

   # Files over 4.5 MB: reserve, PUT, then create from the token.
   curl -s "$BASE/uploads" -H "Authorization: Bearer $IRISFILE_API_KEY" \
     -H "content-type: application/json" \
     -d '{"filename":"big.csv","size":31457280,"contentType":"text/csv"}'
   curl -X PUT "<uploadUrl>" -H "content-type: text/csv" --data-binary @big.csv
   curl -s "$BASE/submissions" -H "Authorization: Bearer $IRISFILE_API_KEY" \
     -H "content-type: application/json" \
     -d '{"uploadToken":"<uploadToken>","filename":"big.csv"}'

5. 5

   Check the status

   Poll the submission until its stage is ready_to_file or ready_to_unlock, or wait for the submission.converted webhook. Then file it. ready_to_unlock means some forms are not paid for yet. The file call pays for them from your credits, and it needs the tax year's license. If the stage reads needs_fixing, list the errors, fix the file and create a new submission.

   export ID=6f1c2a9e-...   # submission.id
   curl -s "$BASE/submissions/$ID" -H "Authorization: Bearer $IRISFILE_API_KEY"
   curl -s "$BASE/submissions/$ID/diagnostics?severity=error" -H "Authorization: Bearer $IRISFILE_API_KEY"

6. 6

   File with the IRS

   The file call sends each transmission to the IRS sandbox and returns its receipt ID. A sandbox file needs no body. If the answer is 409 filing_incomplete, send the same call again later: a transmission is never sent twice.

   curl -s -X POST "$BASE/submissions/$ID/file" \
     -H "Authorization: Bearer $IRISFILE_API_KEY"

   {
     "status": "submitted",
     "transmissions": [{
       "sequence": 1,
       "status": "receipted",
       "utid": "c55915bb-...:IRIS:...::A",
       "receiptId": "2025-...",
       "state": "submitted",
       ...
     }],
     "billing": { "debitedCents": 0, "balanceCents": 0 }
   }

7. 7

   Download the XML

   The outputs route answers 302 to a storage link that expires in 5 minutes. Its JSON body repeats the link with the billing.

   # Without -L, curl prints the JSON body: the link, its expiry and the billing.
   curl -s "$BASE/submissions/$ID/outputs/xml" -H "Authorization: Bearer $IRISFILE_API_KEY"
   # With -L, curl follows the link and saves the file.
   curl -sL "$BASE/submissions/$ID/outputs/xml" -H "Authorization: Bearer $IRISFILE_API_KEY" -o irs.xml

8. 8

   Wait for the acknowledgement

   The IRS sandbox acknowledges a transmission after it gives the receipt. IRISfile asks the IRS for acknowledgements at most every 60 minutes, and less often after an IRS lookup error. Your endpoint then gets transmission.acknowledged with the ack code. Without a webhook, poll the submission until each transmission has an ackCode.

Endpoints

Every path is relative to https://irisfile.co/api/v1. The OpenAPI spec has each request body, response and error code.

POST /validate

Check a file or JSON records. Stores nothing.

POST /uploads

Reserve a direct upload for a file over 4.5 MB.

POST /submissions

Create a submission from a file or an upload, and convert it.

GET /submissions/{id}

Status, counts, the quote for unpaid forms and each transmission.

GET /submissions/{id}/diagnostics

Errors, warnings and notices, one page at a time.

POST /submissions/{id}/file

File with the IRS. Safe to retry.

GET /submissions/{id}/outputs/{kind}

Redirect to the xml, portal-csv or copy-b download.

GET /webhook-endpoints

List your webhook endpoints.

POST /webhook-endpoints

Register an endpoint. Returns its signing secret once.

DELETE /webhook-endpoints/{id}

Delete an endpoint and cancel its pending deliveries.

POST /webhook-endpoints/{id}/test

Send a webhook.test event to one endpoint.

GET /webhook-endpoints/{id}/deliveries

The endpoint's recent deliveries and their results.

Common error codes

Only the file call and the outputs route spend form credits. A form stays paid after its first debit, so an error after the debit costs nothing to retry. The spec lists every code per route.

invalid_api_key 401

Send a current key as Authorization: Bearer or x-api-key.

rate_limited 429

Wait for the seconds in Retry-After, then retry.

invalid_request 400

Fix the body or the query. The message names the problem.

not_found 404

The id is not in this account, or it belongs to the other environment.

not_ready 409

The file is still converting. Retry after Retry-After.

filing_incomplete 409

Some transmissions may already be filed and paid. Keep the submission, read transmissions and billing in the body, then retry the same call. Nothing is sent twice.

transmission_required 409

Add ?transmission=<sequence> to download one transmission's XML.

sandbox_output_unavailable 409

Sandbox files serve only the xml output.

license_required 402

Buy the tax year's license in the dashboard.

payment_required 402

Buy form credits. The body carries the quote and the balance.

irs_filing_failed 502

The IRS refused or failed the call. Retry later; the body lists each transmission.

Credits and billing headers

Webhooks

IRISfile posts each event as JSON to your https endpoints in the key's environment. An account can hold 5 endpoints per environment. Payloads carry ids, statuses, counts and IRS receipt IDs, never a TIN, a name or an amount.

An event

{
  "id": "5d0e...",
  "type": "transmission.acknowledged",
  "created": "2026-10-21T18:04:11.000Z",
  "apiVersion": "2026-10-21",
  "environment": "sandbox",
  "data": {
    "submission": { "id": "6f1c2a9e-...", "parentId": null },
    "transmission": { "id": "...", "sequence": 1, "taxYear": 2025, "receiptId": "2025-...",
                      "ackCode": "A", "irsStatus": "Accepted", "errorCount": 0 }
  }
}

Delivery

• Each post carries IRISfile-Signature, IRISfile-Event-Id and IRISfile-Event-Type headers.
• Answer with any 2xx status within 10 seconds. A redirect or any other status counts as a failure.
• A failed post is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours. The delivery stops after 7 attempts.
• Delivery is at least once, so skip an event id you have already handled.

Verify the signature

The header reads t=<unix seconds>,v1=<hex>. The v1 value is an HMAC-SHA256 of ${t}.${raw body}, keyed with the endpoint's whole whsec_ secret. Compute it over the raw body before you parse it, compare in constant time, and reject a t more than 300 seconds from your clock.

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body exactly as received, before JSON.parse.
// header: the IRISfile-Signature header. secret: your whsec_... string.
export function verifyIrisfileSignature(rawBody, header, secret, toleranceSeconds = 300) {
  if (!header) return false;
  let t = null;
  const v1 = [];
  for (const part of header.split(",")) {
    const i = part.indexOf("=");
    if (i < 0) continue;
    const key = part.slice(0, i).trim();
    const value = part.slice(i + 1).trim();
    if (key === "t" && /^\d{1,12}$/.test(value)) t = Number(value);
    if (key === "v1" && /^[0-9a-f]{64}$/.test(value)) v1.push(value);
  }
  if (t === null || v1.length === 0) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSeconds) return false;
  const expected = Buffer.from(
    createHmac("sha256", secret).update(`${t}.${rawBody}`, "utf8").digest("hex"),
    "ascii",
  );
  return v1.some((s) => timingSafeEqual(Buffer.from(s, "ascii"), expected));
}

In Express, read the body raw on the webhook route only:

import express from "express";
import { verifyIrisfileSignature } from "./verify.js";

const app = express();
app.post("/irisfile/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const body = req.body.toString("utf8");
  if (!verifyIrisfileSignature(body, req.get("IRISfile-Signature"), process.env.IRISFILE_WEBHOOK_SECRET)) {
    return res.sendStatus(400);
  }
  const event = JSON.parse(body);
  // Delivery is at least once: skip an event.id you have already handled.
  res.sendStatus(204);
});

Questions