Documentation/Tax & Compliance API/Validate tax context

Contract 1.0.0:tax.context.validate

Validate tax context

Validate and normalize cross-border tax context before a decision is created.

POST/v1/tax/context/validate

Overview

Validate and normalize cross-border tax context before a decision is created.

Use cases

Use `tax.context.validate` when you need validate tax context through the provider-neutral QuoAPI contract.

Authentication

Send a QuoAPI API key as `Authorization: Bearer gi_test_...` or an approved live key. Test and live environments are isolated.

Quick start

Send `POST` to `/v1/tax/context/validate`. Start in the test environment and keep the request ID for support and tracing.

Account & onboarding

No separate upstream/provider user account is required. Your QuoAPI account and QuoAPI API key remain the customer-facing identity. Provider/network onboarding: No separate Dynafis user account is required. QuoAPI authenticates server-to-server; stateful decisions use a JIT technical tenant namespace for isolation/audit only.. A provider-side JIT tenant may be created only as a technical isolation/audit namespace; it is not a user account or customer login.

Request fields

- `supplier_country` — string, required. - `customer_country` — string, required. - `supply_type` — string, optional. - `customer_type` — string, optional. - `customer_vat_id` — string, optional. - `country` — string, optional. Optional ISO 3166-1 alpha-2 routing context. - `currency` — string, optional. Optional ISO 4217 commercial context.

Response fields

The response envelope contains `data` validated against the canonical response schema and `request_id`. Response schema type: `object`.

Errors

Errors use `error.code`, `error.message`, `error.request_id` and structured `error.details`. Provider names, credentials, upstream URLs and raw upstream errors are not part of the public contract.

Webhooks

This capability does not emit a public webhook event.

Rate limits

Rate limits are enforced by API key, organization, plan, capability and environment. Responses include standard rate-limit headers and `Retry-After` when applicable.

Idempotency

Retryable write operations support QuoAPI idempotency semantics so a replay does not create duplicate billing or side effects.

Sandbox

The Playground uses deterministic safe sandbox behavior. Anonymous demos cannot perform purchases, registrations, messages or destructive actions.

Pricing

Usage is measured in `request` and priced in `request` units.

Async behavior

The operation returns through the normal request lifecycle.

Contract version

`1.0.0:tax.context.validate` — schema checksum `55b9082d50c987c65683f5b794c5a19bfda9bec609ea7eb6aced6a13e576fa68`.

Supported input formats

- `Canonical tax-context JSON; ISO 3166-1 alpha-2 countries, canonical supply/customer types and optional VAT identifiers`

Supported output formats

- `Canonical validation JSON containing valid/errors/warnings and normalized tax context`

Limitations & authority

- Validation checks input/context consistency; it is not tax filing or authority submission.

Request schema

{
  "additionalProperties": false,
  "properties": {
    "country": {
      "description": "Optional ISO 3166-1 alpha-2 routing context.",
      "pattern": "^[A-Z]{2}$",
      "type": "string",
      "x-quoapi-hidden": true,
      "x-quoapi-widget": "country"
    },
    "currency": {
      "description": "Optional ISO 4217 commercial context.",
      "pattern": "^[A-Z]{3}$",
      "type": "string",
      "x-quoapi-hidden": true,
      "x-quoapi-widget": "currency"
    },
    "customer_country": {
      "default": "FR",
      "pattern": "^[A-Z]{2}$",
      "title": "Customer country",
      "type": "string",
      "x-quoapi-format": "iso-3166-1-alpha-2",
      "x-quoapi-widget": "country"
    },
    "customer_type": {
      "default": "business",
      "enum": [
        "business",
        "consumer"
      ],
      "title": "Customer type",
      "type": "string",
      "x-quoapi-widget": "select"
    },
    "customer_vat_id": {
      "title": "Customer VAT ID",
      "type": "string",
      "x-quoapi-widget": "text"
    },
    "supplier_country": {
      "default": "DE",
      "pattern": "^[A-Z]{2}$",
      "title": "Supplier country",
      "type": "string",
      "x-quoapi-format": "iso-3166-1-alpha-2",
      "x-quoapi-widget": "country"
    },
    "supply_type": {
      "default": "general_service",
      "enum": [
        "general_service",
        "goods",
        "digital_service"
      ],
      "title": "Supply type",
      "type": "string",
      "x-quoapi-widget": "select"
    }
  },
  "required": [
    "supplier_country",
    "customer_country"
  ],
  "type": "object"
}

