Read workspace tax control

GET/v1/reports/tax-control

Query parameters

bankAccountId string

Optional bank account id filter or query option.

Minimum length: 1 character. · Maximum length: 128 characters.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1G

start string

Calendar date in YYYY-MM-DD format for the reporting period.

Maximum length: 10 characters.

Example2026-01-15

end string

Calendar date in YYYY-MM-DD format for the reporting period.

Maximum length: 10 characters.

Example2026-01-15

range string

Optional range filter or query option.

Allowed values: "all"

Exampleall

timezone string

Optional timezone filter or query option.

Maximum length: 100 characters.

ExampleUTC

clients string[]

Optional clients filter or query option.

at most 500 items

Example1 item

projects string[]

Optional projects filter or query option.

at most 500 items

Example1 item

vendors string[]

Optional vendors filter or query option.

at most 500 items

Example1 item

tags string[]

Optional tags filter or query option.

at most 500 items

Example1 item

invoices string[]

Optional invoices filter or query option.

at most 500 items

Example1 item

expenses string[]

Optional expenses filter or query option.

at most 500 items

Example1 item

recurringExpenses string[]

Optional recurring expenses filter or query option.

at most 500 items

Example1 item

payouts string[]

Optional payouts filter or query option.

at most 500 items

Example1 item

Headers

authorization string required

Bearer workspace API key.

ExampleBearer $NQD_API_KEY

workspace-id string required

Workspace scope for the request. Required for workspace operations and must belong to the authenticated identity.

Minimum length: 1 character. · Maximum length: 128 characters.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1A

Response

200Success

Response headers

x-request-id string

Correlation identifier returned with every response for support and request tracing.

Example550e8400-e29b-41d4-a716-446655440000

data object

Returned records. Collections and batches use an array; single records use an object.

ShowHide 16 properties

data.currency object

Referenced currency with its opaque ID and ISO 4217 currency code.

ShowHide 4 properties

data.currency.id string

Opaque identifier for this resource or reference.

Minimum length: 1 character. · Maximum length: 128 characters.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1F

data.currency.code string

ISO 4217 currency code, such as SAR or USD.

Minimum length: 1 character. · Maximum length: 128 characters.

ExampleSAR

data.currency.conversion object

Currency conversion quote used for reporting, including source, target, and rate.

ShowHide 3 properties

data.currency.conversion.from string

ISO 4217 code of the source currency in this persisted quote.

Minimum length: 1 character. · Maximum length: 128 characters.

ExampleSAR

data.currency.conversion.to string

ISO 4217 code of the target reporting currency in this persisted quote.

Minimum length: 1 character. · Maximum length: 128 characters.

ExampleSAR

data.currency.conversion.rate string

Exact decimal conversion rate from the quote source currency to its target currency.

Maximum length: 128 characters.

Example1.00

data.currency.name string

Display name of the record.

ExampleSaudi Riyal

data.period object

period for this report.

ShowHide 2 properties

data.period.start string

Calendar date in YYYY-MM-DD format for the reporting period.

Maximum length: 10 characters.

Example2026-01-01

data.period.end string

Calendar date in YYYY-MM-DD format for the reporting period.

Maximum length: 10 characters.

Example2026-01-31

data.fiscalStart string

fiscal start for this report.

Example2026-01-01

data.filters object

filters for this report.

ShowHide 2 properties

data.filters.start string

Calendar date in YYYY-MM-DD format for the reporting period.

Example2026-01-01

data.filters.end string

Calendar date in YYYY-MM-DD format for the reporting period.

Example2026-01-31

data.opening number

opening for this report.

Example100

data.output number

output for this report.

Example100

data.input number

input for this report.

Example100

data.payments number

payments for this report.

Example100

data.adjustments number

adjustments for this report.

Example100

data.closing number

closing for this report.

Example100

data.sources object[]

sources for this report.

ShowHide 11 properties

data.sources[].id string

Opaque identifier for this resource or reference.

ExampleConsulting services

data.sources[].sourceKind string

source kind within sources.

Allowed values: "invoice", "income", "expense", "payout", "asset"

Exampleinvoice

data.sources[].name string

Display name of the record.

ExampleNQD record

data.sources[].context string

context within sources.

ExampleConsulting services

data.sources[].net number

Total before tax and other modifiers.

Example100

data.sources[].tax number

Tax calculated from the workspace payable modifier.

Example100

data.sources[].gross number

Total after tax and other price modifiers.

Example100

data.sources[].currency string

Referenced currency with its opaque ID and ISO 4217 currency code.

ExampleConsulting services

data.sources[].link string

link within sources.

ExampleConsulting services

data.sources[].taxDirection string

tax direction within sources.

Allowed values: "output", "input"

Exampleoutput

data.sources[].sourceDate string

Calendar date in YYYY-MM-DD format for the reporting period.

ExampleConsulting services

data.paymentRows object[]

payment rows for this report.

ShowHide 8 properties

data.paymentRows[].id string

Opaque identifier for this resource or reference.

ExampleConsulting services

data.paymentRows[].sourceId string

ID of the related source.

Examplenull

data.paymentRows[].date string

Calendar date in YYYY-MM-DD format for the reporting period.

ExampleConsulting services

data.paymentRows[].amount number

Exact decimal string used for financial calculations. Do not round or convert it to a display number.

