Response structure

All GET and DELETE request parameters are passed on as either path or query parameters.

Meanwhile, POST parameters are passed on as (Content-Type: application/JSON) body. Lastly, 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 the 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.

Param	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 for 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",
    "timestamp": 1614694847237,
    "transaction_id": "03e736ce-1ceb-42e8-a457-9267fede17f8"
}

Data Types

Values in JSON responses are of types of 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	`string`	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
`422`	Invalid Request Body
`429`	Too many requests to the API (rate-limiting), Quota exceeded error
`500`	Something unexpected went wrong like accessing invalid API, invalid endpoint, etc.
`503`	Source Unavailable
`504`	Gateway timeout; the API is unreachable