API reference / Business / KYB

TIN lookup

Dealer details for an 11-digit state TIN.

POST/v1/business/tin
Authentication
Bearer token
Scope
kyc:verify

Before you integrate

  • result is a list, not an object; the field names above are for each item in it.

Request body

FieldTypeRequiredDescription
tinstringYesEleven-digit state TIN. Spaces and hyphens are ignored.

Sample code

Set your key in the GRAPPI_API_KEY environment variable. Sample values are placeholders.

curl -sS -X POST 'https://grappi.ai/v1/business/tin' \
  -H "Authorization: Bearer $GRAPPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tin": "27290123456"
}'

Sample response

{
  "request_id": "req_01HZY3K8M2",
  "result": [
    {
      "dealer": "EXAMPLE TRADERS",
      "owner_name": "ASHA RAO",
      "pan": "ABCDE1234F",
      "status": "Active",
      "registration_status": "Registered",
      "cst_status": "Registered",
      "reg_date": "2015-04-01",
      "cancel_date": "",
      "address": "12 Example Lane, Pune, Maharashtra, 411001",
      "split_address": {
        "district": [
          "Pune"
        ],
        "state": [
          "Maharashtra"
        ],
        "city": [
          "Pune"
        ],
        "pincode": "411001",
        "country": [
          "India"
        ],
        "address_line": "12 Example Lane"
      }
    }
  ]
}

Response fields

FieldTypeDescription
[]arrayOne entry per dealer registration found for the TIN.
[].dealerstringName of the dealer.
[].owner_namestringName of the owner.
[].panstringPAN on the registration.
[].statusstringStatus of the registration.
[].registration_statusstringRegistration status.
[].cst_statusstringCentral sales tax registration status.
[].reg_datestringDate of registration.
[].cancel_datestringDate of cancellation, if cancelled.
[].addressstringAddress of the dealer.
[].split_addressobjectThe dealer's address broken into parts.
[].split_address.districtarrayDistrict name, as a list.
[].split_address.statearrayState name, as a list.
[].split_address.cityarrayCity name, as a list.
[].split_address.pincodestringSix-digit pincode.
[].split_address.countryarrayCountry name, as a list.
[].split_address.address_linestringStreet-level part of the address.

Errors

Every failure has the same shape. A call that fails on our side or at the data source is refunded to your wallet; a "no record found" answer is charged. See the error reference.