Validate VAT ID
Validates the organization's stored VAT identification number against the EU VIES register and persists the verdict. Only a valid VAT ID from another EU member state qualifies the organization for reverse-charge invoicing under AGB § 10.2.
POST /api/organizations/:organizationPublicId/vat-id/validate
Example (cURL)
BASE_URL="https://uptimeify.io"
TOKEN="<your-api-token>"
ORG_ID="<organization-public-id>"
curl -X POST "$BASE_URL/api/organizations/$ORG_ID/vat-id/validate" \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"Notes:
- This endpoint takes no request body. It validates whatever
vatIdandcountryCodeare currently stored on the organization — set them first with Update Organization if needed. - Validation is a deliberate, explicit action, not a side effect of saving the organization. The EU VIES service is slow and occasionally unavailable per member state, so a
PATCHto the organization must not fail or hang on it. Saving a newvatIdorcountryCoderesetsvatIdStatustounverified; calling this endpoint is what turns it back into a verdict. - Reverse charge under AGB § 10.2 applies only when the organization's country is an EU member state other than Germany, a VAT ID is stored, and
vatIdStatusis exactlyvalid. Every other combination bills at the standard rate. - Requires organization write access (organization admin or global admin) from an unrestricted session or token — the same authorization as Update Organization. A customer-scoped API token cannot call this endpoint, even with
admin-level role.
Response
{
"vatIdStatus": "valid",
"vatIdValidatedAt": "2026-07-30T09:15:00.000Z",
"vatIdValidationNote": null,
"taxTreatment": "reverse_charge"
}vatIdStatus is one of:
| Value | Meaning |
|---|---|
unverified | Not yet validated, or the stored vatId/countryCode changed since the last validation (see above). Never returned by this endpoint — it is the pre-validation default. |
valid | VIES confirmed the VAT ID. The only status that grants reverse charge. |
invalid | VIES rejected the VAT ID, its country prefix does not belong to an EU VAT country, or it does not match the organization's stored countryCode. |
unavailable | VIES could not give a verdict — a timeout, an HTTP error, or a member state's registry reporting itself down (MS_UNAVAILABLE). Deliberately distinct from invalid: an outage must never be read as "the VAT ID is wrong," since that would strip a legitimate customer of reverse charge. Retry later. |
taxTreatment reflects the resulting billing treatment and is one of standard or reverse_charge.
vatIdValidationNote is a short, human-readable reason (e.g. why a check came back invalid or unavailable); null on a valid result.
Common errors
401 Unauthorized(data.code: unauthorized) when you are not logged in400 Invalid Organization identifierwhen:organizationPublicIdis neither a legacy integer id nor a valid UUID public identifier403 Forbidden(data.code: forbidden) when you do not have write access to the organization403 Forbidden(data.code: customerScopedTokenForbidden) when called with a customer-scoped API token; this is an organization-wide action and requires an organization-scoped token or a session404 Organization not found(nodata.code) when:organizationPublicIddoes not resolve to an existing organization404 Organization not found(data.code: organizationNotFound) when the organization is deleted in the narrow window between resolving:organizationPublicIdand the endpoint's own lookup — a race, not the typical not-found response422 No VAT ID stored for this organization(data.code: vatIdMissing) when the organization has novatIdset — store one first with Update Organization409 The VAT ID or country changed while validation was in flight(data.code: vatIdChangedDuringValidation) whenvatIdorcountryCodewas edited concurrently while VIES was being queried — the in-flight verdict is discarded rather than written to stale data. Safe to retry.
See Error Codes for the full list.
Cancel Scheduled Quota Change
Cancels a quota reduction that was scheduled for the end of the current billing period, so the organization keeps its current plan. Answers cancelled:false — not 404 — when nothing is scheduled.
Upsert Package Config
Creates a new package config (by :packageType) or updates an existing one. packageType is a free-form identifier chosen by the organization, and customer endpoints can later reference that same key.