DEVELOPER GUIDE

Your first ApiVect request.

Create your account, confirm your email, choose a password and enroll an authenticator. Save your recovery codes. Then create a server-side API key in the dashboard. Free allowances cover all three APIs without a payment card.

1. Keep your key on your server

Set APIVECT_API_KEY through your environment or secret manager. Never embed it in browser JavaScript, source control or a public example. Each product requires the corresponding key scope and an active product entitlement.

2. Validate an invoice

Download the official positive Peppol example as valid-invoice.xml. It contains synthetic example data and retains its upstream licence notice.

curl --request POST https://api.apivect.com/v1/invoices/validate \
  --header "Authorization: Bearer $APIVECT_API_KEY" \
  --header "Content-Type: application/xml" \
  --header "Idempotency-Key: first-invoice-example-001" \
  --data-binary @valid-invoice.xml

A successful operation returns HTTP 200 with valid, the detected profile, rule-set version, validation stages and findings. An invalid invoice can also return HTTP 200: inspect valid. Invalid business content consumes one validation unit when the validation operation completes.

{
  "valid": false,
  "profile": "peppol-bis-billing-3",
  "documentType": "Invoice",
  "ruleset": "peppol-3.0.21_cen-1.3.16_20260911",
  "stages": ["ubl-2.1-xsd", "en16931-1.3.16", "peppol-bis-billing-3.0.21"],
  "findings": [{ "code": "BR-CO-10", "severity": "error" }],
  "truncated": false
}

For reusable clients and a loopback stub test, see the Python and Node.js invoice validation examples.

3. Retry safely

Send the exact same body, profile and idempotency key again within 24 hours. The response includes Idempotent-Replayed: true and consumes no additional unit. A key used with different input returns 409. An expired key or failed operation returns a specific retry instruction; do not blindly repeat a request with a new key after an uncertain network result.

4. Check VAT

curl --request POST https://api.apivect.com/v1/vat/validate \
  --header "Authorization: Bearer $APIVECT_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: first-vat-example-0001" \
  --data '{"countryCode":"DK","vatNumber":"12345678"}'

This number is illustrative. Results distinguish valid, invalid and unknown. Unknown provider results consume zero units. Cached conclusive results count as a new check when sent with a new idempotency key. Check the provider date and cached flag.

5. Inspect a domain

curl --request POST https://api.apivect.com/v1/domains/audit \
  --header "Authorization: Bearer $APIVECT_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: first-domain-example-001" \
  --data '{"domain":"apivect.com","dkimSelectors":[]}'

Supply known DKIM selectors when available. When omitted, only the default selector is checked. Missing optional policies use not_configured. Each check returns pass, warning, fail, unknown, not_tested or not_configured and states its coverage. This API inspects direct-domain configuration; it does not evaluate an actual email message or provide scheduled monitoring. SPF sender evaluation, DMARC organizational-domain discovery, BIMI logos/certificates and SMTP delivery are outside current coverage.

Handle limits and failures

• 401/403: check your key and scopes.
• 402: the product entitlement is inactive.
• 409: follow the idempotency error code.
• 429: read the error code; a quota or spending cap needs a plan/limit change, while a rate limit may include Retry-After.
• 503: the service or a dependency could not complete the operation. There is no charge for a failed operation; first retry the same idempotency key to resolve uncertainty.

Free access is limited and has no automatic charge or overage. Open the interactive API reference for request/response schemas and the price catalogue for product allowances.

Document Render: private PDF jobs

1. Choose a Document Render plan and create a dedicated documents:render API key. Existing keys do not gain this scope.
2. Send supported HTML or a JSON report to POST /v1/documents/render with Content-Type: text/html or application/json and a 16–100-character Idempotency-Key.
3. The response is a private job. Poll GET /v1/documents/jobs/{id}; download a succeeded PDF through GET /v1/documents/jobs/{id}/file with the same workspace scope.
4. Use POST /v1/documents/jobs/{id}/cancel before completion, or POST /v1/documents/jobs/{id}/remove to remove retained output.

The parser fixes the page format from the submitted supported input. A job has a 90-second deadline. HTML/JSON input is limited to 1 MiB; output is limited to 4 MiB and 50 pages. The renderer permits no JavaScript or remote assets. A successful PDF consumes one operation; rejected, cancelled and failed jobs do not. Exact retries replay the same job without extending its one-hour output expiry or regenerating removed/expired output. This is PDF rendering only: it does not perform OCR or create Factur-X documents.

Domain Watch: website and API

