Request API access

API credentials are required in order to invoke Tarrakki APIs. The API credentials are generated and shared with you once your registration is processed.

Write to us at gunjan.dudhrejiya@tarrakki.com if you have not yet received your API credentials.

Authenticate

Tarrakki APIs use OAuth 2.0 protocol for authentication and authorization. It is the de-facto industry-standard for auhorizing applications via internet.

Use following snippet to authenticate using the client id, and client secret provided.

PS: Replace {URL}, {YOUR CLIENT ID}, and {YOUR CLIENT SECRET}.

curl --request POST 'https://{URL}/access_token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "grant_type": "client_credentials",
    "client_id": "{YOUR CLIENT ID}",
    "client_secret": "{YOUR CLIENT SECRET}"
}'

A successful invocation returns HTTP 200 (success) with JSON response e.g.

{
"token_type":"Bearer",
"access_token":"eyJhbGci...",
"expires_in":3600
}

Invoking APIs

Tarrakki APIs use OpenAPI Specification (OAS) making it easier for humans and computers to understand, discover and use the APIs.

For instance, the GET /kyc API is used to check KYC status of a PAN card holder. The API requires OAuth2 authorization, meaning it is accessible with a valid access token. The API also requires "pan" and it is accepted as a query parameter.

Following example demonstrates GET /kyc API call. The access token is provided as bearer token in the authorization header, and the pan is provided as query parameter.

curl --request GET 'http://{URL}/kyc?pan=ABCDE1234X' \
--header 'Authorization: Bearer eyJhbGci...'

Handling API response

Tarrakki API uses HTTP status codes to communicate success or failure of an API request. For instance, HTTP 200 means that the API request is processed successfully. In general, HTTP status code between 200-299 range indicate success. Following is an example response of the GET /kyc request.

{
    "status": "pending", 
    "pan": "ABCDE1234X"
}

HTTP status codes between 400-499 range indicate client error. Following is an example response of the GET /kyc?pan=ABCD01234X API. The fifth character in the pan letter 'E' is replaced with '0' to make it invalid.

{
    "message": "Invalid PAN"
}

Status codes between 500-599 range indicate server error and these are rare.

This section will help you to understand the process of onboarding an investor.

Step 0: Authentication

Our APIs use OAuth 2.0 protocol for authentication and authorization. To start using our APIs, you need to authenticate yourself using the client_id, client_secret & base_url.

For more information regarding the same, check the "Getting Started" section.

Step 1: Check KYC Status

The first step is to run the KYC Status API. Enter PAN, if it’s KYC verified, then we move further. If the KYC is not verified, we need to register it first and then proceed further.

You may only proceed further if the Response status for this is “registered”

Step 2: Create Investor

The next step is to create an Investor. We need to fill in all the necessary details and use the Create Investor API, this API will create investor on our system.

As a response, we receive an ‘id’ and the status as “incomplete_details”. Store the id, and proceed further to Step 3.

Step 3: Add Bank Details

Once we have created our investor, we need to add all the necessary details. One of these details is Bank Details. Using the “Add Bank” API we add the bank details of the investor.

Remember, you need to pass the ‘id’ we have for the previously created investor.

This API has no success response. Now move to Step 4.

Step 4: Upload Documents

For Individuals, you need to Upload “Signature” using the Upload document API.

Refer below table to find the documents needed for each investor types.

Step 5: Add Nominee Details

The next step is to create the Nominee. You can add up to 3 nominees, and make sure that the total share adds up to no more or no less than 100.

You can store the response "nominee_id".

Status Check : Investor Status API You can use this API to know the current status of your investor. Until you have completed Steps upto Step 4, the status will be “incomplete_details”. After Step 4, the status should be “pending_nominee_verification” After Step 5, the status should be “under_review” Once the Investor’s Bank account gets verified, the status will change to “ready_to_invest”

Once the status is “ready_to_invest”, we can start placing orders and invest.

This collection provides set of APIs to check KYC status of an investor, and submit a request to initiate eKYC for an investor.

Set of APIs to facilitate onboarding of an investor. It involves registering investor's personal, demographic and financial information with BSE.

This collection also provides set of APIs to retrieve details of an investor, and update the information.

Investor's nominations