Platform
Business verification
Fill in, document and submit your business verification (KYC) through the API, and follow its review: its status, the documents still required, and identifiers shown only by their last four characters.
Organizations that sign up on their own verify their business before live keys, numbers, live sends and live calls work. Fill it in and upload its documents in the console (Settings → Business verification) or through the API; our team reviews it. A key with verifications:read reads where it stands, and one with verifications:write fills it in and submits it — test keys too: a project that holds only test keys gets verified this way. It is your organization’s real verification, not test data, and every change is audited against the key.
- GET
/v1/verificationsRetrieves the business verification: its status, the documents still required and identifiers as their last four characters - POST
/v1/verificationsFills in (or changes) the business details of the verification - POST
/v1/verifications/{verificationId}/documentsUploads a verification document (PDF, JPEG or PNG, at most 10 MB) - POST
/v1/verifications/{verificationId}/submitSends the verification for review
Fill it in and submit it
curl -X POST 'https://api.trovacast.com/v1/verifications' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"legalName": "Acme Widgets Private Limited",
"entityType": "private_limited",
"country": "IN",
"addressLine1": "1 MG Road",
"city": "Bengaluru",
"postalCode": "560001",
"gstin": "29ABCDE1234F1Z5",
"pan": "ABCDE1234F",
"signatoryName": "Asha Rao",
"signatoryEmail": "asha@acme.example",
"signatoryPhone": "+919876543210"
}'- The first save creates the draft; absent fields stay as they are,
nullclears one. The answer is the verification below, with itsid, itsversionand the documentsrequirementsstill lists. - Upload each document with
POST /v1/verifications/{verificationId}/documentsasmultipart/form-data:type(a document type, such aspan_card) andfile— a PDF, JPEG or PNG of at most 10 MB, whose bytes must match the type they claim. - Submit with
POST /v1/verifications/{verificationId}/submitand theversionyou read:422 VERIFICATION_INCOMPLETElists what is still missing,409means it changed since you read it. A submitted verification can no longer be edited until the review asks for more.
curl -X POST 'https://api.trovacast.com/v1/verifications/5f0c2a9e-0d4b-4c55-9b1e-2f6a7c8d9e01/submit' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"version": 3
}'curl 'https://api.trovacast.com/v1/verifications?numberType=promotional_140' \
-H "Authorization: Bearer $TROVACAST_API_KEY"{
"object": "verification",
"status": "needs_info",
"required": true,
"verified": false,
"verifiedAt": null,
"business": {
"legalName": "Acme Widgets Private Limited",
"entityType": "private_limited",
"country": "IN"
},
"identifiers": {
"gstinLast4": "F1Z5",
"panLast4": "234F",
"cinLast4": "3456",
"signatoryPhoneLast4": "3210"
},
"requirements": {
"numberType": "promotional_140",
"documents": [
{
"label": "Certificate of incorporation or registration",
"anyOf": [
"incorporation_certificate"
],
"satisfied": true
},
{
"label": "Authorisation letter or board resolution naming the authorised signatory",
"anyOf": [
"authorisation_letter"
],
"satisfied": false
},
{
"label": "Letter of authority, on the business letterhead, for the numbers it will use",
"anyOf": [
"number_loa"
],
"satisfied": false
}
]
},
"documents": [
{
"object": "verification_document",
"id": "9c2f7e1a-3b4d-4e5f-8a6b-7c8d9e0f1a2b",
"type": "incorporation_certificate",
"status": "stored",
"mimeType": "application/pdf",
"sizeBytes": 182044,
"createdAt": "2026-11-03T08:15:00.000Z"
}
],
"reviewNote": "The authorisation letter is unsigned"
}Reading it
statusmovesnot_started→draft→submitted→in_review→approved, or toneeds_info(fix whatreviewNotesays and submit again) orrejected. An approval the platform withdraws becomesexpired.verifiedis what the gate reads: verification is not required for your organization, or it is approved. While it isfalse, live keys answer403LIVE_KEYS_REQUIRE_VERIFICATION.requirements.documentslists what your country and business type must give, and whether a document of an accepted type is on file. PassnumberTypeto see what a number type adds — a letter of authority for 140-series, 160-series and toll-free numbers in India — before you order one.documentslists what you uploaded: its type, whether the file is still stored, its size and date — never its name or a link to it.identifiersshows the GSTIN, PAN, company number and the signatory’s phone by their last four characters only. The full values, the signatory’s name and email and the address stay with the review.
Errors
| Code | Status | Meaning and what to do |
|---|---|---|
LIVE_KEYS_REQUIRE_VERIFICATION | 403 | The organization signed up on its own and its business verification is not approved yet, so only test-mode keys (tc_test_…) work. See Authentication.What to do: Use a test key until the verification is approved: fill it in and submit it under Settings → Business verification, or over the API with a test key. See Business verification. |
VERIFICATION_DOCUMENTS_REQUIRED | 403 | This number type needs a document that is not on file and accepted yet — a letter of authority for 140-series, 160-series or toll-free numbers. Every organization needs it, including one an integration provisioned without a business verification.What to do: Upload the letter of authority (POST /v1/verifications/{verificationId}/documents with type number_loa, or Settings → Business verification); once the platform accepts it, activate the number again. |
VERIFICATION_INHERITED_FROM_PARENT | 409 | This subaccount is the same business as its parent, so its business verification is the parent's — approved and revoked with it. It does not fill in or submit its own.What to do: Do not retry: complete the parent organization's verification instead, and read this one's state with GET /v1/verifications. |
VERIFICATION_REQUIRED | 403 | The feature (feature names it: numbers, live keys, live messaging, live calls or subaccounts) needs an approved business verification.What to do: Complete and submit the business verification (Settings → Business verification, or POST /v1/verifications then POST /v1/verifications/{verificationId}/submit), and retry once it is approved. See Business verification. |