Example100

data.paymentRows[].nativeAmount number

Exact decimal string used for financial calculations. Do not round or convert it to a display number.

Example100

data.paymentRows[].nativeCurrency string

native currency within payment rows.

ExampleConsulting services

data.paymentRows[].direction string

direction within payment rows.

Allowed values: "payment", "refund"

Examplepayment

data.paymentRows[].link string

link within payment rows.

ExampleConsulting services

data.payableCards object[]

payable cards for this report.

ShowHide 11 properties

data.payableCards[].id string

Opaque identifier for this resource or reference.

ExampleConsulting services

data.payableCards[].vendorId string

ID of the related vendor.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1C

data.payableCards[].modifierId string

ID of the related modifier.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1J

data.payableCards[].purpose string

purpose within payable cards.

Allowed values: "custom", "vat", "zakah"

Examplecustom

data.payableCards[].recipient string

recipient within payable cards.

ExampleConsulting services

data.payableCards[].modifierName string

modifier name within payable cards.

ExampleConsulting services

data.payableCards[].opening number

opening within payable cards.

Example100

data.payableCards[].accrued number

accrued within payable cards.

Example100

data.payableCards[].paid number

paid within payable cards.

Example100

data.payableCards[].remaining number

remaining within payable cards.

Example0

data.payableCards[].vat object nullable

Value-added tax amount.

ShowHide 2 properties

data.payableCards[].vat.output number

output within vat.

Example100

data.payableCards[].vat.input number

input within vat.

Example100

data.recordedFactsOnly boolean

recorded facts only for this report.

Allowed values: true

Exampletrue

data.limitations string[]

limitations for this report.

Example1 item

data.generatedAt string

ISO 8601 timestamp for generated.

Example2026-01-15T12:00:00.000Z

Possible errors

400 Invalid request

Response headers

x-request-id string

Correlation identifier returned with every response for support and request tracing.

Example550e8400-e29b-41d4-a716-446655440000

error object

Error details returned for a failed request.

ShowHide 4 properties

error.code string

Stable machine-readable error or resource code.

Exampleinvalid_input

error.message string

Human-readable explanation of the result or error.

ExampleThe request could not be validated.

error.requestId string

Correlation identifier for support and request tracing.

Example550e8400-e29b-41d4-a716-446655440000

error.details object nullable

Additional structured details about the result or error.

ShowHide 1 property

error.details.issues object[]

Structured field issues returned when request validation fails.

ShowHide 3 properties

error.details.issues[].path string | number[]

Field path where the validation issue occurred.

One of: string alternative 1, number alternative 2

Example0 items

error.details.issues[].reason string

Machine-readable reason for the validation issue.

Allowed values: "expected_type", "required", "unexpected_property", "invalid_value", "invalid_json", "invalid_query", "unsupported_media_type", "body_too_large", "body_timeout", "conflicting_scope", "missing_header", "concurrency_required", "invalid_resource_id", "invalid_request"

Exampleinvalid_request

error.details.issues[].code string nullable

Stable machine-readable error or resource code.

Exampleinvalid_input

{
  "error": {
    "code": "invalid_input",
    "message": "The request could not be validated.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "details": {
      "issues": [
        {
          "path": [],
          "reason": "invalid_request"
        }
      ]
    }
  }
}

View raw OpenAPI operation

Use the machine-readable contract for client generation and payload validation.

Open OpenAPI contract ↗

curl --include --fail-with-body --request GET "${NQD_API_URL:-http://api.nqd.localhost:1335}/v1/reports/tax-control" \ -H "Authorization: Bearer $NQD_API_KEY" \ -H "Workspace-Id: $NQD_WORKSPACE_ID"

{ "data": { "currency": { "id": "01JQ2T5Y5Q3R8W9N6M4K2H7P1F", "code": "SAR", "conversion": { "from": "SAR", "to": "SAR", "rate": "1.00" }, "name": "Saudi Riyal" }, "period": { "start": "2026-01-01", "end": "2026-01-31" }, "fiscalStart": "2026-01-01", "filters": { "start": "2026-01-01", "end": "2026-01-31" }, "opening": 100, "output": 100, "input": 100, "payments": 100, "adjustments": 100, "closing": 100, "sources": [ { "id": "Consulting services", "sourceKind": "invoice", "name": "NQD record", "context": "Consulting services", "net": 100, "tax": 100, "gross": 100, "currency": "Consulting services", "link": "Consulting services", "taxDirection": "output", "sourceDate": "Consulting services" } ], "paymentRows": [ { "id": "Consulting services", "sourceId": null, "date": "Consulting services", "amount": 100, "nativeAmount": 100, "nativeCurrency": "Consulting services", "direction": "payment", "link": "Consulting services" } ], "payableCards": [ { "id": "Consulting services", "vendorId": "01JQ2T5Y5Q3R8W9N6M4K2H7P1C", "modifierId": "01JQ2T5Y5Q3R8W9N6M4K2H7P1J", "purpose": "custom", "recipient": "Consulting services", "modifierName": "Consulting services", "opening": 100, "accrued": 100, "paid": 100, "remaining": 0 } ], "recordedFactsOnly": true, "limitations": [ "Consulting services" ], "generatedAt": "2026-01-15T12:00:00.000Z" } }