Analyze Items

Authentication Required

This endpoint requires a valid API key. Include your API key in the x-api-key header of every request. You can generate a test key in your developer dashboard.

The Analyze Items API accepts an invoice document — PDF, DOCX, XLS, XLSX, or DOC — and reads it line-by-line to determine the correct tax treatment for each item. Prism returns the applicable tax type (VAT, WHT, or CIT), the computed tax amount per line, and the total tax across the entire document.

You pass a publicly accessible documentUrl pointing to the invoice file. Prism fetches, parses, and classifies each line item, then delivers the full analysis to your webhook endpoint.

Integration Flow

1Host the Document: Upload your invoice to a storage bucket (S3, GCS, Azure Blob) and make it publicly accessible, or generate a signed URL with at least 5 minutes TTL.
2Submit the URL: POST the documentUrl along with your invoiceId and currency. Prism accepts PDF, DOCX, XLS, XLSX, and DOC formats only.
3Receive Analysis: Listen for the prism.analysis.complete webhook event which carries the per-line tax breakdown and total tax liability.

Supported formats: PDF · DOCX · DOC · XLS · XLSX — maximum file size 20 MB. Scanned images within PDFs are processed via OCR automatically.

HTTP Request

POSThttps://api.taxstreem.com/v1/prism/analyze-items

Request Body

The following parameters are required for this action.

Parameter	Type	Required	Description
encryptedPayload	string	Required	Your Base64-encoded, AES-256-GCM in-flight encrypted TaxPromax credentials (email and password). See Encryption Section for generation steps.
filingId	string	Required	Your unique internal ID representing this VAT filing request. Limits duplicate filings (Idempotency Key).
month	number	Required	Numeric month you are filing for. Valid values: `1` to `12`. Late filings may incur penalties from the authority.
year	number	Required	4-digit year for the filing (e.g. `2024`).
vatStatus	number	Required	Determines tax treatment. Valid values: `0` (VATABLE), `1` (ZERO RATED), `2` (VAT EXEMPT).
amount	number	Required	The total invoice or item amount exclusive of VAT.
item	string	Required	Name or category of the exchanged product/service (e.g. `Enterprise Software License`).
narration	string	Optional	Detailed context or invoice reference line for the item. Helps your finance team during auditing.
taxId	string	Optional	The customer's TIN. If the customer isn't registered or it's a B2C transaction, provide `"0"`.
beneficiary	string	Optional	Customer name. If blank/B2C, default system value is `"Retail Customer"`.

Response Documentation

A successful invocation of this endpoint returns a 202 Accepted or 200 OK. Since filing operations are processed asynchronously alongside tax gateways, the immediate response acknowledges successful receipt and enqueueing of the schedule payload.

Field Name	Type	Description
status	string	The high-level outcome of the request context. Value is typically `accepted` indicating payload validation passed.
message	string	A human-readable confirmation note (e.g. "schedule accepted successfully").
data.id	string	The tracking UUID for this schedule. This precise ID correlates to the `filingId` in downstream webhook events.
data.created_at	string (date-time)	Timestamp marking the instant the schedule safely enqueued, in ISO 8601 format.

Error Handling

The API applies standard HTTP status codes indicating success or failure. In case of an anomaly, the response body contains an errors array detailing specific field-level validation issues to facilitate rapid integration debugging.

HTTP Status	Error Key	Cause & Resolution
400	Bad Request	Cause: Missing required fields, invalid attributes (e.g. malformed TIN), or structural JSON anomalies. Resolution: Traverse the `errors` array in the response to target the invalid field constraints, format properly, and re-submit.
401	Unauthorized	Cause: The API key credential is missing, malformed, or revoked. Resolution: Ensure your `x-api-key` is populated in the request header and that you are matching the correct environment bounds (live vs test).
403	Forbidden	Cause: Properly authenticated, but the key context is lacking specific scope permissions or the merchant account represents restricted access. Resolution: Review integration scopes within the dashboard to assure capability rights correspond to PRISM operations.
429	Too Many Requests	Cause: Network volume exceeds the rate envelope associated with your tier configuration. Resolution: Gracefully throttle via exponential backoff semantics checking the `Retry-After` header variable, or upgrade capacity constraints.

Example Request

curl -X POST https://api.taxstreem.com/v1/prism/analyze-items \
  -H "x-api-key: txsm_test_SK489c..." \
  -H "Content-Type: application/json" \
  -d '{
    "documentUrl": "https://storage.example.com/invoices/inv-00291.pdf",
    "invoiceId": "INV-00291",
    "currency": "NGN"
  }'

Example Response

202 Accepted

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