---
title: "Validate VAT ID"
description: "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)

```bash
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 `vatId` and `countryCode` are currently stored on the organization — set them first with [Update Organization](/api/organization/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 `PATCH` to the organization must not fail or hang on it. Saving a new `vatId` or `countryCode` resets `vatIdStatus` to `unverified`; 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 `vatIdStatus` is exactly `valid`. 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](/api/organization/update-organization). A customer-scoped API token cannot call this endpoint, even with `admin`-level role.

## Response

```json
{
  "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 in
- `400 Invalid Organization identifier` when `:organizationPublicId` is neither a legacy integer id nor a valid UUID public identifier
- `403 Forbidden` (`data.code: forbidden`) when you do not have write access to the organization
- `403 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 session
- `404 Organization not found` (no `data.code`) when `:organizationPublicId` does not resolve to an existing organization
- `404 Organization not found` (`data.code: organizationNotFound`) when the organization is deleted in the narrow window between resolving `:organizationPublicId` and the endpoint's own lookup — a race, not the typical not-found response
- `422 No VAT ID stored for this organization` (`data.code: vatIdMissing`) when the organization has no `vatId` set — store one first with [Update Organization](/api/organization/update-organization)
- `409 The VAT ID or country changed while validation was in flight` (`data.code: vatIdChangedDuringValidation`) when `vatId` or `countryCode` was 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](/api/error-codes-and-known-pitfalls) for the full list.