List tax returns
curl --request GET \
--url https://api.melso.ai/v1/companies/{company_id}/tax-returns \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.melso.ai/v1/companies/{company_id}/tax-returns"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.melso.ai/v1/companies/{company_id}/tax-returns', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": [
{
"id": "<string>",
"model": "<string>",
"period": "2026-Q3",
"status": "draft",
"is_estimate": true,
"amount": "121.00",
"version": 123,
"approved_version": 123,
"approved_at": "2023-11-07T05:31:56Z",
"deadline": "2023-12-25",
"direct_debit_deadline": "2023-12-25",
"boxes": [
{
"box": "<string>",
"key": "<string>",
"amount": "121.00"
}
],
"records": [
{
"tax_id": "<string>",
"name": "<string>",
"country": "<string>",
"key": "<string>",
"amount": "121.00",
"withheld": "121.00",
"quarters": [
"121.00"
],
"missing": [
"tax_id"
]
}
],
"review": [
"missing_tax_id"
],
"unconfirmed_expenses": 123,
"filed_at": "2023-11-07T05:31:56Z",
"filing": {
"filed_at": "2023-11-07T05:31:56Z",
"reference": "<string>",
"csv": "<string>",
"receipt": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"filename": "<string>",
"content_type": "<string>",
"size_bytes": 123,
"url": "<string>"
},
"filed_by": "melso"
},
"recalculated": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
],
"next_cursor": "<string>"
}{
"error": "invalid token",
"code": "unauthorized",
"request_id": "req_01JAB3K9X2"
}{
"error": "invoice not found",
"code": "not_found",
"request_id": "req_01JAB3K9X2"
}Tax returns
List tax returns
Lists the company’s returns: the ones Melso calculated (drafts, approved and filed) and the reminder forms marked filed.
GET
/
companies
/
{company_id}
/
tax-returns
List tax returns
curl --request GET \
--url https://api.melso.ai/v1/companies/{company_id}/tax-returns \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.melso.ai/v1/companies/{company_id}/tax-returns"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.melso.ai/v1/companies/{company_id}/tax-returns', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": [
{
"id": "<string>",
"model": "<string>",
"period": "2026-Q3",
"status": "draft",
"is_estimate": true,
"amount": "121.00",
"version": 123,
"approved_version": 123,
"approved_at": "2023-11-07T05:31:56Z",
"deadline": "2023-12-25",
"direct_debit_deadline": "2023-12-25",
"boxes": [
{
"box": "<string>",
"key": "<string>",
"amount": "121.00"
}
],
"records": [
{
"tax_id": "<string>",
"name": "<string>",
"country": "<string>",
"key": "<string>",
"amount": "121.00",
"withheld": "121.00",
"quarters": [
"121.00"
],
"missing": [
"tax_id"
]
}
],
"review": [
"missing_tax_id"
],
"unconfirmed_expenses": 123,
"filed_at": "2023-11-07T05:31:56Z",
"filing": {
"filed_at": "2023-11-07T05:31:56Z",
"reference": "<string>",
"csv": "<string>",
"receipt": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"filename": "<string>",
"content_type": "<string>",
"size_bytes": 123,
"url": "<string>"
},
"filed_by": "melso"
},
"recalculated": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
],
"next_cursor": "<string>"
}{
"error": "invalid token",
"code": "unauthorized",
"request_id": "req_01JAB3K9X2"
}{
"error": "invoice not found",
"code": "not_found",
"request_id": "req_01JAB3K9X2"
}Live capability. Melso runs this in production today. Partner keys reach it once your partner account is enabled. See Availability.
version. Without an active tax
service, the list carries estimates (is_estimate true) instead of
drafts.Authorizations
Your partner secret key, mk_live_… for real companies or mk_test_…
for test companies. Keep it on your servers. See
Authentication.
Path Parameters
The company's ID. Every company-scoped call works in exactly this company.
Query Parameters
Page size.
Required range:
1 <= x <= 200The next_cursor of the previous page.
Only this form, such as 303.
draft: calculated, still recalculated from the records. approved: the owner authorized this exact version. filed: filed, with the administration's reference and receipt when Melso filed it.
Available options:
draft, approved, filed