Packet API

Keys and modes

• fyl_test_ keys are free and return a sample marked TEST, NOT FOR FILING on every page. Use them to build and test.
• fyl_live_ keys work while the firm has a Firm + API plan or a license in force, put your firm's name on the cover, and use one credit per packet. When neither is in force, live keys stop at once and test keys keep working.
• A key can expire, be limited to scopes (packets, usage) and to an IP allowlist, and be rotated: the new key is a twin and the old one keeps working for the overlap you choose. Rotate before a key expires.
• Send the key as Authorization: Bearer <key>. Create and revoke keys on the API page.

Request

POST https://api.fylit.tax/api/v1/packets with the client's information as JSON. The fields are the ones the Fylit Pro wizard collects; the OpenAPI spec lists each one, with a complete example.

curl -sS https://api.fylit.tax/api/v1/packets \
  -H "Authorization: Bearer $FYLIT_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-123" \
  --data @packet.json -o packet.pdf -D -

Retry safely with Idempotency-Key: the same key and the same body is not charged twice. Response headers say Fylit-Mode, Fylit-Charged and, for live keys, Fylit-Credits-Remaining.

Batches

POST https://api.fylit.tax/api/v1/packet-batches with {"items": [...]} (up to 10 packet requests, each with an optional client_ref of your own). The answer is a ZIP of the PDFs that were made and a results.json with each item's result or error. One item's error does not stop the others, and only packets that were made use a credit. It is synchronous on purpose: nothing is stored, so there is nothing to fetch later and no webhook. Send an Idempotency-Key to make the whole batch safe to retry: a retry charges only for packets not yet made.

Usage

GET https://api.fylit.tax/api/v1/usage lists your firm's calls, newest first: the key, the time, the status, the tax year, the pages and whether a credit was used, never the request. Filter with key, from and to (dates, inclusive), page with limit and before, and add output=csv for a CSV. The key needs the usage scope.

Errors

400 invalid_request

The body is not valid. errors names each field.

402 no_credits

Live key and no credits left. Nothing is generated.

401

Missing, invalid, revoked or expired key. An expired key says so; rotate keys before they expire.

403 ip_not_allowed

The key has an IP allowlist and the call came from outside it.

403 insufficient_scope

The key lacks the scope this call needs (packets to make packets).

403 live_access_ended

A live key, and the firm has no Firm + API plan or license in force. Test keys still work.

403 firm_suspended

The firm is suspended. Nothing is charged. Sign in to Fylit Pro to resolve it.

403 terms_not_accepted

The firm's owner has not accepted the Pro terms now in force. Nothing is charged.

400 batch_too_large

A batch holds more than 10 packets.

422 batch_failed

No packet in the batch could be made. items lists each item's error. Nothing is charged.

422 validation_blocked

The engine cannot build this packet. validation_issues lists each blocking answer.

422 not_renderable

The case is outside what Fylit supports (for example not a foreign-owned single-member LLC).

422 idempotency_key_reused

The Idempotency-Key was used before with a different body.

429

More than 60 requests a minute on one key, counted across packets, batches and usage. Wait Retry-After seconds and send it again. Nothing is charged.

500 render_failed

The renderer failed. Nothing is charged or kept, and the Idempotency-Key stays usable. Send it again.

What Fylit keeps

Nothing from the request. It is validated and rendered, and every record it created is rolled back before the PDF is returned. Fylit logs only which key called, when, the status, the tax year, the page count, and a fingerprint of the body for idempotency. Your firm reviews, signs and files every return prepared with Fylit.