Response schema

{
  "additionalProperties": true,
  "description": "Canonical QuoAPI tax/compliance response.",
  "type": "object"
}

Example request

{
  "customer_country": "FR",
  "customer_type": "business",
  "customer_vat_id": "demo",
  "supplier_country": "DE",
  "supply_type": "general_service"
}

Try in Playground

Code examples

curl

curl -X POST "https://api.quoapi.com/v1/tax/context/validate" \
  -H "Authorization: Bearer $QUOAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"supplier_country\": \"DE\", \"customer_country\": \"FR\", \"supply_type\": \"general_service\", \"customer_type\": \"business\", \"customer_vat_id\": \"demo\"}"

javascript

const response = await fetch("https://api.quoapi.com/v1/tax/context/validate", {
  method: "POST",
  headers: {Authorization: `Bearer ${process.env.QUOAPI_API_KEY}`, "Content-Type": "application/json"},
  body: JSON.stringify({"supplier_country": "DE", "customer_country": "FR", "supply_type": "general_service", "customer_type": "business", "customer_vat_id": "demo"})
});
const data = await response.json();

typescript

const response = await fetch("https://api.quoapi.com/v1/tax/context/validate", {
  method: "POST",
  headers: {Authorization: `Bearer ${process.env.QUOAPI_API_KEY}`, "Content-Type": "application/json"},
  body: JSON.stringify({"supplier_country": "DE", "customer_country": "FR", "supply_type": "general_service", "customer_type": "business", "customer_vat_id": "demo"})
});
const data = await response.json();

php

<?php
$ch = curl_init("https://api.quoapi.com/v1/tax/context/validate");
curl_setopt_array($ch, [CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => ["Authorization: Bearer ".getenv("QUOAPI_API_KEY"), "Content-Type: application/json"], CURLOPT_POSTFIELDS => "{\"supplier_country\": \"DE\", \"customer_country\": \"FR\", \"supply_type\": \"general_service\", \"customer_type\": \"business\", \"customer_vat_id\": \"demo\"}", CURLOPT_RETURNTRANSFER => true]);
echo curl_exec($ch);

python

import os, requests
response = requests.request("POST", "https://api.quoapi.com/v1/tax/context/validate", headers={"Authorization": "Bearer " + os.environ["QUOAPI_API_KEY"]}, json={'supplier_country': 'DE', 'customer_country': 'FR', 'supply_type': 'general_service', 'customer_type': 'business', 'customer_vat_id': 'demo'})
print(response.json())

csharp

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("QUOAPI_API_KEY"));
var response = await client.PostAsJsonAsync("https://api.quoapi.com/v1/tax/context/validate", {"supplier_country": "DE", "customer_country": "FR", "supply_type": "general_service", "customer_type": "business", "customer_vat_id": "demo"});

java

var request = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://api.quoapi.com/v1/tax/context/validate"))
  .header("Authorization", "Bearer " + System.getenv("QUOAPI_API_KEY"))
  .header("Content-Type", "application/json")
  .method("POST", java.net.http.HttpRequest.BodyPublishers.ofString("{\"supplier_country\": \"DE\", \"customer_country\": \"FR\", \"supply_type\": \"general_service\", \"customer_type\": \"business\", \"customer_vat_id\": \"demo\"}")).build();

payload := strings.NewReader("{\"supplier_country\": \"DE\", \"customer_country\": \"FR\", \"supply_type\": \"general_service\", \"customer_type\": \"business\", \"customer_vat_id\": \"demo\"}")
req, _ := http.NewRequest("POST", "https://api.quoapi.com/v1/tax/context/validate", payload)
req.Header.Set("Authorization", "Bearer "+os.Getenv("QUOAPI_API_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)