KintsugiKintsugi
API reference / Get filings

Get filings

GET/v1/filings

The Get Filings API retrieves a paginated list of filings based on filters such as dates, jurisdiction, Country, status, etc. This helps track and manage tax filings efficiently across multiple jurisdictions.

Authorization

x-api-keystringRequired

Your secret API key. Include it with every request.

x-organization-idstringRequired

Identifies the organization this request acts on.

Query

Every query parameter below is optional. Combine as many as you need and append them to the endpoint as a query string. The example shows a few to get you started.

/v1/filings?status__in=<status__in>&country_code=<country_code>&page=<page>
status__instring

Filter filings by status

Available options:FILEDFILINGUNFILEDPAUSED
start_datestring

Filter filings with a start date greater than or equal to this date.

end_datestring

Filter filings with an end date less than or equal to this date.

date_filed__gtestring

Filter filings filed on or after this date.

date_filed__ltestring

Filter filings filed on or before this date.

order_bystring

Comma-separated list of fields to sort the results.

Available options:statusstart_dateend_dateamount
state_codestring

Filter filings by state code (e.g., CA for California).

country_codeCountryCodeEnum[]

Filter filings by country code in ISO 3166-1 alpha-2 format (e.g., US).

Available options:AFAXALDZASADAOAIAQAGARAMAWAUATAZBSBHBDBBBYBEBZBJBMBTBOBQBABWBVBRIOBNBGBFBICVKHCMCAKYCFTDCLCNCXCCCOKMCGCDCKCRHRCUCWCYCZDKDJDMDOECEGSVGQEREESZETFKFOFJFIFRGFPFTFGAGMGEDEGHGIGRGLGDGPGUGTGGGNGWGYHTHMVAHNHKHUISINIDIRIQIEIMILITCIJMJPJEJOKZKEKIKPKRKWKGLALVLBLSLRLYLILTLUMOMGMWMYMVMLMTMHMQMRMUYTMXFMMDMCMNMEMSMAMZMMNANRNPNLNCNZNINENGNUNFMKMPNOOMPKPWPSPAPGPYPEPHPNPLPTPRQARERORURWBLSHKNLCMFPMVCWSSMSTSASNRSSCSLSGSXSKSISBSOZAGSSSESLKSDSRSJSECHSYTWTJTZTHTLTGTKTOTTTNTRTMTCTVUGUAAEGBUSUMUYUZVUVEVNVGVIWFEHYEZMZWXKZZ_EU
pageinteger

Page number

sizeinteger

Page size

Response

itemsFilingRead[]Required
totalintegerRequired
pageintegerRequired
sizeintegerRequired
pagesintegerRequired
200

Successfully retrieved filings

401

Unauthenticated request.

404

Resource not found

422

Validation error

500

Internal server error

cURL
GET /v1/filings?status__in=FILED,FILING,UNFILED,PAUSED&country_code=US&page=1
-H "x-api-key: ***"
-H "x-organization-id: ***"
Example request
https://api.trykintsugi.com/v1/filings?status__in=FILED,FILING,UNFILED,PAUSED&country_code=US&page=1
Response
{
"items": [
{
"status": "FILED",
"start_date": "2024-01-01",
"end_date": "2024-12-31",
"due_date": "2025-01-20",
"date_filed": "2025-01-19",
"is_manual": false,
"state_code": "CA",
"state_name": "California",
"country_code": "US",
"jira_issue_key": "TO-1234",
"auto_approved": true,
"amount_calculated": "2500.00",
"amount_adjusted": "0.00",
"amount_discounts": "0.00",
"amount_fees": "50.00",
"amount_penalties": "10.00",
"amount_tax_collected": "2510.00",
"amount_sales": "125000.00",
"amount": "2510.00",
"total_tax_liability": "2510.00",
"transaction_count": 25,
"internal_notes": "Filing completed successfully.",
"tax_remitted": "2510.00",
"return_confirmation_id": "RC123456789",
"payment_confirmation_id": "PC987654321",
"id": "file_ABC123XYZ789",
"registration_id": "regs_12345ABCDE"
},
{
"status": "FILING",
"start_date": "2024-07-01",
"end_date": "2024-09-30",
"due_date": "2024-10-15",
"is_manual": true,
"state_code": "NY",
"state_name": "New York",
"country_code": "US",
"jira_issue_key": "TO-5678",
"auto_approved": false,
"amount_calculated": "1200.00",
"amount_adjusted": "0.00",
"amount_discounts": "0.00",
"amount_fees": "30.00",
"amount_penalties": "0.00",
"amount_tax_collected": "1230.00",
"amount_sales": "62000.00",
"amount": "1230.00",
"total_tax_liability": "1230.00",
"transaction_count": 18,
"tax_remitted": "0.00",
"id": "file_DEF456UVW321",
"registration_id": "regs_67890VWXYZ"
}
],
"total": 2,
"page": 1,
"size": 50,
"pages": 1
}