Response structure

All GET and DELETE request parameters goes either as path parameter or as query parameters, and POST parameters as (Content-Type: application/json) body, responses from the API are always JSON. The responses may be Gzipped.

SUCCESSFUL REQUEST

All responses from the API server are JSON with the content-type application/json. A successful 200 OK response always has a JSON response body except for DELETE request. The response contains the full payload. Every API response contains entities that are shared across different endpoints. There are some common attributes for an entity.

Property

Type

Description

@entity

string

Indicates the type of entity

id

hex(32)

Unique identifier of the entity

EXAMPLE OBJECT

HTTP/1.1 200 OK
Content-Type: application/json
{
"@entity": "object"
"id": "51A565413C35B5565718756153019872"
}

FAILED REQUEST

We use conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with our servers. A failure response is preceded by the corresponding 40x or 50x HTTP header. The code key in the response envelope contains the REST status code. The message key contains a textual description of the error.

HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"code": 403,
"message": "Access denied"
}

DATA TYPES

Values in JSON responses are of types string, bigdecimal, date, or boolean. All date are in DD/MM/YYYY format set under the Indian timezone (IST) (Local time as in Asia/Kolkata)

Common Entities

Common entities reused across APIs such as an address, contact, bank account, etc. are described below.

ADDRESS ENTITY

The various properties are explained below:

Param

Type

Description

area

string

Area

city

string

City

country

string

Country

district

string

District

full_address

string

Full address

id

hex(32)

Unique address identifier

is_primary

boolean

Whether it is the primary address or not

postal_code

string

Postal code

street

string

Street

type

string

Type of address. Possible values: Home, Work, Shipping and Billing

CONTACT ENTITY

The various properties are explained below:

Param

Type

Description

email

string

Email

id

hex(32)

Unique contact identifier

mobile

string

Mobile number

BANK ACCOUNT ENTITY

The various properties are explained below:

Param

Type

Description

account_number

string

Account number

bank_name

string

Bank name

id

hex(32)

Unique bank account identifier

ifsc

string

IFSC code

is_primary

boolean

Whether it is a primary bank account or not

type

string

Type of bank account. Possible value: Savings and Current

DOCUMENT ENTITY

The various properties are explained below:

Param

Type

Description

document_creation_date

date

Document creation date

document_name

string

Document name

id

hex(32)

Unique document identifier

signed_url

string

Signed URL to document

type

string

Type of document. Possible values: Form-16, Form 27Q, Form 26Q, Form 24Q, ITR, ITR-V, Signature, Aadhaar, Bank Statement, Birth Certificate, Certificate of Incorporation, Driving License, Voter Id Card, Electricity Bill, Marriage Certificate, PAN, Passport, Rent Agreement, Telephone Bill, Mobile Bill, Form-49A, Acknowledgement, Salary Slips, Profit and Loss Account, Balance Sheet, Demat Account Ledger, Contract Notes, Purchase Deed, Sale Deed, National Savings Certificate(NSC), Fixed Deposit Certificate, Insurance Premium Receipt, Pension Fund Receipt, Tution Fees Receipt, Donation Receipt, Disability Certificate, Tax Deduction Certificate, Form-16A, Form-26AS, Tax Payment Counterfoil, Passbook, LLP Agreement, Gas Bill, Property Tax Bill, NOC, INC-9, INC-10, DIR-2, MOA Subscriber Sheet, AOA Subscriber Sheet, LLP Subscriber Sheet, Form-12BB, Rent Receipt, Computation of Income, Challan, TDS Return, FVU, Form-27, TDS Return Acknowledgement, TDS Return Statistics, Consolidated Statment, Income Tax Notice, Invoice, Purchase Order, Estimate, Bill of Supply, Debit Note, Credit Note, Logo and Other

Common HTTP error codes

Code

Description

400

Missing or bad request parameters or values

401

Authorization failure

403

Authentication token expired/missing error

404

Requested resource was not found

413

Request is too large

429

Too many requests to the API (rate-limiting), Quota exceeded error

500

Something unexpected went wrong like accessing invalid API, invalid endpoint, etc.

504

Gateway timeout; the API is unreachable