{
"valid": false,
"errors": [
{ "field": "taxId", "code": "compliance_tax_id_format", "message": "taxId format is invalid for US", "legacy": "compliance_tax_id_format:US" }
],
"readyForVerification": false
}
{
"valid": true,
"errors": [],
"readyForVerification": true
}
Business Verification (v2)
Validate Business Profile
Dry-run: check business-profile fields for field-level errors without saving.
POST
/
v2
/
business-profiles
/
validate
{
"valid": false,
"errors": [
{ "field": "taxId", "code": "compliance_tax_id_format", "message": "taxId format is invalid for US", "legacy": "compliance_tax_id_format:US" }
],
"readyForVerification": false
}
{
"valid": true,
"errors": [],
"readyForVerification": true
}
Validates business-profile fields and returns field-level errors without creating or changing anything. Use it to drive an inline correction UI before you create or update a profile. Works with any key (including sandbox).
Checks performed: country allowlist, tax-id format for the country, state-code coercion, and the US TIN-match legal-name length cap.
Body Parameters
Accepts the same fields as create; all are optional here — only the fields you send are validated.Response Fields
boolean
true when no field errors were found.array
Field-level errors. Each has
field (the offending camelCase field), code, a human message, and legacy (a backward-compatible string: the code, plus : and the offending value when there is one — e.g. compliance_tax_id_format:US, but just identifier_type_required when there is none).boolean
true when the payload is valid and carries every field KYB needs (name, companyLegalName, taxId, addressCountry, businessContactFirstName, businessContactLastName).Examples
cURL
curl -X POST "https://api.tracklysms.com/api/v2/business-profiles/validate" \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{ "name": "Acme", "addressCountry": "US", "taxId": "not-an-ein" }'
Python
import requests
resp = requests.post(
"https://api.tracklysms.com/api/v2/business-profiles/validate",
headers={"X-Api-Key": "trk_your_api_key_here"},
json={"name": "Acme", "addressCountry": "US", "taxId": "not-an-ein"},
)
print(resp.json()["errors"])
{
"valid": false,
"errors": [
{ "field": "taxId", "code": "compliance_tax_id_format", "message": "taxId format is invalid for US", "legacy": "compliance_tax_id_format:US" }
],
"readyForVerification": false
}
{
"valid": true,
"errors": [],
"readyForVerification": true
}
Error Codes
Field errors are returned inline inerrors (HTTP 200), not as HTTP error statuses. Common code values:
| Code | Field | Meaning |
|---|---|---|
address_country_invalid | addressCountry | Not a recognized / supported country. |
compliance_tax_id_format | taxId | Tax-id format is wrong for the country. |
address_state_invalid | addressState | Not a valid state/region for the country. |
compliance_legal_name_too_long | companyLegalName | Exceeds the 40-char US TIN-match cap. |
Next Steps
Create the profile
Once validation is clean.
Lifecycle overview
How verification proceeds.