Validation outcomes
Every response carries a result
object. Its status is the single
source of truth for what we concluded — five mutually exclusive values.
Branch on result.status;
everything else in the response is supporting detail.
Don't branch on validation.overall.isValid alone.
It is true for VALID,
UNVERIFIED and INDETERMINATE alike, so a
format-only pass looks identical to a registry-confirmed one.
result.status exists to remove that ambiguity.
| result.status | result.reason | HTTP | Meaning and what to do |
|---|---|---|---|
| VALID | null | 200 | Format passed and a government registry confirmed the entity. Accept it. |
| INVALID | INVALID_FORMAT INVALID_CHECKSUM NOT_REGISTERED |
200 | A definitive negative: the structure or check digit is wrong, or the registry holds no matching record. Reject it. |
| UNVERIFIED | NO_SOURCE_AVAILABLE | 200 | The country exposes no queryable registry, so only the format was checked. A pass is not proof the business exists or is registered. |
| INDETERMINATE | SOURCE_UNAVAILABLE | 200 | A registry was temporarily unreachable, so the result couldn't be confirmed. Retry later — don't treat this as invalid. The only outcome with retryable: true. |
| UNSUPPORTED | COUNTRY_NOT_SUPPORTED | 422 | We don't validate this country or number type yet. Nothing was checked. |
The legacy errors[] array is
deprecated. It now simply mirrors result
(and is absent for VALID and UNVERIFIED);
new integrations should read result.
Example response
{
"referenceId": "req_abc123def456",
"countryCode": "RO",
"requestDate": "2026-08-15T10:21:14.268Z",
"tin": "42056996",
"result": {
"status": "VALID",
"reason": null,
"message": "Confirmed against the official registry.",
"retryable": false
},
"validation": {
"format": { "isValid": true, "attempted": true },
"source": { "isValid": true, "attempted": true },
"overall": { "isValid": true, "attempted": true, "validationMethod": "SOURCE_DATABASE" }
},
"tinInfo": { "label": "TVA", "name": "Taxa pe valoarea adăugată", "formattedTin": "RO42056996" },
"entity": { "name": "EXAMPLE SRL", "status": "Active" },
"metadata": { "processingTime": 663, "version": "2.0" }
}