Trovacast

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.

Fill it in and submit it

Save the business details
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, null clears one. The answer is the verification below, with its id, its version and the documents requirements still lists.
  • Upload each document with POST /v1/verifications/{verificationId}/documents as multipart/form-data: type (a document type, such as pan_card) and file — a PDF, JPEG or PNG of at most 10 MB, whose bytes must match the type they claim.
  • Submit with POST /v1/verifications/{verificationId}/submit and the version you read: 422 VERIFICATION_INCOMPLETE lists what is still missing, 409 means it changed since you read it. A submitted verification can no longer be edited until the review asks for more.
Submit it for review
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
}'
Read the verification, with what a 140-series number would need
curl 'https://api.trovacast.com/v1/verifications?numberType=promotional_140' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
200 — the reviewer asked for changes (json)
{
  "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

  • status moves not_started → draft → submitted → in_review → approved, or to needs_info (fix what reviewNote says and submit again) or rejected. An approval the platform withdraws becomes expired.
  • verified is what the gate reads: verification is not required for your organization, or it is approved. While it is false, live keys answer 403 LIVE_KEYS_REQUIRE_VERIFICATION.
  • requirements.documents lists what your country and business type must give, and whether a document of an accepted type is on file. Pass numberType to 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.
  • documents lists what you uploaded: its type, whether the file is still stored, its size and date — never its name or a link to it.
  • identifiers shows 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

CodeStatusMeaning and what to do
LIVE_KEYS_REQUIRE_VERIFICATION403The 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_REQUIRED403This 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_PARENT409This 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_REQUIRED403The 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.