📡 API Calls

API Requests Best Practice.

TaxStreem exposes a modern and intuitive RESTful API over HTTPS, enabling developers to build robust tax compliance features directly into their products. Our API supports the following HTTP methods:

GET— Retrieve data
POST— Submit filings and create resources
DELETE— Remove records

All requests must be authenticated using your secret API key in the request header. See the Business Account page for setup details.

🔄 Request Rate Limits

To ensure fair use and reliable performance, TaxStreem enforces rate limits on all API requests:

⏱️

Limit: 500 requests per minute per business

If your application exceeds this threshold, TaxStreem will return a 429 Too Many Requests response. We recommend implementing a retry strategy with exponential backoff.

Environment	Limit	Burst
Sandbox	5 RPS	10 concurrent
Production	50 RPS	100 concurrent

📋 Request Requirements

Every API call must include the following headers:

Header	Required	Value
x-api-key	Required	Your secret API key from the Partner Dashboard
Content-Type	Required	application/json

curl -X POST https://sandbox-api.taxstreem.com/v1/flux/vat-filing/single \
  -H "Content-Type: application/json" \
  -H "x-api-key: ts_live_xxxxxxxxxxxx" \
  -d '{ "amount": 5000, "taxId": "2345544-0001", "vatStatus": 1 }'

📬 Response Format

All responses are JSON. Synchronous endpoints return 200 OK with data inline. Filing operations return 202 Accepted immediately — the final result is delivered via webhook.

✅ 202 Accepted

{
  "status": "accepted",
  "message": "schedule accepted",
  "data": {
    "id": "xaee2ddf-effvkfes",
    "created_at": "2026-02-20T10:00:00Z"
  }
}

❌ 400 Bad Request

{
  "status": "error",
  "message": "Invalid parameters",
  "errors": [{
    "field": "taxId",
    "message": "Tax ID is required"
  }]
}

📘 HTTP Status Codes

Code	Meaning
200 OK	Request succeeded. Data returned in response body.
202 Accepted	Async job enqueued. Final result delivered via webhook.
400 Bad Request	Missing or invalid request parameters.
401 Unauthorized	API key is missing or invalid.
403 Forbidden	Your account does not have permission for this resource.
429 Too Many Requests	Rate limit exceeded. Retry with exponential backoff.
500 Internal Server Error	Unexpected server error. Retry after a short delay.

✅ Developer Tips

🔒

Never expose your API key in client-side code, Git repos, or logs. Store it in environment variables or a secrets manager.

🔁

All filing endpoints are async. Use webhooks to receive the final result — do not poll for status.

📦

For high-volume operations, use the batch filing endpoints. A single request can carry up to 500 records, slashing network overhead.

🧪

Always develop against the sandbox environment first. Production calls trigger real filings with revenue authorities.

⏱️

If you hit a 429, apply exponential backoff with jitter. Stagger retries over increasing intervals — never hammer the API.