1. Choose a Watch plan in Billing. Payment confirmation grants domain slots.
2. Open Domain Watch, save a domain and publish the exact DNS TXT record or HTTPS file shown. Keep it published.
3. Verify ownership and explicitly enable scheduled monitoring. Add known DKIM selectors from your mail provider.
4. Choose email alerts at your own verified account address. Use maintenance to pause alerts during planned work.
5. Read incident history or download PDF, CSV or JSON. Exports use saved evidence and never start another check.

For software integrations, create a separate Watch read or Watch manage key in your workspace. Existing API keys do not gain Watch scopes. Use Bearer authorization for GET /v1/watch/domains, GET /v1/watch/domains/{id}/events and GET /v1/watch/domains/{id}/report?format=json. Management also permits creation, ownership verification, scheduling, maintenance and removal. Read the exact request schemas in the API reference.

Watch is a fixed monthly capacity subscription. Paused/unverified setups occupy slots; run-now is limited to once/hour/domain. A downgrade preserves the oldest setups within the new slot allowance and pauses extras. Unavailable provider/local-probe data remains inconclusive. Compare Watch plans →

Invoice Tools: one allowance for website and API

1. Choose a Tools subscription in Billing, then open Invoice Tools in your workspace.
2. Download the synthetic JSON example or upload a supported UBL Invoice/CreditNote. Choose JSON → UBL, UBL → JSON or PDF reading copy.
3. Confirm one operation and one-hour private output storage. Review the validation result and download the output before expiry.

For software, create an explicit invoice:convert and/or invoice:render key. Existing validation keys gain no permissions. Send JSON to POST /v1/invoices/from-json with application/json, or UTF-8 XML to POST /v1/invoices/to-json or POST /v1/invoices/render with application/xml. Each request needs a 16–100-character Idempotency-Key. The API reference includes the synthetic JSON example; authenticated schemas are under /v1/invoices/tools/schema/Invoice and /v1/invoices/tools/schema/CreditNote.

The response is a small receipt with validation and artifact. Download from the same API origin using artifact.downloadPath and your matching scoped key. It is not a public link. Reuse the same idempotency key and exact bytes after an uncertain network result. Replay restores the original receipt for up to 24 hours without extra usage or renewed file retention; removed/expired output is not regenerated.

Amounts stay exact strings. Unsupported fields, attachments, signatures and extensions are rejected without a partial output. Supported business-invalid output consumes one operation and preserves the original values; conversion never repairs it silently. PDF supports the embedded Latin/Greek/Cyrillic font coverage and rejects unsupported scripts. Structured conversion preserves Unicode. There is no free Tools trial, rollover or overage. Compare Tools plans →

Website Audit: verified websites, shared page allowance

1. Choose an Audit plan in Billing, then add the exact public HTTPS root URL in Website Audit. Each hostname, including www, is a separate site.
2. Publish the exact DNS TXT value or plain-text verification file shown. Verify ownership and keep this proof published.
3. Choose a maximum URL budget, sitemap discovery and consent to usage and encrypted metadata retention. Start the scan, then refresh its private progress report.
4. Filter warnings, inspect findings and suggested actions, compare completed scans of the same site or export labelled windows of 25 URL results as PDF, CSV or JSON.

One completed HTTP observation uses one page unit, including 404 responses and a bounded redirect chain. Technical failures, robots-denied pages, reading reports and downloads use none. A scan can stop at quota, technical capacity or its 24-hour deadline. Queue completion does not prove every website page was discovered or that the site passed all SEO checks.

Business and Agency can explicitly enable one monthly scan per site, on day 1–28 from 06:00 UTC. Temporary failures retry within a 24-hour start window; missed starts never accumulate. Pause stops future starts; cancel a queued scan separately. Current access, ownership, plan limits and the same shared page allowance apply to every run. An upgrade does not silently extend previously agreed retention.

For integrations, create an explicit Website Audit read, scan or manage key in the workspace. Use GET/POST /v1/sites, POST /v1/sites/{id}/verify and POST /v1/sites/audits. Scan creation needs a 16–100-character Idempotency-Key, current siteRevision, maximumPages, acceptUsage and acceptRetention. Read /v1/sites/audits/{id}, /pages, /issues, /compare?previous={id} and /export?format=json. Manage monthly settings at /v1/sites/{id}/schedule. Existing keys do not gain these scopes. Exact contracts and bounded pagination are in the API reference.

Retained scan capacity is 1 GiB for Starter, 3 GiB for Business and 12 GiB for Agency, with at most 1,000 retained scans. A scan reserves space for its selected URL budget. Export/remove old reports or select fewer URLs when capacity is full. Scans respect robots rules, a shared host delay of at least one second and public-address checks before every hop. Cross-host redirects are excluded. No browser JavaScript, authenticated content, private endpoints, vulnerability exploitation, keyword rankings or search-index verification is included. Raw HTML is never saved. Compare Audit plans →