NAV Navbar
shell

Introduction

The FP API is designed to be easily predictable and have consistency across all the resources. It accepts json in the request body and returns a json representation of the resource. We use standard HTTP response codes and HTTP verbs.

You can access FP API in sandbox and production modes separately. Use the following base URLs: Sandbox (for testing): https://s.finprim.com Production (for live transactions): https://api.fintechprimitives.com

MasterData

Pincode

curl "https://s.finprim.com/api/onb/pincodes/560102"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns JSON structured like this:

{
  "code": "560102",
  "city": "Bangalore South",
  "district": "Bangalore",
  "state_name": "Karnataka",
  "country_ansi_code": "IN",
  "_links": [
    {
      "href": "https://s.finprim.com/api/onb/pincodes/560102",
      "rel": "self",
      "method": "GET"
    }
  ]
}

This endpoint retrieves details of the given pincode

HTTP Request

GET https://s.finprim.com/api/onb/pincodes/{pincode}

Response Object

Attribute Type Description
code string Pincode of the location
city string City
district string District
state_name string State
country_ansi_code string ANSI code of the Country

States

curl "https://s.finprim.com/api/onb/states"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns JSON structured like this:

{
  "states": [
    {
      "name": "Karnataka",
      "state_code": "KA",
      "country_ansi_code": "IN"
    }
  ]
}

This endpoint retrieves all states of India which are updated in the system

HTTP Request

GET https://s.finprim.com/api/onb/states

Response Object

Attribute Type Description
name string name of the state
state_code string state code associated with the state
country_ansi_code string ANSI code of the country

Countries

curl "https://s.finprim.com/api/onb/countries"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns JSON structured like this:

{
  "countries": [
    {
      "name": "India",
      "ansi_code": "IN"
    }
  ]
}

This endpoint retrieves the list of countries updated in the system

HTTP Request

GET https://s.finprim.com/api/onb/countries

Response Object

Attribute Type Description
name string name of the country
country_ansi_code string ANSI code of the country

IFSC

curl "https://s.finprim.com/api/onb/ifsc_code/ICIC0000611"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns JSON structured like this:

{
  "ifsc_code": "ICIC0000611",
  "micr_code": "0000000",
  "branch_name": "gudivada",
  "branch_address": "ICICI BANK LTD , D NO-11-218, NENIPLAZA, ELURU ROAD, GUDIVADA. 521301",
  "bank_name": "ICICI",
  "contact": "SUMANTH SAGI 08674-247355",
  "city": "guivada",
  "district": "KRISHNA",
  "state": "ANDHRA PRADESH"
}

This endpoint retrieves details of the given ifsc_code updated in the system

HTTP Request

GET https://s.finprim.com/api/onb/ifsc_codes/{ifsc_code}

Response Object

Attribute Type Description
ifsc_code string IFSC code associated with the bank
micr_code string MICR code associated with the bank (if available)
branch_name string branch name of the bank
branch_address string branch address of the bank
bank_name string name of the bank
contact string contact details of the bank (if available)
city string city in which bank is located
district string district in which bank is located
state string state in which bank is located

Fund Scheme

curl "https://s.finprim.com/api/oms/fund_schemes/INF277K010L9  "
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns JSON structured like this:

{
  "fund_scheme_id": 4134,
  "name": "Tata Multicap Fund-Regular Plan-Dividend Reinvestment",
  "investment_option": "DIV_REINVESTMENT",
  "min_initial_investment": 5000,
  "min_additional_investment": 1000,
  "initial_investment_multiples": 1,
  "max_initial_investment": 99999999,
  "max_additional_investment": 99999999,
  "additional_investment_multiples": 1,
  "min_withdrawal_amount": 500,
  "min_withdrawal_units": 0.01,
  "max_withdrawal_amount": 99999999,
  "max_withdrawal_units": 99999999,
  "withdrawal_multiples": 1,
  "withdrawal_multiples_units": 0.001,
  "sip_allowed": true,
  "swp_allowed": true,
  "stp_out_allowed": true,
  "stp_in_allowed": true,
  "sip_frequency_specific_data": {
    "monthly": {
      "dates": "[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28]",
      "min_installment_amount": 1000.0,
      "max_installment_amount": 99999999.0,
      "amount_multiples": 100.0,
      "min_installments": 6
    },
    "quarterly": {
      "dates": "[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28]",
      "min_installment_amount": 10000.0,
      "max_installment_amount": 99999999.0,
      "min_installments": 3,
      "amount_multiples": 1000
    },
    "half_yearly": {
      "dates": "[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28]",
      "min_installment_amount": 10000.0,
      "max_installment_amount": 99999999.0,
      "min_installments": 3,
      "amount_multiples": 1000
    },
    "yearly": {
      "dates": "[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28]",
      "min_installment_amount": 10000.0,
      "max_installment_amount": 99999999.0,
      "min_installments": 3,
      "amount_multiples": 1000
    }
  },
  "swp_frequency_specific_data": {
    "monthly": {
      "dates": "[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28]",
      "min_installment_amount": 1000.0,
      "max_installment_amount": 99999999.0,
      "min_installments": 6,
      "amount_multiples": 100.0
    },
    "quarterly": {
      "dates": "[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28]",
      "min_installment_amount": 10000.0,
      "max_installment_amount": 99999999.0,
      "min_installments": 3,
      "amount_multiples": 100.0
    },
    "half_yearly": {
      "dates": "[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28]",
      "min_installment_amount": 10000.0,
      "max_installment_amount": 99999999.0,
      "min_installments": 3,
      "amount_multiples": 1000
    },
    "yearly": {
      "dates": "[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28]",
      "min_installment_amount": 10000.0,
      "max_installment_amount": 99999999.0,
      "min_installments": 3,
      "amount_multiples": 1000
    }
  },
  "stp_frequency_specific_data": {
    "monthly": {
      "dates": "[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28]",
      "min_installment_amount": 1000.0,
      "max_installment_amount": 99999999.0,
      "min_installments": 6,
      "amount_multiples": 100.0
    },
    "quarterly": {
      "dates": "[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28]",
      "min_installment_amount": 1000.0,
      "max_installment_amount": 99999999.0,
      "min_installments": 6,
      "amount_multiples": 100.0
    },
    "half_yearly": {
      "dates": "[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28]",
      "min_installment_amount": 10000.0,
      "max_installment_amount": 99999999.0,
      "min_installments": 3,
      "amount_multiples": 1000
    },
    "yearly": {
      "dates": "[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28]",
      "min_installment_amount": 10000.0,
      "max_installment_amount": 99999999.0,
      "min_installments": 3,
      "amount_multiples": 1000
    }
  },
  "switch_in_allowed": true,
  "min_switch_in_amount": 5000,
  "switch_in_amount_multiples": 0.01,
  "fund_category": "EQUITY",
  "plan_type": "REGULAR",
  "sub_category": "",
  "amfi_code": "144545",
  "isin": "INF277K010L9",
  "close_ended": false,
  "scheme_code": "MTCD",
  "lock_in": false,
  "lock_in_period": null,
  "long_term_period": null,
  "purchase_allowed": true,
  "redemption_allowed": true,
  "insta_redemption_allowed": false,
  "merged": false,
  "merged_to_isin": "",
  "merger_date": null,
  "switch_out_allowed": true,
  "min_switch_out_amount": 5000.0,
  "min_switch_out_units": 0.01,
  "switch_out_unit_multiples": 0.01,
  "switch_out_amount_multiples": 0.01,
  "amc_id": 36,
  "rta_id": 1,
  "name_changes": null,
  "active": true,
  "delivery_mode": "PHYSICAL",
  "switch_multiples": 0.01,
  "switch_in_min_amt": 5000,
  "min_sip_amount": 150,
  "min_swp_amount": 500,
  "min_stp_in_amount": 1000,
  "max_sip_amount": 1999999,
  "max_swp_amount": 99999999,
  "max_stp_in_amount": 99999999,
  "min_sip_installments": 12,
  "min_stp_out_installments": 6,
  "min_swp_installments": 6,
  "sip_multiples": 1,
  "swp_multiples": 1,
  "stp_in_amount_multiples": 1,
  "sip_frequency_data": {
    "MONTHLY": "1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28"
  },
  "swp_frequency_data": {
    "MONTHLY": "1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28"
  },
  "stp_frequency_data": {
    "MONTHLY": "1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28"
  }
}

This endpoint retrieves any particular fund scheme information

HTTP Request

GET https://s.finprim.com/api/oms/fund_schemes/{isin}

Response Object

Attribute Type Description
fund_scheme_id integer id of the fund scheme
isin string ISIN of the scheme
active boolean if the scheme is active
delivery_mode string Allowed delivery mode for MF units in the scheme. Possible Values
- PHYSICAL
- DEMAT
- DEMAT_PHYSICAL
name string name of the fund scheme
amc_id integer unique amc id given by fp
rta_id integer unique rta id given by fp
purchase_allowed boolean if Purchase is allowed for the scheme
redemption_allowed boolean if Redemption is allowed for the scheme
instant_redemption_allowed boolean if Instant Redemption is allowed for the scheme
investment_option string type of investment option. Possible Values
- GROWTH
- DIV_REINVESTMENT
- DIV_PAYOUT
fund_category string category of scheme. Possible values -
- Equity
- Debt
- Liquid
- Others
plan_type string scheme type Regular or Direct
min_initial_investment integer minimum amount an investor needs to invest to make a fresh purchase
max_initial_investment integer maximum amount an investor is allowed to invest for fresh purchase
initial_investment_multiples integer initial amount invested should be a multiple of initial_investment_multiples
min_additional_investment integer minimum amount an investor requires to invest in an existing folio
max_additional_investment integer maximum amount an investor is allowed to invest in an existing folio
additional_investment_multiples integer additional amount invested should be a multiple of additional_investment_multiples
min_withdrawal_amount integer minimum withdrawal amount for the scheme
max_withdrawal_amount integer maximum withdrawal amount allowed for the scheme
withdrawal_multiples integer withdrawal amount requested should be a multiple of withdrawal_multiples
min_withdrawal_units decimal minimum withdrawal units for the scheme
max_withdrawal_units integer maximum withdrawal units allowed for the scheme
withdrawal_multiples_units decimal withdrawal units requested should be a multiple of withdrawal_multiples_units
sip_allowed boolean if SIP is allowed for the scheme
swp_allowed boolean if SWP is allowed for the scheme
stp_out_allowed boolean if systematic transfer out is allowed for the scheme
stp_in_allowed boolean if systematic transfer in is allowed for the scheme
switch_in_allowed boolean if Switch-In is allowed for the scheme
min_switch_in_amount integer minimum amount required to Switch-In to the scheme
switch_in_amount_multiples decimal amount requested for Switch-In should be a multiple of switch_in_amount_multiples
switch_out_allowed boolean if Switch-Out is allowed from the scheme
min_switch_out_amount decimal minimum amount required to Switch-Out from the scheme
min_switch_out_units decimal minimum number of units to Switch-Out from the scheme
switch_out_unit_multiples decimal Switch-Out units requested should be multiple of switch_out_unit_multiples
switch_out_amount_multiples decimal Switch-Out amount requested should be multiple of switch_out_amount_multiples
sub_category string
amfi_code string code assigned by AMFI for unique identification of the funds
close_ended boolean if the scheme is close ended
scheme_code string unique identification code associated with the scheme
lock_in boolean if Lock-In applicable for the scheme
lock_in_period integer Lock-In period of the scheme
long_term_period integer refers to a period an investment needs to be held (locked)
merged boolean if scheme is merged to new scheme
merged_to_isin string new scheme to which it has merged into
merger_date string date on which scheme has merged with new scheme. Applicable only if merged = True
name_changes hash history if the scheme has changed its name to new fund scheme name
switch_multiples decimal switch_multiples of the scheme
switch_in_min_amt decimal minimum amount required to switch_in to the scheme

Deprecated Attributes

In this api there were multiple attributes for SIP, SWP and STP . So we have now clubbed them into a list for each type (sip_frequency_specific_data,swp_frequency_specific_data and stp_frequency_specific_data) .

For Example:

For SIP we have below attributes

"min_sip_amount":150,
"max_sip_amount": 1999999,
"sip_multiples": 12
"min_sip_installments": 1,
"sip_frequency_data": {"MONTHLY": "1,2,3,4,5"}

So now all this data related to sip would be in a list sip_frequency_specific_data . This list would be seprated on the basis of frequency that is monthly, quarterly etc.

"sip_frequency_specific_data": {
"monthly": {
"dates": "[1,2,3,4,5]",
"min_installment_amount": 1000.0,
"max_installment_amount": 99999999.0,
"amount_multiples": 100.0,
"min_installments": 6
},
"quarterly": {
"dates": "[1,2,3,4,5]",
"min_installment_amount": 10000.0,
"max_installment_amount": 99999999.0,
"min_installments": 3,
"amount_multiples": 1000
}

Deprecated Attributes New Attribute
min_sip_amount

min_swp_amount

min_stp_in_amount

min_installment_amount
max_sip_amount

max_swp_amount

max_stp_in_amount

max_installment_amount
sip_multiples

swp_multiples

stp_in_amount_multiples

amount_multiples
min_sip_installments

min_swp_installments

min_stp_out_installments

min_installments
sip_frequency_data sip_frequency_specific_data
swp_frequency_data swp_frequency_specific_data
stp_frequency_data stp_frequency_specific_data

Frequency Specific Data

The values of the attributes are specific to a particular frequency of any specified plan.

Attribute Type Description
dates integer-array dates of month on which plan creation is allowed
min_installment_amount decimal minimum amount required to create the plan
max_installment_amount decimal maximum amount allowed for the plan
amount_multiples decimal amount invested/withdrawn should be a multiple of amount_multiples
min_installments integer minimum installments required to create the plan

List all fund scheme

Below endpoint can be used to retrieve all fund schemes data, by default it gives you first 20 schemes. You can use below query parameters to filter the result of api.

HTTP Request

GET https://s.finprim.com/api/oms/fund_schemes

Query Parameters

Name Mandatory Default Description
page no 0 page number of the result set
size no 20 number of results per page, size should not be greater than 100
amc_id no - unique amc id given by fp
investment_option no - type of investment option. Possible Values
- GROWTH
- DIV_REINVESTMENT
- DIV_PAYOUT
plan_type no - scheme type Regular or Direct
delivery_mode no - Allowed delivery mode for MF units in the scheme. Possible Values
- PHYSICAL
- DEMAT
- DEMAT_PHYSICAL

AMCs

curl "https://s.finprim.com/api/oms/amcs"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns JSON structured like this:

{
  "_links": {
    "self": {
      "href": "https://s.finprim.com/oms/api/amcs"
    }
  },
  "amcs": [
    {
      "id": 1,
      "name": "Axis MF",
      "active": true,
      "amc_code": null
    }
  ]
}

This endpoint retrieves all the AMCs.

HTTP Request

GET https://s.finprim.com/api/oms/amcs

Response Object

Attribute Type Description
id integer Id of the AMC
name string Name of the AMC
active boolean Status of the AMC configured
amc_code string Unique code associated with AMC

Authentication

Overview

FP uses OAuth 2.0 protocols for authentication. At present, FP supports the following authentications

Types of authentication

Endpoints for authentication:

GET /v2/auth/{tenant_name}/auth POST /v2/auth/{tenant_name}/token

Token Object

Token object encapsulates the access_token that is required to access FP APIs. You get a token object after successful authentication(Tenant authentication or Investor authentication or Partner authentication).

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIyUVVoVl9aaGVyQmRHMjVQMl83cmdVaDYxcS1WXzZ0NzNmO",
  "expires_in": 1800,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "default"
}
Attribute Type Comments
access_token string The access token contains the security credentials for a login session and identifies the user. You need to pass this in the header at the time of invoking FP APIs.
expires_in long It specifies the validity of the access token in seconds.
refresh_token string Not applicable for tenant login and reserved for Partner and Investor authentication.
refresh_expires_in long Not applicable for tenant login and reserved for Partner and Investor authentication.
token_type string The token type will always be Bearer. This type of authentication means that any Bearer of an access token can access FP APIs.
not-before-policy (for internal use) int not-before-policy ensures that any tokens issued before that time become invalid.
scope (for internal use) string The scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account.

Tenant Authentication

Getting Started

  1. Write an email to fpsupport@cybrilla.com and register yourself as OAuth 2.0 client for tenant authentication purposes.
  2. We will share the client_id, client_secret, and tenant_name.
  3. Use POST /v2/auth/{tenant_name}/token endpoint and provide client_id, client_secret, and tenant_name to generate token object.
  4. Use the generated token object's access_token to access FP APIs.
  5. Every token object will have an expiry time. Ensure that you are creating a new token object if the existing token object is expired.

Getting tenant token

For tenant tokens, we are using Client Credentials flow. This flow is recommended for server-side (aka confidential) client applications with no end-user, which normally describes server-to-server communication. The application needs to securely store its client ID and secret and pass them in exchange for an access token.

POST /v2/auth/{tenant_name}/token

curl \
-H 'accept: application/json' \
-H 'content-type: application/x-www-form-urlencoded' \
-d "client_id=XXX" \
-d "client_secret=XXXXXXX" \
-d "grant_type=client_credentials" \
"{baseUrl}/v2/auth/{tenant_name}/token"

Success response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIyUVVoVl9aaGVyQmRHMjVQMl83cmdVaDYxcS1WXzZ0NzNmO",
  "expires_in": 1800,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "default"
}

Headers

Parameter Mandatory Default value
accept yes - application/json
content-type yes - application/x-www-form-urlencoded

Request Parameters

Parameter Mandatory Default Description
client_id yes - client_id provided by fintechprimitives
client_secret yes - client_secret provided by fintechprimitives
grant_type yes - client_credentials

Using token to make API call

FP API uses bearer auth to authenticate all the API calls. You need to send the following header in all your API calls along with your access token:

Authorization: Bearer ACCESS_TOKEN

Partners

Represents a FP Partner entity. For example, a partner could be a sub-broker.

Endpoints:

POST /v2/partners
GET /v2/partners/:id
GET /v2/partners

Partner Object

{
  "object": "partner",
  "id": "ptnr_8afb5028f1574e639b58722becd70aa3",
  "name": "ABC Distributors",
  "license_code": "ARN-98345",
  "created_at": "2023-08-21T16:07:02+05:30",
  "default_broker_codes": {
    "karvy": "ATID",
    "cams": "ATID"
  },
  "location": "Bangalore",
  "ref_no": "34768322346",
  "mobile": "9036427846",
  "email": "abc_distributors@gmail.com",
  "contact_person_name": "Abraham N",
  "expiry_date": "2028-09-01",
  "euins": [
    "E23432"
  ]
}
Attribute Type Comments
object string Value is partner. String representing the object type. Objects of the same type share the same value
id string Unique identifier for the object.
name string Full name of the partner
license_code string License code of the partner (RIA/ARN code)
default_broker_codes string Default RTA broker codes of the partner
location string Partner registration location
ref_no string Internal reference number provided by the tenant for a partner.
mobile string Mobile number of the partner
email string Email ID of the partner
contact_person_name string Contact person name from the partner office
expiry_date string The expiration date of the license code of the partner if any. Format: YYYY-MM-DD
euins string Employee Unique Identification Number of the partner can be used while placing an order
created_at string Creation timestamp

Create a Partner

curl -X POST "https://s.finprim.com/v2/partners"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "name": "ABC Distributors",
  "license_code": "ARN-98345",
  "default_broker_codes": {
    "karvy": "ATID",
    "cams": "ATID"
  },
  "location": "Bangalore",
  "ref_no": "34768322346",
  "mobile": "9036427846",
  "email": "abc_distributors@gmail.com",
  "contact_person_name": "Abraham N",
  "expiry_date": "2028-09-01",
  "euins": [
    "E23432"
  ]
}

JSON Response:

{
  "object": "partner",
  "id": "ptnr_8afb5028f1574e639b58722becd70aa3",
  "name": "ABC Distributors",
  "license_code": "ARN-98345",
  "created_at": "2023-08-21T16:07:02+05:30",
  "default_broker_codes": {
    "karvy": "ATID",
    "cams": "ATID"
  },
  "location": "Bangalore",
  "ref_no": "34768322346",
  "mobile": "9036427846",
  "email": "abc_distributors@gmail.com",
  "contact_person_name": "Abraham N",
  "expiry_date": "2028-09-01",
  "euins": [
    "E23432"
  ]
}

Request Parameters

Name Mandatory Type Comments
name no string
license_code no string
default_broker_codes yes hash Supported keys cams and karvy. Use to populate sub-broker broker code. Once set, this cannot be modified
location yes string
ref_no no string
mobile no string
email no string
contact_person_name no string
expiry_date no string
euins conditional string[] List of EUINs for the partner. Mandatory when partner is an ARN holder

Fetch a Partner

GET /partners/:id

curl -X GET "https://s.finprim.com/v2/partners/ptnr_8afb5028f1574e639b58722becd70aa3"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API is used to fetch a partner by its identifier.

Query Parameters

Name Mandatory Type Comments
id yes string id of the partner

JSON Response:

{
  "object": "partner",
  "id": "ptnr_8afb5028f1574e639b58722becd70aa3",
  "name": "ABC Distributors",
  "license_code": "ARN-98345",
  "created_at": "2023-08-21T16:07:02+05:30",
  "default_broker_codes": {
    "karvy": "ATID",
    "cams": "ATID"
  },
  "location": "Bangalore",
  "ref_no": "34768322346",
  "mobile": "9036427846",
  "email": "abc_distributors@gmail.com",
  "contact_person_name": "Abraham N",
  "expiry_date": "2028-09-01",
  "euins": [
    "E23432"
  ]
}

Search a Partner

GET /partners

curl -X GET "https://s.finprim.com/v2/partners?code=ARN-13452"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API can be use to search partner.

JSON Response:

{
  "object": "list",
  "data": [
    {
      "object": "partner",
      "id": "ptnr_8afb5028f1574e639b58722becd70aa3",
      "name": "ABC Distributors",
      "license_code": "ARN-98345",
      "created_at": "2023-08-21T16:07:02+05:30",
      "default_broker_codes": {
        "cams": "ATID",
        "karvy": "ATID"
      },
      "location": "Bangalore",
      "ref_no": "34768322346",
      "mobile": "9036427846",
      "email": "abc_distributors@gmail.com",
      "contact_person_name": "Abraham N",
      "expiry_date": "2028-09-01",
      "euins": [
        "E23432"
      ]
    }
  ]
}

Query Parameters

Name Mandatory Type Comments
code yes string Licence code of the partner

KYC Checks

This API will allow you to check the KYC compliance status of an investor and also display his demographic information as present in the KRA (KYC Registration Agency) databases.

Endpoints:

POST /api/kyc/check GET /api/kyc/:id PUT /api/kyc/:id/refetch

Create a kyc check

Status Check

curl -X POST "https://s.finprim.com/api/kyc/check"
-H "x-tenant-id: <tenant name>"
-H "Authorization: Bearer JWTTOKEN"
-d
'
{
  "pan": "BNBPP9384M"
}
'

The above command returns JSON structured like this:

{
  "id": "5620fd1f-eb14-442e-b0ee-da96a6c305c0",
  "source_ref_id": null,
  "pan": "BNBPP9384M",
  "entity_details": {
    "name": "Tony Soprano"
  },
  "status": false,
  "constraints": [
    {
      "type": "investment_limit",
      "amount": {
        "value": 50000,
        "currency": "inr"
      }
    }
  ],
  "sources": [
    {
      "name": "kra-cams",
      "response_verbatim": "Y|BNBPP9384M|KS100",
      "fetched_at": "2018-04-21T23:00:20+05:30"
    }
  ],
  "created_at": "2018-04-21T23:00:20+05:30",
  "updated_at": "2018-04-21T23:00:20+05:30",
  "action": "modify",
  "reason": "onhold"
}

POST /api/kyc/check

Fetch KYC Data

curl -X POST "https://s.finprim.com/api/kyc/check"
-H "x-tenant-id: <tenant name>"
-H "Authorization: Bearer JWTTOKEN"
-d
'
{
"pan": "AAAPA3751A",
"date_of_birth": "1955-10-25"
}
'

The above command returns JSON structured like this:

{
  "id": "429f998a-6488-428b-adbd-1c7abdf2a42a",
  "source_ref_id": null,
  "pan": "AAAPA3751A",
  "entity_details": {
    "name": "Tony Soprano",
    "gender": "male",
    "date_of_birth": "1955-10-25",
    "father_name": "Murli Dhar Narang",
    "marital_status": "married",
    "nationality": "indian",
    "residential_status": "resident_individual",
    "correspondence_address": {
      "line_1": "19th main, 33rd cross",
      "line_2": "Jayanagar 4th T block",
      "line_3": null,
      "city": "Bengaluru",
      "pincode": "560041",
      "state": "Karnataka",
      "country": "India"
    },
    "permanent_address": {
      "line_1": "19th main, 33rd cross",
      "line_2": "Jayanagar 4th T block",
      "line_3": null,
      "city": "Bengaluru",
      "pincode": "560041",
      "state": "Karnataka",
      "country": "India"
    },
    "email": "suresh.nrg@gmail.com",
    "mobile": "9809879878"
  },
  "status": true,
  "constraints": [

  ],
  "sources": [
    {
      "name": "kra-cvl",
      "response_verbatim": "<xml></xml>",
      "fetched_at": "2021-08-10T12:32:25+05:30"
    }
  ],
  "created_at": "2021-08-10T12:32:25+05:30",
  "updated_at": "2021-08-10T12:32:25+05:30",
  "action": null,
  "reason": null
}

Creating a KYC Check fetches the investor's kyc status from different sources. We offer below listed two solutions here.

Status Check

This will allow you to check the KYC status of an investor using his / her PAN number. The status can be true or false which will indicate if he / she is KYC compliant or not. If the investor has some investment constraints, they would be listed under the constraints list.

Fetch KYC Data

This will allow you to check and fetch the KYC details of an investor as recorded in the KRA databases. You need to send the investor's PAN number and the date of birth as the input parameters in the request body. The response would contain the KYC status along with the demographic (Identity, Address and Contact) information of the investor under entity_details list.

Query Parameters

Parameter Mandatory Default Description
pan yes - A valid PAN number to check the kyc status for
Parameter Mandatory Default Description
pan yes - A valid PAN number to check the kyc status for
date_of_birth yes - A valid date of birth for the above mentioned PAN number in YYYY-MM-DD format

Fetch a kyc check

curl "https://s.finprim.com/api/kyc/5620fd1f-eb14-442e-b0ee-da96a6c305c0"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns JSON structured like this:

{
  "id": "5620fd1f-eb14-442e-b0ee-da96a6c305c0",
  "source_ref_id": null,
  "pan": "BNBPP9384M",
  "entity_details": {
    "name": "Tony Soprano"
  },
  "status": false,
  "constraints": [
    {
      "type": "investment_limit",
      "amount": {
        "value": 50000,
        "currency": "inr"
      }
    }
  ],
  "sources": [
    {
      "name": "kra-cams",
      "response_verbatim": "Y|BNBPP9384M|KS100",
      "fetched_at": "2018-04-21T23:00:20+05:30"
    }
  ],
  "created_at": "2018-04-21T23:00:20+05:30",
  "updated_at": "2018-04-21T23:00:20+05:30",
  "action": "modify",
  "reason": "onhold"
}

GET /api/kyc/:id

Retrieve the KYC Check object

Refetch a kyc check

curl -X PUT "https://s.finprim.com/api/kyc/5620fd1f-eb14-442e-b0ee-da96a6c305c0/refetch"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns JSON structured like this:

{
  "id": "5620fd1f-eb14-442e-b0ee-da96a6c305c0",
  "source_ref_id": null,
  "pan": "BNBPP9384M",
  "entity_details": {
    "name": "Tony Soprano"
  },
  "status": false,
  "constraints": [
    {
      "type": "investment_limit",
      "amount": {
        "value": 50000,
        "currency": "inr"
      }
    }
  ],
  "sources": [
    {
      "name": "kra-cams",
      "response_verbatim": "Y|BNBPP9384M|KS100",
      "fetched_at": "2018-04-21T23:00:20+05:30"
    }
  ],
  "created_at": "2018-04-21T23:00:20+05:30",
  "updated_at": "2018-04-21T23:00:20+05:30",
  "action": "modify",
  "reason": "onhold"
}

PUT /api/kyc/:id/refetch

Force the platform to refetch the kyc information from the sources

Error codes

These are the error codes that you would receive as a part of the Error object, whenever we get an error response from the configured source gateway while trying to fetch the KYC details of an investor.

Error code Description
cams_down The source gateway CAMS KRA is down
cams_internal_error The source gateway CAMS KRA encountered an internal error. This may occur mostly because CAMS KRA could not successfully fetch your KYC details as one or more KRAs might be facing a downtime
cams_timed_out The source gateway CAMS KRA timed out and we did not receive any response. Please try again after some time
cams_invalid_credentials Your credentials to access the source gateway CAMS KRA is either invalid or expired. Please reset and reach out to FP Support
cams_invalid_response The source gateway CAMS KRA sent an invalid response. These might occur very rarely when CAMS KRA sends KYC details from multiple sources against a single investor
cams_daily_limit_exceeded Daily limit exceeded to check the PAN details at the source gateway CAMS KRA
cvl_down The source gateway CVL KRA is down
cvl_internal_error The source gateway CVL KRA encountered an internal error. This may occur mostly because CVL KRA could not successfully fetch your KYC details as one or more KRAs might be facing a downtime
cvl_timed_out The source gateway CVL KRA timed out and we did not receive any response. Please try again after some time
cvl_invalid_credentials Your credentials to access the source gateway CVL KRA is either invalid or expired. Please reset and reach out to FP Support
cvl_invalid_response The source gateway CVL KRA sent an invalid response. These might occur very rarely when CVL KRA sends KYC details from multiple sources against a single investor
ipru_down The source gateway IPru AMC is down
ipru_internal_error The source gateway IPru AMC encountered an internal error
ipru_timed_out The source gateway IPru AMC timed out and we did not receive any response. Please try again after some time

KYC Requests

This endpoint can be used to create a KYC application. Even though values for name, pan, email, date_of_birth and mobile fields are required to create a KYC application and generate an OTP, all the required information must be collected from the KYC non-compliant user in order to perform eSign and complete the KYC application submission. At any point in time you can refer to requirements.fields_needed attribute in the KYC object to check the fields for which the values are required.

Endpoints:

POST /v2/kyc_requests
GET /v2/kyc_requests/:id
GET /v2/kyc_requests
PATCH /v2/kyc_requests
POST /v2/kyc_requests/:id/simulate

Basic workflow to submit a KYC application

  1. Create a KYC application by providing values for name, pan, email, date_of_birth and mobile. The KYC request will be in pending state at this stage. You can check the state by referring to the status attribute in the KYC object.

  2. Provide all the required information to eSign and submit the KYC application that is created. You can also check the requirements.fields_needed section in the KYC object to see the list of fields which are yet to be input.

  3. Once all the required details are provided, the KYC application moves from pending to esign_required state. Please note that this process might take 1-2 minutes (approx.) in production environment as the bank account details are verified in the background.

  4. Once the state of the KYC application changes to esign_required, Esign API should be used to create an esign object. Redirect the user to redirect_url in the esign object in order to perform the eSign.

  5. Once the user completes the eSign process successfully, the KYC application will be submitted and state moves from esign_required to submitted.

  6. Now our AMC partner would have received the KYC application that was submitted and the verification process begins, post which the application will be moved to either successful or rejected state

  7. In case the KYC request object is not completely filled and submitted within 5 days from the time of its creation, the status of the KYC request object would be changed to expired. In this case, you cannot retry the same application to fill the missing details and move it to esign_required state. You will have to create a new KYC request and submit it

KYC Request Object

{
  "object": "kyc_request",
  "id": "kycr_724198d524004ceb8ba8203d06a32e26",
  "status": "pending",
  "aadhaar_number": "1210",
  "pan": "K1PPG1998U",
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": null,
  "mother_name": "Neha Gupta",
  "email": "rani@example.com",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "signature": "file_9109577dfdc04c239e740684eed3d952",
  "photo": "file_872def4ecfe740af8d8f32de98b5fc01",
  "gender": "female",
  "date_of_birth": "1980-10-19",
  "marital_status": "unmarried",
  "country_of_birth": "in",
  "address": {
    "city": "Delhi",
    "proof": "file_3f9490b986924fab908456b920640245",
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "line_3": "12th Main Road South Delhi",
    "country": "in",
    "pincode": "401012",
    "proof_back": "file_40e41f689f8b40bc81d006052d65ea8e",
    "proof_type": "passport",
    "proof_number": "JXXXXXXA",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "identity_proof": "file_899c33d4304e420ca38f68ffbde617c6",
  "residential_status": "resident_individual",
  "occupation_type": "private_sector",
  "created_at": "2019-11-09T13:26:38.946+0530",
  "updated_at": "2019-11-09T13:28:38.946+0530",
  "expires_at": "2019-11-14T13:26:38.946+0530",
  "esign_required_at": null,
  "submitted_at": null,
  "successful_at": null,
  "rejected_at": null,
  "otp": "9bbf32",
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "file_3877919efa7f49c0b6f69e12793f0c2d"
  },
  "requirements": {
    "fields_needed": [
      "ipv_video"
    ]
  },
  "verification": {
    "status": "pending",
    "details": null,
    "details_verbose": null
  }
}
Attribute Type Comments
object string Value is kyc_request. String representing the object type. Objects of the same type share the same value
id string Unique identifier of the kyc_request object
name string Full name of the investor
pan string PAN number of the investor
email string Email id of the investor
mobile hash Mobile number of the investor
date_of_birth string Date of birth of the investor
aadhaar_number string Last 4 digits of the investor's aadhaar number
father_name string Investor's father name
spouse_name string Investor's spouse name
mother_name string Investor's mother name
gender enum Investor's gender. Possible values: male, female, transgender
country_of_birth enum Investor's country of birth in ISO 3601 2 alphabet code
marital_status enum Investor's marital status. Possible values: married, unmarried, others
residential_status enum This determines the investor's residential status for tax purposes. Possible values: resident_individual
occupation_type enum Investor's occupation details. Possible values: business, professional, self_employed, retired, housewife, student, public_sector, private_sector, government_sector, others
geolocation hash Location of the investor from where the kyc application is submitted. It contains latitude and longitude
bank_account hash Investor's bank account details. Contains account_holder_name, account_number, ifsc_code, proof
address hash Address for all correspondence
identity_proof string Copy of investor's pan card
ipv_video string Verification video
signature string Investor's signature
photo string Investor's photograph
otp string Verification code for the video. The code has no expiration time.
status string The status of the kyc request. Can be pending, esign_required, submitted, successful, rejected, expired
created_at string The timestamp at which the kyc request object was created
updated_at string The timestamp at which the kyc request object was updated
expires_at string The timestamp at which the kyc request object expires. This would be 5 days from the time of kyc_request object creation
esign_required_at string The timestamp at which the kyc request object was eligible to be esigned
submitted_at string The timestamp at which the kyc request object was submitted to AMC for further verification
successful_at string The timestamp at which the kyc request object was successfully submitted to the KRA for final verification
rejected_at string The timestamp at which the kyc request object was rejected. Refer to the verifications hash for details on the rejection reasons
verification hash The details of the verification status of the data submitted
requirements hash Feedback on the data requirements. It contains fields_needed which represent the list of fields that are required for procesing the KYC Request

verification hash

A snippet of verification hash from the KYC Request object

{
  // showing only a part of KYC Request object
  "verification": {
    "status": "rejected",
    "details": {
      "pan": "data_mismatch",
      "signature": "data_missing",
      "address.proof": "document_unclear"
    },
    "details_verbose": {
      "pan": {
        "code": "data_mismatch",
        "reason": "Invalid pan"
      },
      "signature": {
        "code": "data_missing",
        "reason": "Signature not available"
      },
      "address.proof": {
        "code": "document_invalid",
        "reason": "Proof of address not valid; Translation into english is required"
      }
    }
  }
}
Attribute Type Comments
status string Status of the verification. Can be pending, esign_required, submitted, successful, rejected, expired
details hash If the verification status is rejected, this contains the details about the rejection. Keys of this hash represent the fields in the kyc request object and value can be data_missing, data_mismatch, document_unclear, document_invalid
details_verbose hash If the verification status is rejected, this contains the details about the rejection along with a reason text. Keys of this hash represent the fields in the kyc request object and value is a hash with code and reason keys. code is the same as in the details hash

Create a kyc request

curl -X POST "https://s.finprim.com/v2/kyc_requests"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{json_request}'

JSON request:

{
  "pan": "K1PPG1998U",
  "email": "rani@example.com",
  "aadhaar_number": "1210",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": "",
  "mother_name": "Neha Gupta",
  "gender": "female",
  "date_of_birth": "1980-10-19",
  "country_of_birth": "in",
  "marital_status": "unmarried",
  "residential_status": "resident_individual",
  "occupation_type": "private_sector",
  "address": {
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "line_3": "12th Main Road South Delhi",
    "city": "Delhi",
    "pincode": "401012",
    "country": "in",
    "proof": "file_3f9490b986924fab908456b920640245",
    "proof_back": "file_40e41f689f8b40bc81d006052d65ea8e",
    "proof_type": "passport",
    "proof_number": "JXXXXXX0",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "file_3877919efa7f49c0b6f69e12793f0c2d"
  },
  "identity_proof": "file_899c33d4304e420ca38f68ffbde617c6",
  "signature": "file_9109577dfdc04c239e740684eed3d952",
  "photo": "file_872def4ecfe740af8d8f32de98b5fc01"
}

JSON response:

{
  "object": "kyc_request",
  "id": "kycr_724198d524004ceb8ba8203d06a32e26",
  "status": "pending",
  "aadhaar_number": "1210",
  "pan": "K1PPG1998U",
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": null,
  "mother_name": "Neha Gupta",
  "email": "rani@example.com",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "signature": "file_9109577dfdc04c239e740684eed3d952",
  "photo": "file_872def4ecfe740af8d8f32de98b5fc01",
  "gender": "female",
  "date_of_birth": "1980-10-19",
  "marital_status": "unmarried",
  "country_of_birth": "in",
  "address": {
    "city": "Delhi",
    "proof": "file_3f9490b986924fab908456b920640245",
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "line_3": "12th Main Road South Delhi",
    "country": "in",
    "pincode": "401012",
    "proof_back": "file_40e41f689f8b40bc81d006052d65ea8e",
    "proof_type": "passport",
    "proof_number": "JXXXXXXA",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "identity_proof": "file_899c33d4304e420ca38f68ffbde617c6",
  "residential_status": "resident_individual",
  "occupation_type": "private_sector",
  "created_at": "2019-11-09T13:26:38.946+0530",
  "updated_at": "2019-11-09T13:28:38.946+0530",
  "expires_at": "2019-11-14T13:26:38.946+0530",
  "esign_required_at": null,
  "submitted_at": null,
  "successful_at": null,
  "rejected_at": null,
  "otp": "9bbf32",
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "file_3877919efa7f49c0b6f69e12793f0c2d"
  },
  "requirements": {
    "fields_needed": [
      "ipv_video"
    ]
  },
  "verification": {
    "status": "pending",
    "details": null,
    "details_verbose": null
  }
}

The endpoint is used to submit a KYC request to the platform.

HTTP Request

POST /v2/kyc_requests

Query Parameters

Name Mandatory* Type Comments
name yes string name of the investor
pan yes string should be a valid individual pan number
email yes string email ID of the investor to be reported to AMC
date_of_birth yes string date of birth in yyyy-mm-dd format
mobile yes object
aadhaar_number no string last 4 digits of aadhaar
father_name no string father name of the investor
spouse_name no string spouse name of the investor if married
mother_name no string mother name of the investor
gender no string gender of the investor. Values permitted: male, female, transgender
country_of_birth no string investor's country of birth in ISO 3601 2 alphabet code
marital_status no string marital status of the investor. Values permitted: married, unmarried, others
residential_status no string residential status of the investor. Values permitted: resident_individual
occupation_type no string occupation of the investor. Values permitted: business, professional, self_employed, retired, housewife, student, public_sector, private_sector, government_sector, others
address no object
identity_proof no string (ID of File) PAN card image. File must be in jpg, jpeg, png or pdf format and size should not exceed 5 MB.
ipv_video no string (ID of File) verification video of the investor. File must be in mp4 or webm format and size should not exceed 10 MB.

This need not be captured if you are choosing address.proof_type as aadhaar
signature no string (ID of File) copy of the wet signature of the investor. File must be in jpg, jpeg, png or pdf format and size should not exceed 5 MB.
photo no string (ID of File) investor's photo. File must be in jpg, jpeg, png or pdf format and size should not exceed 5 MB.
geolocation no object Location details of the investor from where the kyc application is submitted
bank_account no object Investor's bank account details

Mobile params

Name Mandatory type Comments
isd yes string isd code of country
number yes string mobile number

Address params

Name Mandatory type Comments
line_1 conditional string address line 1

Mandatory if proof_type != aadhaar.

If proof_type == aadhaar then any information given here would be ignored
line_2 no string address line 2
line_3 no string address line 3
city conditional string city name

Mandatory if proof_type != aadhaar.

If proof_type == aadhaar then any information given here would be ignored
pincode conditional string valid area pincode

Mandatory if proof_type != aadhaar.

If proof_type == aadhaar then any information given here would be ignored
country conditional string country in ISO 3601 2 alphabet code

Mandatory if proof_type != aadhaar.

If proof_type == aadhaar then any information given here would be ignored
proof yes string If proof_type != aadhaar then copy of the address proof (ID of File) must be passed here.

If proof_type == aadhaar then the ID of the identity_document with type = aadhaar should be passed here.
Please note that only successfully fetched identity_document would be accepted here
proof_back conditional string (ID of File) copy of the back side of the address proof. Required if proof_type is voter_id, passport and driving_licence. File must be in jpg, jpeg, png or pdf format and size should not exceed 5 MB.

If proof_type == aadhaar then any information given here would be ignored
proof_type yes string one of passport, voter_id, driving_licence, aadhaar
proof_number conditional string Valid ID number mentioned on the address proof. Mandatory if proof_type != aadhaar.

If proof_type == aadhaar then any information given here would be ignored
proof_issue_date no string Required if proof_type is passport, driving_licence else this would be ignored. Should be in past in yyyy-mm-dd format
proof_expiry_date no string Required if proof_type is passport, driving_licence else this would be ignored. Should be in future in yyyy-mm-dd format

Geolocation

Name Mandatory type Comments
latitude yes float Geolocation latitude
longitude yes float Geolocation longitude

Bank Account

Name Mandatory type Comments
account_holder_name yes string Name of the bank account holder
account_number yes string Account number
ifsc_code yes string IFSC code of the bank
proof no string (ID of File) cancelled cheque image. File must be in jpg, jpeg, png or pdf format and size should not exceed 5 MB.

A note on working with aadhaar as a proof as address

If you are using aadhaar as a proof of address, you need not give all the details reqiured in the address hash. Before updating the address hash, you need to create an identity_document to fetch the Aadhaar proof and details which should be used. address.proof can only accept identity_documents which are successfully fetched. Also note that if you are using aadhaar as a proof of address in a KYC Request, you need not give ipv_video as the OTP authentication that happens in the Digilocker workflow will fulfull the requirement of IPV (In-Person Verification).

Fetch a kyc request

curl -X GET "https://s.finprim.com/v2/kyc_requests/kycr_724198d524004ceb8ba8203d06a32e26"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON response:

{
  "object": "kyc_request",
  "id": "kycr_724198d524004ceb8ba8203d06a32e26",
  "status": "pending",
  "aadhaar_number": "1210",
  "pan": "K1PPG1998U",
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": null,
  "mother_name": "Neha Gupta",
  "email": "rani@example.com",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "signature": "file_9109577dfdc04c239e740684eed3d952",
  "photo": "file_872def4ecfe740af8d8f32de98b5fc01",
  "gender": "female",
  "date_of_birth": "1980-10-19",
  "marital_status": "unmarried",
  "country_of_birth": "in",
  "address": {
    "city": "Delhi",
    "proof": "file_3f9490b986924fab908456b920640245",
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "line_3": "12th Main Road South Delhi",
    "country": "in",
    "pincode": "401012",
    "proof_back": "file_40e41f689f8b40bc81d006052d65ea8e",
    "proof_type": "passport",
    "proof_number": "JXXXXXXA",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "identity_proof": "file_899c33d4304e420ca38f68ffbde617c6",
  "residential_status": "resident_individual",
  "occupation_type": "private_sector",
  "created_at": "2019-11-09T13:26:38.946+0530",
  "updated_at": "2019-11-09T13:28:38.946+0530",
  "expires_at": "2019-11-14T13:26:38.946+0530",
  "esign_required_at": null,
  "submitted_at": null,
  "successful_at": null,
  "rejected_at": null,
  "otp": "9bbf32",
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "file_3877919efa7f49c0b6f69e12793f0c2d"
  },
  "requirements": {
    "fields_needed": [
      "ipv_video"
    ]
  },
  "verification": {
    "status": "pending",
    "details": null,
    "details_verbose": null
  }
}

The endpoint is used to fetch the details of a KYC request.

HTTP Request

GET /v2/kyc_requests/:id

Query Parameters

Parameter Mandatory Default Description
id yes - id of the KYC Request

Status Descriptions - verification.status

Value Description
pending The KYC request has been created. It will be sent to AMC when all the required fields are provided.
esign_required Investor details document needs to be eSigned for the kyc request to be processed further.
submitted The KYC request has been submitted to the AMC
successful The KYC request has been successfully processed by the AMC and submitted to the KRA
rejected The KYC request has been rejected
expired The KYC request has been expired

Verification Details

Value Description
data_mismatch The data provided in the input is not matching with the document
document_invalid The provided document is not valid
document_unclear The provided document is not clear to read
data_missing The data point is completely missing

Details Verbose

Name Comments
code Value is same as Verification Details
reason Rejection messages separated by semicolon

List all kyc requests

curl -X GET "https://s.finprim.com/v2/kyc_requests?pan=K1PPG1998U&status=rejected,pending"
-H "x-tenant-id: <tenant name>"
-H "Authorization: Bearer ACCESS_TOKEN"

JSON response:

{
  "object": "list",
  "data": [
    {
      "object": "kyc_request",
      "id": "kycr_7a73c46a99b941ee94609671eff0f076",
      "status": "rejected",
      "aadhaar_number": "1210",
      "pan": "K1PPG1998U",
      "name": "Rani Gupta",
      "father_name": "Rajesh Gupta",
      "spouse_name": null,
      "mother_name": "Neha Gupta",
      "email": "rani@example.com",
      "mobile": {
        "isd": "+91",
        "number": "8160597103"
      },
      "signature": "file_9109577dfdc04c239e740684eed3d953",
      "photo": "file_872def4ecfe740af8d8f32de98b5fc02",
      "ipv_video": "file_5b21c8f9786443159d7f2f217879d0d2",
      "gender": "female",
      "date_of_birth": "1980-10-19",
      "marital_status": "unmarried",
      "country_of_birth": "in",
      "address": {
        "city": "Delhi",
        "proof": "file_3f9490b986924fab908456b920640244",
        "line_1": "E/&02",
        "line_2": "Opp SBI ATM",
        "line_3": "12th Main Road South Delhi",
        "country": "in",
        "pincode": "401012",
        "proof_back": "file_40e41f689f8b40bc81d006052d65ea8e1",
        "proof_type": "passport",
        "proof_number": "JXXXXXXA",
        "proof_issue_date": "2004-10-20",
        "proof_expiry_date": "2020-10-20"
      },
      "identity_proof": "file_899c33d4304e420ca38f68ffbde617c612",
      "residential_status": "resident_individual",
      "occupation_type": "private_sector",
      "created_at": "2019-11-09T13:26:38.946+0530",
      "updated_at": "2019-11-09T13:28:38.946+0530",
      "expires_at": "2019-11-14T13:26:38.946+0530",
      "esign_required_at": "2019-11-09T13:28:38.946+0530",
      "submitted_at": "2019-11-09T13:30:38.946+0530",
      "successful_at": null,
      "rejected_at": "2019-11-10T13:26:38.946+0530",
      "otp": "9bbf32",
      "geolocation": {
        "latitude": 12.354,
        "longitude": 77.453
      },
      "bank_account": {
        "account_holder_name": "Rani Gupta",
        "account_number": "919017057965811",
        "ifsc_code": "UTIB0003093",
        "proof": "file_3877919efa7f49c0b6f69e12793f0c2d12"
      },
      "requirements": {
        "fields_needed": [

        ]
      },
      "verification": {
        "status": "rejected",
        "details": {
          "pan": "data_mismatch",
          "signature": "data_missing",
          "address.proof": "document_unclear"
        },
        "details_verbose": {
          "pan": {
            "code": "data_mismatch",
            "reason": "Invalid pan"
          },
          "signature": {
            "code": "data_missing",
            "reason": "Signature not available"
          },
          "address.proof": {
            "code": "document_invalid",
            "reason": "Proof of address not valid; Translation into english is required"
          }
        }
      }
    },
    {
      "object": "kyc_request",
      "id": "kycr_724198d524004ceb8ba8203d06a32e26",
      "status": "pending",
      "aadhaar_number": "1210",
      "pan": "K1PPG1998U",
      "name": "Rani Gupta",
      "father_name": "Rajesh Gupta",
      "spouse_name": null,
      "mother_name": "Neha Gupta",
      "email": "rani@example.com",
      "mobile": {
        "isd": "+91",
        "number": "8160597103"
      },
      "signature": "file_9109577dfdc04c239e740684eed3d952",
      "photo": "file_872def4ecfe740af8d8f32de98b5fc01",
      "gender": "female",
      "date_of_birth": "1980-10-19",
      "marital_status": "unmarried",
      "country_of_birth": "in",
      "address": {
        "city": "Delhi",
        "proof": "file_3f9490b986924fab908456b920640245",
        "line_1": "E/&02",
        "line_2": "Opp SBI ATM",
        "line_3": "12th Main Road South Delhi",
        "country": "in",
        "pincode": "401012",
        "proof_back": "file_40e41f689f8b40bc81d006052d65ea8e",
        "proof_type": "passport",
        "proof_number": "JXXXXXXA",
        "proof_issue_date": "2004-10-20",
        "proof_expiry_date": "2020-10-20"
      },
      "identity_proof": "file_899c33d4304e420ca38f68ffbde617c6",
      "residential_status": "resident_individual",
      "occupation_type": "private_sector",
      "created_at": "2019-11-09T13:26:38.946+0530",
      "updated_at": "2019-11-09T13:28:38.946+0530",
      "expires_at": "2019-11-14T13:26:38.946+0530",
      "esign_required_at": null,
      "submitted_at": null,
      "successful_at": null,
      "rejected_at": null,
      "otp": "9bbf32",
      "geolocation": {
        "latitude": 12.354,
        "longitude": 77.453
      },
      "bank_account": {
        "account_holder_name": "Rani Gupta",
        "account_number": "919017057965811",
        "ifsc_code": "UTIB0003093",
        "proof": "file_3877919efa7f49c0b6f69e12793f0c2d"
      },
      "requirements": {
        "fields_needed": [
          "ipv_video"
        ]
      },
      "verification": {
        "status": "pending",
        "details": null,
        "details_verbose": null
      }
    }
  ]
}

The endpoint is used to fetch the list of KYC requests.

HTTP Request

GET /v2/kyc_requests

Query Parameters

Name Mandatory* Type Comments
pan No string PAN number
status No string Can be pending, esign_required, submitted, successful, rejected. Multiple values are supported by , seperator.

Update a kyc request

curl -X POST "https://s.finprim.com/v2/kyc_requests/kycr_724198d524004ceb8ba8203d06a32e26"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{json_request}'

JSON request:

{
  "ipv_video": "file_5b21c8f9786443159d7f2f217879d0d2"
}

The endpoint is used to update the details of a KYC request

JSON response:

{
  "object": "kyc_request",
  "id": "kycr_724198d524004ceb8ba8203d06a32e26",
  "status": "esign_required",
  "aadhaar_number": "1210",
  "pan": "K1PPG1998U",
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": null,
  "mother_name": "Neha Gupta",
  "email": "rani@example.com",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "signature": "file_9109577dfdc04c239e740684eed3d952",
  "photo": "file_872def4ecfe740af8d8f32de98b5fc01",
  "ipv_video": "file_5b21c8f9786443159d7f2f217879d0d2",
  "gender": "female",
  "date_of_birth": "1980-10-19",
  "marital_status": "unmarried",
  "country_of_birth": "in",
  "address": {
    "city": "Delhi",
    "proof": "file_3f9490b986924fab908456b920640245",
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "line_3": "12th Main Road South Delhi",
    "country": "in",
    "pincode": "401012",
    "proof_back": "file_40e41f689f8b40bc81d006052d65ea8e",
    "proof_type": "passport",
    "proof_number": "JXXXXXXA",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "identity_proof": "file_899c33d4304e420ca38f68ffbde617c6",
  "residential_status": "resident_individual",
  "occupation_type": "private_sector",
  "created_at": "2019-11-09T13:26:38.946+0530",
  "updated_at": "2019-11-09T13:28:38.946+0530",
  "expires_at": "2019-11-14T13:26:38.946+0530",
  "esign_required_at": null,
  "submitted_at": null,
  "successful_at": null,
  "rejected_at": null,
  "otp": "9bbf32",
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "file_3877919efa7f49c0b6f69e12793f0c2d"
  },
  "requirements": {
    "fields_needed": [

    ]
  },
  "verification": {
    "status": "esign_required",
    "details": null,
    "details_verbose": null
  }
}

HTTP Request

POST/PATCH /v2/kyc_requests/:id

Request/Response same as Create KYC Request

Simulate a kyc request

curl -X POST "https://s.finprim.com/v2/kyc_requests/kycr_724198d524004ceb8ba8203d06a32e26/simulate"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{json_request}'

JSON request:

{
  "status": "successful"
}

The endpoint is used to simulate the status of a KYC request

JSON response:

{
  "object": "kyc_request",
  "id": "kycr_724198d524004ceb8ba8203d06a32e26",
  "status": "successful",
  "aadhaar_number": "1210",
  "pan": "K1PPG1998U",
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": null,
  "mother_name": "Neha Gupta",
  "email": "rani@example.com",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "signature": "file_9109577dfdc04c239e740684eed3d952",
  "photo": "file_872def4ecfe740af8d8f32de98b5fc01",
  "ipv_video": "file_5b21c8f9786443159d7f2f217879d0d2",
  "gender": "female",
  "date_of_birth": "1980-10-19",
  "marital_status": "unmarried",
  "country_of_birth": "in",
  "address": {
    "city": "Delhi",
    "proof": "file_3f9490b986924fab908456b920640245",
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "line_3": "12th Main Road South Delhi",
    "country": "in",
    "pincode": "401012",
    "proof_back": "file_40e41f689f8b40bc81d006052d65ea8e",
    "proof_type": "passport",
    "proof_number": "JXXXXXXA",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "identity_proof": "file_899c33d4304e420ca38f68ffbde617c6",
  "residential_status": "resident_individual",
  "occupation_type": "private_sector",
  "created_at": "2019-11-09T13:26:38.946+0530",
  "updated_at": "2019-11-09T13:28:38.946+0530",
  "expires_at": "2019-11-14T13:26:38.946+0530",
  "esign_required_at": null,
  "submitted_at": null,
  "successful_at": null,
  "rejected_at": null,
  "otp": "9bbf32",
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "file_3877919efa7f49c0b6f69e12793f0c2d"
  },
  "requirements": {
    "fields_needed": [

    ]
  },
  "verification": {
    "status": "successful",
    "details": null,
    "details_verbose": null
  }
}

HTTP Request

POST /v2/kyc_requests/:id/simulate

Query Parameters

Name Mandatory* Type Comments
status yes string expected status of the kyc request. Values permtted: successful, rejected, expired. For successful or rejected, the KYC request must be in submitted state. For expired, the KYC request must be in pending or esign_required state

Identity Documents

This can be used to fetch a document and its details from an external source. You need to give the requesting entity details in order to fetch these details. Currently, the only supported requesting entity is a kyc_request object.

Endpoints:

POST /v2/identity_documents
GET /v2/identity_documents/:id
GET /v2/identity_documents

Identity Document Object

Identity Document Object

{
  "object": "identity_document",
  "id": "iddoc_20ecb2ee966a45b48ff2da70ec45ff01",
  "type": "aadhaar",
  "kyc_request": "kycr_96a0ccde4bb74ce6b79bab6b720d479c",
  "fetch": {
    "redirect_url": null,
    "postback_url": "https://fintechprimitives.com",
    "status": "successful",
    "reason": null,
    "expires_at": "2023-04-21T18:06:22+05:30"
  },
  "data": {
    "number": "0000000000000512",
    "line_1": "36TH CROSS SOUTH JAYANAGAR BENGALURU",
    "city": "Bengaluru",
    "pincode": "560041",
    "country": "in"
  },
  "created_at": "2023-04-21T17:06:22+05:30",
  "updated_at": "2023-04-21T17:08:22+05:30"
}

This object can be used to store a document and its details that are fetched from an external source.

Identity Document object attributes

Name Type Comments
object string Value is identity_document. String representing the object type. Objects of the same type share the same value
id string Unique identifier of the identity_document object
type string Type of the identity document
kyc_request string ID of the kyc_request object that consumes this identity document
fetch hash Stores the details on fetching an identity_document
data hash Stores the details that were fetched along with an associated identity document
created_at string Creation timestamp in ISO Local Date Time yyyy-MM-ddThh:mm:ss format
updated_at string Last updated timestamp in ISO Local Date Time yyyy-MM-ddThh:mm:ss format. This would indicate when the document fetching reached a final state

Identity Document Fetch hash attributes

Name Type Comments
redirect_url string URL to intiate document fetching
postback_url string URL to redirect the investor back, after document fetching workflow
status string Status of the document fetching. Possible values are pending, successful, failed and expired
reason string Reason for the fetching action to be in a current state. This would be present only in the failure scenarios
expires_at string Expiry timestamp of the redirect_url in ISO Local Date Time yyyy-MM-ddThh:mm:ss format. The URL would expire after 1 hour from creation

NOTE:
1. fetch.redirect_url will be null if fetch.status != pending
2. While redirecting to the postback_url, you will also receive the ID of the associated identity_document and the corresponding fetch.status
3. You can consume the last 4 digits of the Aadhaar number that would be present in the data hash to populate the kyc_request.aadhaar_number attribute
4. If fetch.redirect_url link is expired, then you would have to create a new identity_document object against the KYC Request
5. identity_document mapped to a KYC Request object cannot be reused for any other KYC Request object.

Create an Identity Document

curl -X POST "https://s.finprim.com/v2/identity_documents"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "kyc_request": "kycr_96a0ccde4bb74ce6b79bab6b720d479c",
  "type": "aadhaar",
  "postback_url": "https://fintechprimitives.com"
}

JSON Response

{
  "object": "identity_document",
  "id": "iddoc_20ecb2ee966a45b48ff2da70ec45ff01",
  "type": "aadhaar",
  "kyc_request": "kycr_96a0ccde4bb74ce6b79bab6b720d479c",
  "fetch": {
    "redirect_url": "https://s.finprim.com/v2/identity_documents/iddoc_20ecb2ee966a45b48ff2da70ec45ff01/redirect_to_digilocker",
    "postback_url": "https://fintechprimitives.com",
    "status": "pending",
    "reason": null,
    "expires_at": "2023-04-21T18:06:22+05:30"
  },
  "data": null,
  "created_at": "2023-04-21T17:06:22+05:30",
  "updated_at": "2023-04-21T17:08:22+05:30"
}

POST /v2/identity_documents

This API can be used to create a identity_document object.

Request Parameters

Name Mandatory Type Comments
kyc_request yes string ID of the KYC Request object where this identity document would be consumed
type yes string Type of the identity document that has to be fetched. Currently, the only supported value is aadhaar
postback_url yes string URL to redirect the investor back, after document fetching workflow

Fetch an Identity Document

curl -X GET "https://s.finprim.com/v2/identity_documents/iddoc_20ecb2ee966a45b48ff2da70ec45ff01"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "identity_document",
  "id": "iddoc_20ecb2ee966a45b48ff2da70ec45ff01",
  "type": "aadhaar",
  "kyc_request": "kycr_96a0ccde4bb74ce6b79bab6b720d479c",
  "fetch": {
    "redirect_url": null,
    "postback_url": "https://fintechprimitives.com",
    "status": "successful",
    "reason": null,
    "expires_at": "2023-04-21T18:06:22+05:30"
  },
  "data": {
    "number": "0000000000000512",
    "line_1": "36TH CROSS SOUTH JAYANAGAR BENGALURU",
    "city": "Bengaluru",
    "pincode": "560041",
    "country": "in"
  },
  "created_at": "2023-04-21T17:06:22+05:30",
  "updated_at": "2023-04-21T17:08:22+05:30"
}

GET /v2/identity_documents/:id

This API can be used to fetch the details of an identity document.

Query parameters

Name Mandatory Type Comments
id yes string ID of an identity_document object

List all Identity Documents

curl -X GET "https://s.finprim.com/v2/identity_documents"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "list",
  "data": [
    {
      "object": "identity_document",
      "id": "iddoc_20ecb2ee966a45b48ff2da70ec45ff01",
      "type": "aadhaar",
      "kyc_request": "kycr_96a0ccde4bb74ce6b79bab6b720d479c",
      "fetch": {
        "redirect_url": "https://s.finprim.com/v2/identity_documents/iddoc_20ecb2ee966a45b48ff2da70ec45ff01/redirect_to_digilocker",
        "postback_url": "https://fintechprimitives.com",
        "status": "pending",
        "reason": null,
        "expires_at": "2023-04-21T18:06:22+05:30"
      },
      "data": null,
      "created_at": "2023-04-21T17:06:22+05:30",
      "updated_at": "2023-04-21T17:08:22+05:30"
    },
    {
      "object": "identity_document",
      "id": "iddoc_fad581bbdf4441c5ae2eff48a88cec90",
      "type": "aadhaar",
      "kyc_request": "kycr_96a0ccde4bb74ce6b79bab6b720d479c",
      "fetch": {
        "redirect_url": null,
        "postback_url": "https://fintechprimitives.com",
        "status": "failed",
        "reason": "user cancelled",
        "expires_at": null
      },
      "data": null,
      "created_at": "2023-04-21T17:06:22+05:30",
      "updated_at": "2023-04-21T17:08:22+05:30"
    }
  ]
}

GET /v2/identity_documents

This API can be used to fetch all the identity documents.

Query parameters

Name Mandatory Type Comments
kyc_request no string id of an Identity Document
fetch.status no string status of the Identity Document fetch

NOTE: The response can contain 100 latest folios at max.

Esigns

Use this to complete the Esign process for the KYC request.

Endpoints:

POST /v2/esigns GET /v2/esigns/:id

Esign Object

{
  "object": "esign",
  "id": "8f05d378-3cf2-4e57-83c8-5ad767f21f12",
  "type": "aadhaar",
  "kyc_request": "c6b524ed-fcbd-4e37-9348-6fee95f7d997",
  "redirect_url": "http://s.finprim.com/v2/esigns/8f05d378-3cf2-4e57-83c8-5ad767f21f12/sign?token=ce825801-beab-4868-8fd8-5c4009e7f112",
  "status": "pending",
  "postback_url": "http://localhost:3000",
  "created_at": "2020-06-22T13:15:12.308+0530"
}
Attribute Type Comments
object string Value is esign. String representing the object type. Objects of the same type share the same value
id string Unique identifier of the esign object
type string Type of the esign. Can be aadhaar
kyc_request string KYC Request for which this esign is being processed for
redirect_url string Url for starting the esign process
status string Status of the esign. Can be pending, successful
postback_url string Url to which you will be redirected once esign process is complete
created_at string The timestamp at which the esign object is created

* The redirect_url can be used multiple times in case the user is not able to complete the esign process

Create an esign

curl -X POST "https://s.finprim.com/v2/esigns"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{json_request}'

JSON request:

{
  "kyc_request": "c6b524ed-fcbd-4e37-9348-6fee95f7d997",
  "postback_url": "http://localhost:3000"
}

JSON response:

{
  "object": "esign",
  "id": "8f05d378-3cf2-4e57-83c8-5ad767f21f12",
  "type": "aadhaar",
  "kyc_request": "c6b524ed-fcbd-4e37-9348-6fee95f7d997",
  "redirect_url": "http://s.finprim.com/v2/esigns/8f05d378-3cf2-4e57-83c8-5ad767f21f12/sign?token=ce825801-beab-4868-8fd8-5c4009e7f112",
  "status": "pending",
  "postback_url": "http://localhost:3000",
  "created_at": "2020-06-22T13:15:12.308+0530"
}

The endpoint is used to create an esign

HTTP Request

POST /v2/esigns

Query Parameters

Name Mandatory* Type Comments
kyc_request yes string id of the kyc_request to which it is related
postback_url yes string The URL to which you want be redirected once the esign process is complete.

Postback response

After the esign process is completed, we redirect the user to postback_url with the following query parameters

Name Value
esign id of the esign object
status status of the esign.

Fetch an esign

curl -X GET "https://s.finprim.com/v2/esigns/8f05d378-3cf2-4e57-83c8-5ad767f21f12"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON response:

{
  "object": "esign",
  "id": "8f05d378-3cf2-4e57-83c8-5ad767f21f12",
  "type": "aadhaar",
  "kyc_request": "c6b524ed-fcbd-4e37-9348-6fee95f7d997",
  "redirect_url": "http://s.finprim.com/v2/esigns/8f05d378-3cf2-4e57-83c8-5ad767f21f12/sign?token=ce825801-beab-4868-8fd8-5c4009e7f112",
  "status": "successful",
  "postback_url": "http://localhost:3000",
  "created_at": "2020-06-22T13:15:12.308+0530"
}

The endpoint is used to fetch an esign

HTTP Request

GET /v2/esigns/:id

Query Parameters

Name Mandatory* Type Comments
id yes string id of the esign

Files

Create a file

curl -X POST "https://s.finprim.com/files"
-H "x-tenant-id: <tenant name>"
-H "Authorization: Bearer JWTTOKEN"
-F
'
"file" : {file_to_upload}
'

The above command returns JSON structured like this:

{
  "object": "file",
  "id": "224f380c-d8f9-6f15-b2d9-27968a75f491",
  "created_at": "2018-05-13T17:53:58+05:30",
  "filename": "bob_dl_back.jpg",
  "content_type": "image/jpeg",
  "purpose": null,
  "byte_size": 4501312,
  "url": "https://files.fp.com/bob_dl_back.jpg"
}

Endpoint is used to upload POI, POA, photo, video, and signature files.

HTTP Request

POST https://s.finprim.com/files

Query Parameters

Parameter Mandatory Default Description
file yes - File must be in jpg, jpeg, png, mp4, webm, pdf and tiff format and size should not exceed 10MB.
purpose no - Notes.

Fetch a file

curl "https://s.finprim.com/files/870d11d1-c63b-41ca-362a-c8062f4efc71"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWTTOKEN"

Endpoint is used to fetch details of a particular file.

{
  "object": "file",
  "id": "224f380c-d8f9-6f15-b2d9-27968a75f491",
  "created_at": "2018-05-13T17:53:58+05:30",
  "filename": "bob_dl_back.jpg",
  "content_type": "image/jpeg",
  "purpose": null,
  "byte_size": 4501312,
  "url": "https://files.fp.com/bob_dl_back.jpg"
}

Endpoint is used to fetch details of a particular file.

HTTP Request

GET https://s.finprim.com/files/{id}

Query Parameters

Parameter Mandatory Default Description
id yes - file id returned from upload file api.

List all files

curl -X GET "https://s.finprim.com/files"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWTTOKEN"

Endpoint fetches the list of all the files.

{
  "object": "list",
  "data": [
    {
      "object": "file",
      "id": "d2784e7c-a414-4da8-954c-911fe425094a",
      "created_at": "2018-01-29T13:07:32+05:30",
      "filename": "file1.png",
      "content_type": "image/png",
      "purpose": "kyc approve document",
      "byte_size": 127343,
      "url": "https://files.fp.com/file1.png"
    },
    {
      "object": "file",
      "id": "81d631b2-4bc7-49b9-a11d-ff10110e484b",
      "created_at": "2018-01-29T13:44:56+05:30",
      "filename": "undraw_deliveries_131a.png",
      "content_type": "image/png",
      "purpose": "kyc document",
      "byte_size": 73441,
      "url": "https://files.fp.com/undraw_deliveries_131a.png"
    }
  ]
}

Endpoint fetches the list of all the files.

HTTP Request

GET https://s.finprim.com/files

Investor Profiles

The Investor Profile object lets you manage the profile information of the investor like addresses, bank accounts, contact details, FATCA declarations, and other demographic details.

NOTE: This is currently available only for customers who are transacting via the RTA route.

Endpoints:

POST /v2/investor_profiles
PATCH /v2/investor_profiles
GET /v2/investor_profiles/:id
GET /v2/investor_profiles

Investor Profile Object

Investor Profile Object

{
  "object": "investor_profile",
  "id": "invp_9abd706565144b83947f4b498bc95e98",
  "type": "individual",
  "tax_status": "resident_individual",
  "name": "Tony Soprano",
  "date_of_birth": "2002-09-18",
  "gender": "male",
  "occupation": "business",
  "pan": "DWEPS2837G",
  "guardian_name": null,
  "guardian_date_of_birth": null,
  "guardian_pan": null,
  "signature": null,
  "country_of_birth": "IN",
  "place_of_birth": "IN",
  "first_tax_residency": {
    "country": "IN",
    "taxid_type": "pan",
    "taxid_number": "DWEPS2837G"
  },
  "second_tax_residency": null,
  "third_tax_residency": null,
  "fourth_tax_residency": null,
  "source_of_wealth": "salary",
  "income_slab": "upto_1lakh",
  "pep_details": "not_applicable",
  "employer": null,
  "ip_address": "192.92.12.39",
  "created_at": "2022-07-07T10:28:53+05:30"
}

Investor profiles let you store information about a particular investor and use this information for a folio creation.

Investor object attributes

Attribute Type Comments
object string Value is investor_profile. String representing the object type. Objects of the same type share the same value
id string Unique identifier of the investor_profile object
type enum Allowed values are individual
tax_status enum Allowed values are resident_individual and nri
name string Name of the investor
date_of_birth string Date of birth of the investor
gender enum Allowed values are male, female, transgender
occupation enum Allowed values are business, professional, retired, house_wife, student, public_sector_service, private_sector_service, government_service, others, agriculture, doctor, forex_dealer, service
pan string Investor's PAN. Please note that PAN once set cannot be modified.
guardian_name string Name of the minor's guardian
guardian_date_of_birth string DOB of minor's guardian
guardian_pan string PAN of minor's guardian
signature string File ID to be passed here
country_of_birth string ANSI code of the birth country
place_of_birth string If country_of_birth=IN, then by default IN would be passed if no value is given
first_tax_residency hash Details of the investor's first tax residency
second_tax_residency hash Details of the investor's second tax residency
third_tax_residency hash Details of the investor's third tax residency
fourth_tax_residency hash Details of the investor's fourth tax residency
source_of_wealth enum Allowed values are - salary, business, gift, ancestral_property, rental_income, prize_money, royalty, others

NOTE: If investor.tax_status=resident_minor or investor.tax_status=non_resident_minor_nro, then Guardian's source of wealth to be mentioned here.
income_slab enum Investor's income slab.

Allowed values are - upto_1lakh, above_1lakh_upto_5lakh, above_5lakh_upto_10lakh, above_10lakh_upto_25lakh, above_25lakh_upto_1cr, above_1cr

NOTE: If investor.tax_status=resident_minor or investor.tax_status=non_resident_minor_nro, then Guardian's source of wealth to be mentioned here.
pep_details enum To determine if the investor is politically exposed or related to a politically exposed person.

Allowed values are - pep_exposed, pep_related, not_applicable
employer string Investor Profile ID of the employer

NOTE: The attribute employer is available under beta program. You can skip this attribute for folio creation
ip_address string IP address from where the request for investor_profile object creation was made
created_at string Creation timestamp

Tax residency hash

This hash will contain the details of an investor's tax residency. An investor can provide up to four tax residency details in the investor_profile object.

Name Type Remarks
country string ANSI code of the tax residency country
taxid_type enum Tax Identification type.

If country is IN, then allowed values are - passport, election_id, pan, id_card, driving_license, aadhaar_letter, nrega_job_card, others, not_categorized, tin

Else, allowed values are - passport, id_card, driving_license, others, not_categorized, tin
taxid_number string Tax Identification number issued against ID mentioned in taxid_type

Create an Investor Profile

curl -X POST "https://s.finprim.com/v2/investor_profiles"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "type": "individual",
  "tax_status": "resident_individual",
  "name": "Tony Soprano",
  "date_of_birth": "2002-09-18",
  "gender": "male",
  "occupation": "business",
  "pan": "DWEPS2837G",
  "country_of_birth": "IN",
  "place_of_birth": "IN",
  "use_default_tax_residences": "false",
  "first_tax_residency": {
    "country": "IN",
    "taxid_type": "pan",
    "taxid_number": "DWEPS2837G"
  },
  "source_of_wealth": "salary",
  "income_slab": "upto_1lakh",
  "pep_details": "not_applicable",
  "ip_address": "192.92.12.39"
}

JSON Response

{
  "object": "investor_profile",
  "id": "invp_9abd706565144b83947f4b498bc95e98",
  "type": "individual",
  "tax_status": "resident_individual",
  "name": "Tony Soprano",
  "date_of_birth": "2002-09-18",
  "gender": "male",
  "occupation": "business",
  "pan": "DWEPS2837G",
  "guardian_name": null,
  "guardian_date_of_birth": null,
  "guardian_pan": null,
  "signature": null,
  "country_of_birth": "IN",
  "place_of_birth": "IN",
  "first_tax_residency": {
    "country": "IN",
    "taxid_type": "pan",
    "taxid_number": "DWEPS2837G"
  },
  "second_tax_residency": null,
  "third_tax_residency": null,
  "fourth_tax_residency": null,
  "source_of_wealth": "salary",
  "income_slab": "upto_1lakh",
  "pep_details": "not_applicable",
  "employer": null,
  "ip_address": "192.92.12.39",
  "created_at": "2022-07-07T10:28:53+05:30"
}

POST /v2/investor_profiles

This API can be used to create an investor profile.

Request Parameters

Name Mandatory Type Comments
type yes enum Allowed values are individual
tax_status no enum If type=individual, then allowed values are resident_individual and nri

Once set, this cannot be modified
name no string This should not contain any special characters or numbers

Max character length is 70
date_of_birth no string This should be in the yyyy-mm-dd format

Once set, this cannot be modified
gender no enum Allowed values are male, female, transgender
occupation no enum Allowed values are business, professional, retired, house_wife, student, public_sector_service, private_sector_service, government_service, others, agriculture, doctor, forex_dealer, service
pan no string If type=individual, then the 4th character should always be p

To set a PAN, tax_status should be present
guardian_name no string This should not contain any special characters or numbers

Can be entered only if the investor's age < 18

Max character length is 80
guardian_date_of_birth no string Can be entered only if guardian_name is present
guardian_pan no string Can be entered only if guardian_name is present
signature no string Not applicable if the order processing gateway is rta
country_of_birth no string ANSI code of the birth country

Once set, this cannot be modified
place_of_birth no string If country_of_birth=IN, then by default IN would be passed if no other value is given. This would be a mandatory requirement if country_of_birth!=IN. Max character length is 60

Once set, this cannot be modified
use_default_tax_residences no boolean true - First tax residency [first_tax_residency] will be India and the Identification type will be PAN provided that PAN is not empty. Other tax residences will be empty.
false - Allows you to override all the existing tax residency details.

Default value for this input parameter would be false
first_tax_residency no hash Details of the investor's first tax residency
second_tax_residency no hash Details of the investor's second tax residency
third_tax_residency no hash Details of the investor's third tax residency
fourth_tax_residency no hash Details of the investor's fourth tax residency
source_of_wealth no enum Allowed values are - salary, business, gift, ancestral_property, rental_income, prize_money, royalty, others

NOTE: If tax_status=resident_minor or tax_status=non_resident_minor_nro, then Guardian's source of wealth to be mentioned here.
income_slab no enum Investor's income slab.

Allowed values are - upto_1lakh, above_1lakh_upto_5lakh, above_5lakh_upto_10lakh, above_10lakh_upto_25lakh, above_25lakh_upto_1cr, above_1cr
pep_details no enum To determine if the investor is politically exposed or related to a politically exposed person. Allowed values are - pep_exposed, pep_related, not_applicable
ip_address no string Provide IP address of the server through which the request to create this investor profile was made



Tax residency hash attributes

This hash will contain the details of an investor's tax residency. An investor can provide up to four tax residency details in the investor_profile object.

Name Mandatory Type Remarks
country yes string ANSI code of the tax residency country
taxid_type yes enum Tax Identification type.

If country is IN, then allowed values are - passport, election_id, pan, id_card, driving_license, aadhaar_letter, nrega_job_card, others, not_categorized, tin

Else, allowed values are - passport, id_card, driving_license, others, not_categorized, tin
taxid_number yes string Tax Identification number issued against ID mentioned in taxid_type


NOTE:

use_default_tax_residences is only an input parameter and not a part of the investor_profile object


A note on working with Tax Residences

Details of at least one tax residency are mandatory to submit FATCA, irrespective of the tax status. While creating or modifying an investor profile, you can ask FP to assume default tax residency details. In such cases, tax residency will be treated as India and PAN will be used as the Tax Identification type provided that the PAN number is present in the investor profile. Else, if you want to input tax residency details on your own, you can override this and provide custom tax residency details. You can make use of the use_default_tax_residences input parameter to control this behaviour while creating or modifying an investor profile.

first_tax_residency attributes Default values
country IN
taxid_type pan
taxid_number investor.pan


The default tax residency values can be set only for the resident_individual tax status. In cases of tax status being resident_minor or non_resident_minor_nro, the corresponding guardian's tax residency details are to be mentioned.

Modify an Investor Profile

curl -X PATCH "https://s.finprim.com/v2/investor_profiles"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "id": "invp_9abd706565144b83947f4b498bc95e98",
  "income_slab": "above_1lakh_upto_5lakh"
}

PATCH /v2/investor_profiles

This API can be used to modify an investor profile.

Body parameters

Name Mandatory Type Comments
id yes string ID of an investor_profile object

Other input parameters and response are same as Create an Investor Profile API

NOTE:

You cannot modify the attribute type that is present in the investor_profile object.

Fetch an Investor Profile

curl -X GET "https://s.finprim.com/v2/investor_profiles/invp_9abd706565144b83947f4b498bc95e98"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "investor_profile",
  "id": "invp_9abd706565144b83947f4b498bc95e98",
  "type": "individual",
  "tax_status": "resident_individual",
  "name": "Tony Soprano",
  "date_of_birth": "2002-09-18",
  "gender": "male",
  "occupation": "business",
  "pan": "DWEPS2837G",
  "guardian_name": null,
  "guardian_date_of_birth": null,
  "guardian_pan": null,
  "signature": null,
  "country_of_birth": "IN",
  "place_of_birth": "IN",
  "first_tax_residency": {
    "country": "IN",
    "taxid_type": "pan",
    "taxid_number": "DWEPS2837G"
  },
  "second_tax_residency": null,
  "third_tax_residency": null,
  "fourth_tax_residency": null,
  "source_of_wealth": "salary",
  "income_slab": "upto_1lakh",
  "pep_details": "not_applicable",
  "employer": null,
  "ip_address": "192.92.12.39",
  "created_at": "2022-07-07T10:28:53+05:30"
}

GET /v2/investor_profiles/:id

This API can be used to fetch an investor profile.

Query parameters

Name Mandatory Type Comments
id yes string ID of an investor profile

List all Investor Profiles

curl -X GET "https://s.finprim.com/v2/investor_profiles"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "list",
  "data": [
    {
      "object": "investor_profile",
      "id": "invp_9abd706565144b83947f4b498bc95e98",
      "type": "individual",
      "tax_status": "resident_individual",
      "name": "Tony Soprano",
      "date_of_birth": "2002-09-18",
      "gender": "male",
      "occupation": "business",
      "pan": "DWEPS2837G",
      "guardian_name": null,
      "guardian_date_of_birth": null,
      "guardian_pan": null,
      "signature": null,
      "country_of_birth": "IN",
      "place_of_birth": "IN",
      "first_tax_residency": {
        "country": "IN",
        "taxid_type": "pan",
        "taxid_number": "DWEPS2837G"
      },
      "second_tax_residency": null,
      "third_tax_residency": null,
      "fourth_tax_residency": null,
      "source_of_wealth": "salary",
      "income_slab": "upto_1lakh",
      "pep_details": "not_applicable",
      "employer": null,
      "ip_address": "192.92.12.39",
      "created_at": "2022-07-07T10:28:53+05:30"
    }
  ]
}

GET /v2/investor_profiles

This API can be used to fetch all the investor profiles.

Query parameters

Name Mandatory Type Comments
pan no string pan stored in the investor profile
type no string Type of the investor profile. It can be individual

NOTE: Either pan or type should be given as an input to retrieve a list of investor profiles.

Non Individual Investor Profiles (Early Access)

The Non Individuals Investor Profile object lets you manage the profile information of the non individual investor like addresses, bank accounts, contact details, tax residences, beneficial owners, FATCA declarations, and other demographic details.

Endpoints:

POST /v2/investor_profile_non_individuals
PATCH /v2/investor_profile_non_individuals
GET /v2/investor_profile_non_individuals/:id
GET /v2/investor_profile_non_individuals

Non Individual Investor Profile Object

Non Individual Investor Profile Object

{
  "object": "investor_profile_non_individual",
  "id": "invpni_4049b90a47d9494880a8ecaee3b140c5",
  "entity_name": "Test Pvt. Ltd.",
  "type": "private_limited",
  "residential_status": "resident",
  "pan": "DWECS2837G",
  "incorporation": {
    "date": "2012-08-12",
    "place": "Ahmedabad",
    "country": "IN",
    "business_started_from": "2010-10-01"
  },
  "networth": {
    "amount": "₹5.55Cr",
    "as_on": "2023-10-15"
  },
  "gross_annual_income": "above_1cr",
  "services_provided": {
    "foreign_exchange": false,
    "money_changer": false,
    "money_lending": false,
    "pawning": false,
    "gaming": false,
    "gambling": false,
    "lottery": false,
    "casino": false
  },
  "specified_us_person_exemption": "category_a",
  "entity_classification": "fi",
  "fi": {
    "giin": "0L1BZ6.00000.SL.000"
  },
  "ip_address": "192.168.29.100",
  "created_at": "2023-10-30T11:18:51+05:30"
}

Non Individual Investor profiles let you store information about a company and use this information for a folio creation.

Non Individual Investor object attributes

Attribute Type Comments
object string Value is investor_profile_non_individual. String representing the object type. Objects of the same type share the same value
id string Unique identifier of the investor_profile_non_individual object
entity_name string Name of the entity
type enum Allowed values are private_limited, public_limited
residential_status enum Allowed values are resident
pan string Company's PAN. Please note that PAN once set cannot be modified.
incorporation hash Details of the Company's incorporation
services_provided hash Details of the Company's services provided.
networth hash Details of the Company's networth
gross_annual_income enum Company's gross annual income.

Allowed values are - upto_1lakh, above_1lakh_upto_5lakh, above_5lakh_upto_10lakh, above_10lakh_upto_25lakh, above_25lakh_upto_1cr, above_1cr.
specified_us_person_exemption enum Allowed values are category_a, category_b, category_c, category_d, category_e, category_f, category_g, category_h, category_i, category_j, category_k, category_l, category_m
entity_classification enum Allowed values are fi, fi_sponsored, non_reporting_fi, direct_reporting_nfe, active_nfe, active_nfe_listed, active_nfe_related_to_listed, passive_nfe
fi hash NOTE: If entity_classification=fi then only this should be passed
fi_sponsored hash NOTE: If entity_classification=fi_sponsored then only this should be passed
non_reporting_fi hash NOTE: If entity_classification=non_reporting_fi then only this should be passed
direct_reporting_nfe hash NOTE: If entity_classification=direct_reporting_nfe then only this should be passed
active_nfe hash NOTE: If entity_classification=active_nfe then only this should be passed
active_nfe_listed hash NOTE: If entity_classification=active_nfe_listed then only this should be passed
active_nfe_related_to_listed hash NOTE: If entity_classification=active_nfe_related_to_listed then only this should be passed
passive_nfe hash NOTE: If entity_classification=passive_nfe then only this should be passed
ip_address string IP address from where the request for investor_profile_non_individual object creation was made
created_at string Creation timestamp

Incorporation hash

Attribute Type Comments
date string Date from which company was incorporated
place string Place of company
country string ANSI code of the country
business_started_from string Date from which company was started

Services provided hash

Attribute Type Comments
foreign_exchange boolean Is company providing any service related to foreign exchange
money_changer boolean Is company providing any service related to money changer
money_lending boolean Is company providing any service related to money lending
pawning boolean Is company providing any service related to pawning
gaming boolean Is company providing any service related to gaming
gambling boolean Is company providing any service related to gambling
lottery boolean Is company providing any service related to lottery
casino boolean Is company providing any service related to casino

Networth hash

Attribute Type Comments
amount string Networth of company. in currency+number+unit format

possible values are as below
currency: , INR
number: 1-5 places before decimal, 0-2 places after decimal;
unit: Cr, L
as_on string Date of networth, in yyyy-MM-dd format

Specified us person exemption details

Category Description
category_a An organization exempt from tax under section 501(a) or any individual retirement plan as defined in section 7701(a)(37)
category_b The United States or any of its agencies or instrumentalities
category_c A state, the District of Columbia, a possession of the United States, or any of their political subdivisions or instrumentalities
category_d A corporation the stock of which is regularly traded on one or more established securities markets, as described in Reg. section 1.1472-1(c)(1)(i)
category_e A corporation that is a member of the same expanded affiliated group as a corporation described in Reg. section 1.1472-1(c)(1)(i)
category_f A dealer in securities, commodities, or derivative financial instruments (including notional principal contracts, futures, forwards, and options) that is registered as such under the laws of the United States or any state
category_g A real estate investment trust
category_h A regulated investment company as defined in section 851 or an entity registered at all times during the tax year under the Investment Company Act of 1940
category_i A common trust fund as defined in section 584(a)
category_j A bank as defined in section 581
category_k A broker
category_l A trust exempt from tax under section 664 or described in section 4947(a)(1)
category_m A tax exempt trust under a section 403(b) plan or section 457(g) plan

Fi hash

Attribute Type Comments
giin string Actual giin number

Fi sponsored hash

Attribute Type Comments
sponsor_name string -
sponsor_giin string -

Non reporting fi hash

Attribute Type Comments
type enum Allowed values are governmental_entity, international_organisation, central_bank, treaty_qualified_retirement_fund, broad_participation_retirement_fund, narrow_participation_retirement_fund, governmental_entity_pension_fund, armed_forces_non_public_fund, employee_state_insurance_fund, gratuity_fund, provident_fund, indian_investment_entity, qualified_credit_card_issuer, specified_investment_advisor, investment_manager, executing_broker, exempt_collective_investment_vehicle, local_client_base_fi, local_bank, low_value_accounts_fi, sponsored_investment_entity, controlled_foreign_corporation, sponsored_closely_held_investment_vehicle

Direct reporting nfe hash

Attribute Type Comments
giin string Actual giin number

Passive nfe hash

Attribute Type Comments
nature_of_business string Nature of buisness

Active nfe hash

Attribute Type Comments
nature_of_business string Nature of buisness
type enum Allowed values are nfe_due_to_income_or_assets, nfe_government_entity, nfe_international_organisation, nfe_central_bank, nfe_holding_company, nfe_startup_company, nfe_in_liquidation, nfe_treasury_center, nfe_non_profit_organisation, nfe_religious, nfe_charitable, nfe_scientific, nfe_artistic, nfe_cultural, nfe_athletic, nfe_educational, nfe_professional_organisation, nfe_business_league, nfe_chamber_of_commerce, nfe_labor_organisation, nfe_agricultural, nfe_civic_league, nfe_social_welfare, nfe_it_exempt.

Active nfe listed hash

Attribute Type Comments
stock_exchange string
Attribute Type Comments
name string
relation enum Allowed values are subsidiary, controlled
stock_exchange string

Create an Non Individual Investor Profile

curl -X POST "https://s.finprim.com/v2/investor_profile_non_individuals"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "entity_name": "Test Pvt. Ltd.",
  "type": "private_limited",
  "residential_status": "resident",
  "pan": "DWECS2837G",
  "incorporation": {
    "date": "2012-08-12",
    "place": "Ahmedabad",
    "country": "IN",
    "business_started_from": "2010-10-01"
  },
  "networth": {
    "amount": "₹5.55Cr",
    "as_on": "2023-10-15"
  },
  "services_provided": {
    "foreign_exchange": false,
    "money_changer": false,
    "money_lending": false,
    "pawning": false,
    "gaming": false,
    "gambling": false,
    "lottery": false,
    "casino": false
  },
  "gross_annual_income": "above_1cr",
  "entity_classification": "fi",
  "fi": {
    "giin": "0L1BZ6.00000.SL.000"
  },
  "ip_address": "192.168.29.100"
}

JSON Response

{
  "object": "investor_profile_non_individual",
  "id": "invpni_4049b90a47d9494880a8ecaee3b140c5",
  "entity_name": "Test Pvt. Ltd.",
  "type": "private_limited",
  "residential_status": "resident",
  "pan": "DWECS2837G",
  "incorporation": {
    "date": "2012-08-12",
    "place": "Ahmedabad",
    "country": "IN",
    "business_started_from": "2010-10-01"
  },
  "networth": {
    "amount": "₹5.55Cr",
    "as_on": "2023-10-15"
  },
  "services_provided": {
    "foreign_exchange": false,
    "money_changer": false,
    "money_lending": false,
    "pawning": false,
    "gaming": false,
    "gambling": false,
    "lottery": false,
    "casino": false
  },
  "gross_annual_income": "above_1cr",
  "specified_us_person_exemption": null,
  "entity_classification": "fi",
  "fi": {
    "giin": "0L1BZ6.00000.SL.000"
  },
  "ip_address": "192.168.29.100",
  "created_at": "2023-10-30T11:18:51+05:30"
}

POST /v2/investor_profile_non_individuals

This API can be used to create an non individual investor profile.

Request Parameters

Name Mandatory Type Comments
entity_name yes string Name of the entity
type yes enum Allowed values are private_limited, public_limited
residential_status no enum Allowed values are resident
pan no string Company's PAN. Please note that PAN once set cannot be modified.
incorporation no hash Details of the Company's incorporation
services_provided no hash Details of the Company's services provided.
networth no hash Details of the Company's networth
gross_annual_income no enum Company's gross annual income.

Allowed values are - upto_1lakh, above_1lakh_upto_5lakh, above_5lakh_upto_10lakh, above_10lakh_upto_25lakh, above_25lakh_upto_1cr, above_1cr.
specified_us_person_exemption no enum Allowed values are category_a, category_b, category_c, category_d, category_e, category_f, category_g, category_h, category_i, category_j, category_k, category_l, category_m.Details
entity_classification no enum Allowed values are fi, fi_sponsored, non_reporting_fi, direct_reporting_nfe, active_nfe, active_nfe_listed, active_nfe_related_to_listed, passive_nfe
fi no hash NOTE: If entity_classification=fi then only this should be passed
fi_sponsored no hash NOTE: If entity_classification=fi_sponsored then only this should be passed
non_reporting_fi no hash NOTE: If entity_classification=non_reporting_fi then only this should be passed
direct_reporting_nfe no hash NOTE: If entity_classification=direct_reporting_nfe then only this should be passed
active_nfe no hash NOTE: If entity_classification=active_nfe then only this should be passed
active_nfe_listed no hash NOTE: If entity_classification=active_nfe_listed then only this should be passed
active_nfe_related_to_listed no hash NOTE: If entity_classification=active_nfe_related_to_listed then only this should be passed
passive_nfe no hash NOTE: If entity_classification=passive_nfe then only this should be passed
ip_address no string IP address from where the request for investor_profile_non_individual object creation was made

Incorporation hash attributes

Name Mandatory Type Comments
date no string Date from which company was incorporated
place no string Place of company
country no string ANSI code of the country
business_started_from no string Date from which company was started

Networth hash attributes

Name Mandatory Type Comments
amount no string Networth of company. in currency+number+unit format

possible values are as below
currency: , INR
number: 1-5 places before decimal, 0-2 places after decimal;
unit: Cr, L
as_on no string Date of networth, in yyyy-MM-dd format
This attribute is grouped with amount and both of these attributes have to be collected together.

Services provided hash attributes

Name Mandatory Type Comments
foreign_exchange no boolean Is company providing any service related to foreign exchange
money_changer no boolean Is company providing any service related to money changer
money_lending no boolean Is company providing any service related to money lending
pawning no boolean Is company providing any service related to pawning
gaming no boolean Is company providing any service related to gaming
gambling no boolean Is company providing any service related to gambling
lottery no boolean Is company providing any service related to lottery
casino no boolean Is company providing any service related to casino

Fi hash attributes

Name Mandatory Type Comments
giin yes string Actual giin number

Fi sponsored hash attributes

Name Mandatory Type Comments
sponsor_name string -
sponsor_giin string -

Non reporting fi hash attributes

Name Mandatory Type Comments
type yes enum Allowed values are governmental_entity, international_organisation, central_bank, treaty_qualified_retirement_fund, broad_participation_retirement_fund, narrow_participation_retirement_fund, governmental_entity_pension_fund, armed_forces_non_public_fund, employee_state_insurance_fund, gratuity_fund, provident_fund, indian_investment_entity, qualified_credit_card_issuer, specified_investment_advisor, investment_manager, executing_broker, exempt_collective_investment_vehicle, local_client_base_fi, local_bank, low_value_accounts_fi, sponsored_investment_entity, controlled_foreign_corporation, sponsored_closely_held_investment_vehicle

Direct reporting nfe hash attributes

Name Mandatory Type Comments
giin yes string Actual giin number

Passive nfe hash attributes

Name Mandatory Type Comments
nature_of_business yes string Nature of buisness

Active nfe hash attributes

Name Mandatory Type Comments
nature_of_business yes string Nature of buisness
type yes enum Allowed values are nfe_due_to_income_or_assets, nfe_government_entity, nfe_international_organisation, nfe_central_bank, nfe_holding_company, nfe_startup_company, nfe_in_liquidation, nfe_treasury_center, nfe_non_profit_organisation, nfe_religious, nfe_charitable, nfe_scientific, nfe_artistic, nfe_cultural, nfe_athletic, nfe_educational, nfe_professional_organisation, nfe_business_league, nfe_chamber_of_commerce, nfe_labor_organisation, nfe_agricultural, nfe_civic_league, nfe_social_welfare, nfe_it_exempt.

Active nfe listed hash attributes

Name Mandatory Type Comments
stock_exchange yes string
Name Mandatory Type Comments
name yes string
relation yes enum Allowed values are subsidiary, controlled
stock_exchange yes string

Modify an Non Individual Investor Profile

curl -X PATCH "https://s.finprim.com/v2/investor_profile_non_individuals"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "id": "invpni_4049b90a47d9494880a8ecaee3b140c5",
  "specified_us_person_exemption": "category_a"
}

JSON Response

{
  "object": "investor_profile_non_individual",
  "id": "invpni_4049b90a47d9494880a8ecaee3b140c5",
  "entity_name": "Test Pvt. Ltd.",
  "type": "private_limited",
  "residential_status": "resident",
  "pan": "DWECS2837G",
  "incorporation": {
    "date": "2012-08-12",
    "place": "Ahmedabad",
    "country": "IN",
    "business_started_from": "2010-10-01"
  },
  "networth": {
    "amount": "₹5.55Cr",
    "as_on": "2023-10-15"
  },
  "gross_annual_income": "above_1cr",
  "services_provided": {
    "foreign_exchange": false,
    "money_changer": false,
    "money_lending": false,
    "pawning": false,
    "gaming": false,
    "gambling": false,
    "lottery": false,
    "casino": false
  },
  "specified_us_person_exemption": "category_a",
  "entity_classification": "fi",
  "fi": {
    "giin": "0L1BZ6.00000.SL.000"
  },
  "ip_address": "192.168.29.100",
  "created_at": "2023-10-30T11:18:51+05:30"
}

PATCH /v2/investor_profile_non_individuals

This API can be used to modify an non individual investor profile.

Body parameters

Name Mandatory Type Comments
id yes string ID of an investor_profile_non_individual object

Other input parameters and response are same as Create an Non Individual Investor Profile API

NOTE:

You can only modify those attributes that are null.

Fetch an Non Individual Investor Profile

curl -X GET "https://s.finprim.com/v2/investor_profile_non_individuals/invpni_4049b90a47d9494880a8ecaee3b140c5"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "investor_profile_non_individual",
  "id": "invpni_4049b90a47d9494880a8ecaee3b140c5",
  "entity_name": "Test Pvt. Ltd.",
  "type": "private_limited",
  "residential_status": "resident",
  "pan": "DWECS2837G",
  "incorporation": {
    "date": "2012-08-12",
    "place": "Ahmedabad",
    "country": "IN",
    "business_started_from": "2010-10-01"
  },
  "networth": {
    "amount": "₹5.55Cr",
    "as_on": "2023-10-15"
  },
  "gross_annual_income": "above_1cr",
  "services_provided": {
    "foreign_exchange": false,
    "money_changer": false,
    "money_lending": false,
    "pawning": false,
    "gaming": false,
    "gambling": false,
    "lottery": false,
    "casino": false
  },
  "specified_us_person_exemption": "category_a",
  "entity_classification": "fi",
  "fi": {
    "giin": "0L1BZ6.00000.SL.000"
  },
  "ip_address": "192.168.29.100",
  "created_at": "2023-10-30T11:18:51+05:30"
}

GET /v2/investor_profile_non_individuals/:id

This API can be used to fetch an non individual investor profile.

Query parameters

Name Mandatory Type Comments
id yes string ID of an non individual investor profile

List all Non Individual Investor Profiles

curl -X GET "https://s.finprim.com/v2/investor_profile_non_individuals"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "list",
  "data": [
    {
      "object": "investor_profile_non_individual",
      "id": "invpni_4049b90a47d9494880a8ecaee3b140c5",
      "entity_name": "Test Pvt. Ltd.",
      "type": "private_limited",
      "residential_status": "resident",
      "pan": "DWECS2837G",
      "incorporation": {
        "date": "2012-08-12",
        "place": "Ahmedabad",
        "country": "IN",
        "business_started_from": "2010-10-01"
      },
      "networth": {
        "amount": "₹5.55Cr",
        "as_on": "2023-10-15"
      },
      "gross_annual_income": "above_1cr",
      "services_provided": {
        "foreign_exchange": false,
        "money_changer": false,
        "money_lending": false,
        "pawning": false,
        "gaming": false,
        "gambling": false,
        "lottery": false,
        "casino": false
      },
      "specified_us_person_exemption": "category_a",
      "entity_classification": "fi",
      "fi": {
        "giin": "0L1BZ6.00000.SL.000"
      },
      "ip_address": "192.168.29.100",
      "created_at": "2023-10-30T11:18:51+05:30"
    }
  ]
}

GET /v2/investor_profile_non_individuals

This API can be used to fetch all the non individual investor profiles.

Query parameters

Name Mandatory Type Comments
pan no string pan stored in the non individual investor profile
type no string Type of the non individaul investor profile.

NOTE: Either pan or type should be given as an input to retrieve a list of non individaul investor profiles.

Bank Accounts

Endpoints:

POST /v2/bank_accounts
PATCH /v2/bank_accounts
GET /v2/bank_accounts/:id
GET /v2/bank_accounts

Bank Account Object

Bank Account Object

{
  "object": "bank_account",
  "id": "bac_b58dca0f78d5432c907a85c8f8a1139e",
  "old_id": 906,
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "primary_account_holder_name": "Tony Soprano",
  "account_number": "98123459204",
  "type": "savings",
  "ifsc_code": "HDFC0001330",
  "branch_name": "THE MALL CHHOTI BARADARI",
  "bank_name": "HDFC BANK",
  "branch_address": "3THE MALLCHHOTI BARADARI",
  "branch_contact_number": "9815331111",
  "branch_city": "PATIALA",
  "branch_district": "PATIALA",
  "branch_state": "PUNJAB",
  "cancelled_cheque": null,
  "sole_proprietorship": "sopr_1985fcb8f9ae4623b7720a151b58b924",
  "created_at": "2022-12-06T12:10:36+05:30"
}

This will contain the bank account details of the investor corresponding to the id of the linked investor_profile object.

Bank Account Object attributes

Name Type Comments
object string Value is bank_account. String representing the object type. Objects of the same type share the same value
id string Unique identifier of the bank_account object
old_id integer This is the numeric ID of this bank_account object. We have provided this as some of our APIs use this ID like in Payments and Mandate APIs.
profile string ID of the Investor profile to which this bank account belongs to
primary_account_holder_name string Primary account holder name
account_number string Bank account number
type string Allowed values are - savings, current, nre, nro
ifsc_code string IFSC code of the branch in which this bank account is present
branch_name string Branch name
bank_name string Bank name
branch_address string Branch address
branch_contact_number string Branch contact number
branch_city string Branch city
branch_district string Branch district
branch_state string Branch state
cancelled_cheque string V2 File ID of the cancelled cheque
sole_proprietorship string V2 ID of a sole_proprietorship object.

NOTE: The attribute sole_proprietorship is available under beta program.
created_at string Creation timestamp

Create a Bank Account

curl -X POST "https://s.finprim.com/v2/bank_accounts"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "primary_account_holder_name": "Tony Soprano",
  "account_number": "98123459204",
  "type": "savings",
  "ifsc_code": "HDFC0001330",
  "sole_proprietorship": "sopr_1985fcb8f9ae4623b7720a151b58b924"
}

JSON Response

{
  "object": "bank_account",
  "id": "bac_b58dca0f78d5432c907a85c8f8a1139e",
  "old_id": 906,
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "primary_account_holder_name": "Tony Soprano",
  "account_number": "98123459204",
  "type": "savings",
  "ifsc_code": "HDFC0001330",
  "branch_name": "THE MALL CHHOTI BARADARI",
  "bank_name": "HDFC BANK",
  "branch_address": "3THE MALLCHHOTI BARADARI",
  "branch_contact_number": "9815331111",
  "branch_city": "PATIALA",
  "branch_district": "PATIALA",
  "branch_state": "PUNJAB",
  "cancelled_cheque": null,
  "sole_proprietorship": "sopr_1985fcb8f9ae4623b7720a151b58b924",
  "created_at": "2022-12-06T12:10:36+05:30"
}

POST /v2/bank_accounts

This API can be used to create a bank_account object.

Request Parameters

Name Mandatory Type Comments
profile yes string ID of the Investor profile to which this bank account belongs to.

Once set, this cannot be modified.
account_number yes string Bank account number This should only contain integer
Min and Max character length is 9 and 18

Once set, this cannot be modified.
primary_account_holder_name yes string Primary account holder name

Once set, this cannot be modified.
type yes string Allowed values are - savings, current, nre, nro

Once set, this cannot be modified.
ifsc_code yes string IFSC code of the branch in which this bank account is present.

Once set, this cannot be modified.
cancelled_cheque no string File ID of the cancelled cheque
sole_proprietorship no string ID of a sole_proprietorship object

Modify a Bank Account

curl -X PATCH "https://s.finprim.com/v2/bank_accounts"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "id": "bac_b58dca0f78d5432c907a85c8f8a1139e",
  "cancelled_cheque": "file_98367e8972b43867a9c68a7c4605a31d"
}

JSON Response

{
  "object": "bank_account",
  "id": "bac_b58dca0f78d5432c907a85c8f8a1139e",
  "old_id": 906,
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "primary_account_holder_name": "Tony Soprano",
  "account_number": "98123459204",
  "type": "savings",
  "ifsc_code": "HDFC0001330",
  "branch_name": "THE MALL CHHOTI BARADARI",
  "bank_name": "HDFC BANK",
  "branch_address": "3THE MALLCHHOTI BARADARI",
  "branch_contact_number": "9815331111",
  "branch_city": "PATIALA",
  "branch_district": "PATIALA",
  "branch_state": "PUNJAB",
  "cancelled_cheque": "file_98367e8972b43867a9c68a7c4605a31d",
  "sole_proprietorship": "sopr_1985fcb8f9ae4623b7720a151b58b924",
  "created_at": "2022-12-06T12:10:36+05:30"
}

PATCH /v2/bank_accounts

This API can be used to modify the details of a bank account object. You can add and modify cancelled cheque for a bank account object.

Body parameters

Name Mandatory Type Comments
id yes string ID of a bank_account object
cancelled_cheque yes string File ID of the cancelled cheque


NOTE:

For a given bank_account object, at any given time you cannot modify any other attributes other than cancelled_cheque


Fetch a Bank Account

curl -X GET "https://s.finprim.com/v2/bank_accounts/bac_b58dca0f78d5432c907a85c8f8a1139e"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "bank_account",
  "id": "bac_b58dca0f78d5432c907a85c8f8a1139e",
  "old_id": 906,
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "primary_account_holder_name": "Tony Soprano",
  "account_number": "98123459204",
  "type": "savings",
  "ifsc_code": "HDFC0001330",
  "branch_name": "THE MALL CHHOTI BARADARI",
  "bank_name": "HDFC BANK",
  "branch_address": "3THE MALLCHHOTI BARADARI",
  "branch_contact_number": "9815331111",
  "branch_city": "PATIALA",
  "branch_district": "PATIALA",
  "branch_state": "PUNJAB",
  "cancelled_cheque": null,
  "sole_proprietorship": "sopr_1985fcb8f9ae4623b7720a151b58b924",
  "created_at": "2022-12-06T12:10:36+05:30"
}

GET /v2/bank_accounts/:id

This API can be used to fetch the details of a bank account.

Query parameters

Name Mandatory Type Comments
id yes string ID of a bank_account object

List all Bank Accounts

curl -X GET "https://s.finprim.com/v2/bank_accounts"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "list",
  "data": [
    {
      "object": "bank_account",
      "id": "bac_b58dca0f78d5432c907a85c8f8a1139e",
      "profile": "invp_9abd706565144b83947f4b498bc95e98",
      "old_id": 906,
      "primary_account_holder_name": "Tony Soprano",
      "account_number": "98123459204",
      "type": "savings",
      "ifsc_code": "HDFC0001330",
      "branch_name": "THE MALL CHHOTI BARADARI",
      "bank_name": "HDFC BANK",
      "branch_address": "3THE MALLCHHOTI BARADARI",
      "branch_contact_number": "9815331111",
      "branch_city": "PATIALA",
      "branch_district": "PATIALA",
      "branch_state": "PUNJAB",
      "cancelled_cheque": null,
      "sole_proprietorship": "sopr_1985fcb8f9ae4623b7720a151b58b924",
      "created_at": "2022-12-06T12:10:36+05:30"
    }
  ]
}

GET /v2/bank_accounts

This API can be used to fetch all the bank accounts.

Query parameters

Name Mandatory Type Comments
profile yes string id of an investor profile

Addresses

Endpoints:

POST /v2/addresses
PATCH /v2/addresses
GET /v2/addresses/:id
GET /v2/addresses

Address Object

Address Object

{
  "object": "address",
  "id": "addr_4a9ac8e2c88b40be8a0470534d5499d6",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "line1": "342, 2nd main, 1st cross",
  "line2": "JP Nagar 2nd phase",
  "line3": null,
  "city": "Bengaluru",
  "state": "KARNATAKA",
  "postal_code": "560078",
  "country": "IN",
  "nature": "residential",
  "created_at": "2022-12-06T12:19:36+05:30"
}

This object can be used to store an investor's address details.

Address object attributes

Name Type Comments
object string Value is address. String representing the object type. Objects of the same type share the same value
id string Unique identifier of the address object
profile string ID of the Investor profile to which this address belongs to
line1 string Address line 1
line2 string Address line 2
line3 string Address line 3
city string City
state string State
postal_code string Pincode
country string Country ANSI Code
nature enum Allowed values for investor_profile are residential, business_location.
Allowed values for investor_profile_non_individual are registered_office, business_location
created_at string Creation timestamp

Create an Address

POST /v2/addresses

curl -X POST "https://s.finprim.com/v2/addresses"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "line1": "342, 2nd main, 1st crosss",
  "line2": "JP Nagar 2nd phase",
  "country": "IN",
  "postal_code": "560078",
  "nature": "residential"
}

JSON Response

{
  "object": "address",
  "id": "addr_4a9ac8e2c88b40be8a0470534d5499d6",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "line1": "342, 2nd main, 1st cross",
  "line2": "JP Nagar 2nd phase",
  "line3": null,
  "city": "Bengaluru",
  "state": "KARNATAKA",
  "postal_code": "560078",
  "country": "IN",
  "nature": "residential",
  "created_at": "2022-12-06T12:19:36+05:30"
}

This API can be used to create an address object.

Request Parameters

Name Mandatory Type Comments
profile yes string ID of the Investor profile to which this address belongs to.

Once set, this cannot be modified.
line1 yes string Address line 1

Once set, this cannot be modified.
line2 no string Address line 2

Once set, this cannot be modified.
line3 no string Address line 3

Once set, this cannot be modified.
city no string City

Once set, this cannot be modified.
state no string State

Once set, this cannot be modified.
postal_code yes string Pincode

Once set, this cannot be modified.
country yes string Country ANSI Code

Once set, this cannot be modified.
nature no enum Allowed values for investor_profile are residential, business_location.
Allowed values for investor_profile_non_individual are registered_office, business_location.
Once set, this cannot be modified.


If country=IN and an Indian postal_code is mentioned, the fields - city and state would be auto-populated from the postal_code provided.

Modify an Address

curl -X PATCH "https://s.finprim.com/v2/addresses"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "id": "addr_4a9ac8e2c88b40be8a0470534d5499d6",
  "line3": "RK Colony"
}

JSON Response

{
  "object": "address",
  "id": "addr_4a9ac8e2c88b40be8a0470534d5499d6",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "line1": "342, 2nd main, 1st cross",
  "line2": "JP Nagar 2nd phase",
  "line3": "RK Colony",
  "city": "Bengaluru",
  "state": "KARNATAKA",
  "postal_code": "560078",
  "country": "IN",
  "nature": "residential",
  "created_at": "2022-12-06T12:19:36+05:30"
}

PATCH /v2/addresses

This API can be used to modify the details of an address object. All the non-mandatory paramters can be added using this API, but once set they cannot be modified .

Body parameters

Name Mandatory Type Comments
id yes string ID of an address object

Other input parameters are same as Create an Address API

Fetch an Address

curl -X GET "https://s.finprim.com/v2/addresses/addr_4a9ac8e2c88b40be8a0470534d5499d6"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "address",
  "id": "addr_4a9ac8e2c88b40be8a0470534d5499d6",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "line1": "342, 2nd main, 1st cross",
  "line2": "JP Nagar 2nd phase",
  "line3": null,
  "city": "Bengaluru",
  "state": "KARNATAKA",
  "postal_code": "560078",
  "country": "IN",
  "nature": "residential",
  "created_at": "2022-12-06T12:19:36+05:30"
}

GET /v2/addresses/:id

This API can be used to fetch the details of an address.

Query parameters

Name Mandatory Type Comments
id yes string ID of an address object

List all Addresses

curl -X GET "https://s.finprim.com/v2/addresses"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "list",
  "data": [
    {
      "object": "address",
      "id": "addr_4a9ac8e2c88b40be8a0470534d5499d6",
      "profile": "invp_9abd706565144b83947f4b498bc95e98",
      "line1": "342, 2nd main, 1st crosss",
      "line2": "JP Nagar 2nd phase",
      "line3": null,
      "city": "Bengaluru",
      "state": "KARNATAKA",
      "postal_code": "560078",
      "country": "IN",
      "nature": "residential",
      "created_at": "2022-12-06T12:19:36+05:30"
    }
  ]
}

GET /v2/addresses

This API can be used to fetch all the addresses.

Query parameters

Name Mandatory Type Comments
profile yes string id of an investor profile

Phone Numbers

Endpoints:

POST /v2/phone_numbers
PATCH /v2/phone_numbers
GET /v2/phone_numbers/:id
GET /v2/phone_numbers

Phone Number Object

Phone Number Object

{
  "object": "phone_number",
  "id": "phone_0f4a90134705474eb2e354d9b5ba5f56",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "isd": "91",
  "number": "9012893478",
  "belongs_to": "self",
  "created_at": "2022-12-06T12:19:36+05:30"
}

This object can be used to store an investor's phone number.

Phone Number object attributes

Name Type Comments
object string Value is phone_number. String representing the object type. Objects of the same type share the same value
id string Unique identifier of the phone_number object
profile string ID of the Investor profile to which this phone number is linked to
isd string ISD code of the phone number
number string Phone number
belongs_to enum Indicate to whom this phone number belongs to

Allowed values are self, spouse, dependent_children, dependent_siblings, dependent_parents, guardian, pms, custodian, poa
created_at string Creation timestamp

Create a Phone Number

curl -X POST "https://s.finprim.com/v2/phone_numbers"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "isd": "91",
  "number": "9012893478"
}

JSON Response

{
  "object": "phone_number",
  "id": "phone_0f4a90134705474eb2e354d9b5ba5f56",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "isd": "91",
  "number": "9012893478",
  "belongs_to": null,
  "created_at": "2022-12-06T12:19:36+05:30"
}

POST /v2/phone_numbers

This API can be used to create a phone_number object.

Request Parameters

Name Mandatory Type Comments
profile yes string ID of the Investor profile to which this phone number is linked to.

Once set, this cannot be modified.
isd yes string ISD code of the phone number. Only integers are allowed, also + can be added at the start.
Max character length is 4 including +

Once set, this cannot be modified.
number yes string Phone number Only integers and - are allowed
Min and Max character length is 7 and 20

Once set, this cannot be modified.
belongs_to no enum Indicates to whom this phone number belongs to. Once set, this cannot be modified.

Allowed values are self, spouse, dependent_children, dependent_siblings, dependent_parents, guardian, pms, custodian, poa

Modify a Phone Number

curl -X PATCH "https://s.finprim.com/v2/phone_numbers"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "id": "phone_0f4a90134705474eb2e354d9b5ba5f56",
  "belongs_to": "self"
}

JSON Response

{
  "object": "phone_number",
  "id": "phone_0f4a90134705474eb2e354d9b5ba5f56",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "isd": "91",
  "number": "9012893478",
  "belongs_to": "self",
  "created_at": "2022-12-06T12:19:36+05:30"
}

PATCH /v2/phone_numbers

This API can be used to modify a phone number object. You can add belongs_to for an email address object but once set this cannot be modified.

Body parameters

Name Mandatory Type Comments
id yes string ID of a phone_number object
belongs_to yes string Indicates to whom this phone number belongs to. Once set, this cannot be modified.

Allowed values are self, spouse, dependent_children, dependent_siblings, dependent_parents, guardian, pms, custodian, poa

Fetch a Phone Number

curl -X GET "https://s.finprim.com/v2/phone_numbers/phone_0f4a90134705474eb2e354d9b5ba5f56"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "phone_number",
  "id": "phone_0f4a90134705474eb2e354d9b5ba5f56",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "isd": "91",
  "number": "9012893478",
  "belongs_to": "self",
  "created_at": "2022-12-06T12:19:36+05:30"
}

GET /v2/phone_numbers/:id

This API can be used to fetch the details of a phone number.

Query parameters

Name Mandatory Type Comments
id yes string ID of a phone_number object

List all Phone Numbers

curl -X GET "https://s.finprim.com/v2/phone_numbers"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "list",
  "data": [
    {
      "object": "phone_number",
      "id": "phone_0f4a90134705474eb2e354d9b5ba5f56",
      "profile": "invp_9abd706565144b83947f4b498bc95e98",
      "isd": "91",
      "number": "9012893478",
      "belongs_to": "self",
      "created_at": "2022-12-06T12:19:36+05:30"
    }
  ]
}

GET /v2/phone_numbers

This API can be used to fetch all the phone numbers.

Query parameters

Name Mandatory Type Comments
profile yes string id of an investor profile

Email Addresses

Endpoints:

POST /v2/email_addresses
PATCH /v2/email_addresses
GET /v2/email_addresses/:id
GET /v2/email_addresses

Email Address Object

Email Address Object

{
  "object": "email_address",
  "id": "email_122133976adb4f3083e25da895e99293",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "email": "tony.soprano@gmail.com",
  "belongs_to": "self",
  "created_at": "2022-12-06T12:19:36+05:30"
}

This object can be used to store an investor's email addresses.

Email Address object attributes

Name Type Comments
object string Value is email_address. String representing the object type. Objects of the same type share the same value
id string Unique identifier of the email_address object
profile string ID of the Investor profile to which this email address is linked to
email string Email address
belongs_to enum Indicate to whom this email address belongs to

Allowed values are self, spouse, dependent_children, dependent_siblings, dependent_parents, guardian, pms, custodian, poa
created_at string Creation timestamp

Create an Email Address

curl -X POST "https://s.finprim.com/v2/email_addresses"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "email": "tony.soprano@gmail.com"
}

JSON Response

{
  "object": "email_address",
  "id": "email_122133976adb4f3083e25da895e99293",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "email": "tony.soprano@gmail.com",
  "belongs_to": null,
  "created_at": "2022-12-06T12:19:36+05:30"
}

POST /v2/email_addresses

This API can be used to create a email_address object.

Request Parameters

Name Mandatory Type Comments
profile yes string ID of the Investor profile to which this email address is linked to.

Once set, this cannot be modified.
email yes string Email address

Once set, this cannot be modified.
belongs_to no enum Indicates to whom this email address belongs to. Once set, this cannot be modified.

Allowed values are self, spouse, dependent_children, dependent_siblings, dependent_parents, guardian, pms, custodian, poa

Modify an Email Address

curl -X PATCH "https://s.finprim.com/v2/email_addresses"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "id": "email_122133976adb4f3083e25da895e99293",
  "belongs_to": "self"
}

JSON Response

{
  "object": "email_address",
  "id": "email_122133976adb4f3083e25da895e99293",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "email": "tony.soprano@gmail.com",
  "belongs_to": "self",
  "created_at": "2022-12-06T12:19:36+05:30"
}

PATCH /v2/email_addresses

This API can be used to modify an email address object. You can add belongs_to for an email address object but once set this cannot be modified.

Body parameters

Name Mandatory Type Comments
id yes string ID of an email_address object
belongs_to yes string Indicates to whom this email address belongs to. Once set, this cannot be modified.

Allowed values are self, spouse, dependent_children, dependent_siblings, dependent_parents, guardian, pms, custodian, poa

Fetch an Email Address

curl -X GET "https://s.finprim.com/v2/email_addresses/email_122133976adb4f3083e25da895e99293"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "email_address",
  "id": "email_122133976adb4f3083e25da895e99293",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "email": "tony.soprano@gmail.com",
  "belongs_to": "self",
  "created_at": "2022-12-06T12:19:36+05:30"
}

GET /v2/email_addresses/:id

This API can be used to fetch the details of an email address.

Query parameters

Name Mandatory Type Comments
id yes string ID of an email_address object

List all Email Addresses

curl -X GET "https://s.finprim.com/v2/email_addresses"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "list",
  "data": [
    {
      "object": "email_address",
      "id": "email_122133976adb4f3083e25da895e99293",
      "profile": "invp_9abd706565144b83947f4b498bc95e98",
      "email": "tony.soprano@gmail.com",
      "belongs_to": "self",
      "created_at": "2022-12-06T12:19:36+05:30"
    }
  ]
}

GET /v2/email_addresses

This API can be used to fetch all the email addresses.

Query parameters

Name Mandatory Type Comments
profile yes string id of an investor profile

Related Parties

Endpoints:

POST /v2/related_parties
PATCH /v2/related_parties
GET /v2/related_parties/:id
GET /v2/related_parties

JSON Response

{
  "object": "related_party",
  "id": "relp_3c1f0c0b0f15474e90baf9f32692c6eb",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "name": "James Soprano",
  "pan": "ASFPJ2398R",
  "date_of_birth": "1972-02-29",
  "relationship": "father",
  "guardian_name": null,
  "guardian_pan": null,
  "created_at": "2022-12-06T12:26:41+05:30"
}

This object can be used to store any person or a party related to an investor. These related parties could be used for nominations declared by the investor.

Name Type Comments
object string Value is related_party. String representing the object type. Objects of the same type share the same value
id string Unique identifier of the related_party object
profile string ID of the Investor profile to which this party is related to
name string Name of the related party
pan string PAN of the related party
date_of_birth date Date of birth of the related party
relationship string Relation of this party with the investor
guardian_name string Name of the Guardian if the related party is a minor
guardian_pan string PAN of the Guardian if the related party is a minor
created_at string Creation timestamp
curl -X POST "https://s.finprim.com/v2/related_parties"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "name": "James Soprano",
  "date_of_birth": "1972-02-29",
  "relationship": "father"
}

JSON Response

{
  "object": "related_party",
  "id": "relp_3c1f0c0b0f15474e90baf9f32692c6eb",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "name": "James Soprano",
  "pan": null,
  "date_of_birth": "1972-02-29",
  "relationship": "father",
  "guardian_name": null,
  "guardian_pan": null,
  "created_at": "2022-12-06T12:26:41+05:30"
}

POST /v2/related_parties

This API can be used to create a related_party object.

Request Parameters

Name Mandatory Type Comments
profile yes string ID of the Investor profile to which this party is related to.

Once set, this cannot be modified.
name yes string Name of the related party. This should not contain any special characters or numbers.
Max character length is 40

Once set, this cannot be modified.
pan no string PAN of the related party

Once set, this cannot be modified.
date_of_birth no date Date of birth of the related party. This should be given in the format yyyy-mm-dd

Once set, this cannot be modified.
relationship yes string Relation of this party with the investor. This should not contain any special characters or numbers.
Max character length is 25

Once set, this cannot be modified.
guardian_name no string Name of the Guardian Only allowed to enter when the related party is a minor. This attribute is grouped with guardian_pan and both of these attributes have to be collected together. This should not contain any special characters or numbers.
Max character length is 35

Once set, this cannot be modified.
guardian_pan no string PAN of the Guardian Only allowed to enter when the related party is a minor. This attribute is grouped with guardian_name and both of these attributes have to be collected together.

Once set, this cannot be modified.
curl -X PATCH "https://s.finprim.com/v2/related_parties"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "id": "relp_3c1f0c0b0f15474e90baf9f32692c6eb",
  "pan": "ASFPJ2398R"
}

JSON Response

{
  "object": "related_party",
  "id": "relp_3c1f0c0b0f15474e90baf9f32692c6eb",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "name": "James Soprano",
  "pan": "ASFPJ2398R",
  "date_of_birth": "1972-02-29",
  "relationship": "father",
  "guardian_name": null,
  "guardian_pan": null,
  "created_at": "2022-12-06T12:26:41+05:30"
}

PATCH /v2/related_parties

This API can be used to modify the details of a related party object. All the non-mandatory paramters can be added using this API, but once set they cannot be modified .

Body parameters

Name Mandatory Type Comments
id yes string ID of a related_party object

Other input parameters and the response are same as Create a Related Party API

curl -X GET "https://s.finprim.com/v2/related_parties/relp_3c1f0c0b0f15474e90baf9f32692c6eb"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "related_party",
  "id": "relp_3c1f0c0b0f15474e90baf9f32692c6eb",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "name": "James Soprano",
  "pan": "ASFPJ2398R",
  "date_of_birth": "1972-02-29",
  "relationship": "father",
  "guardian_name": null,
  "guardian_pan": null,
  "created_at": "2022-12-06T12:26:41+05:30"
}

GET /v2/related_parties/:id

This API can be used to fetch the details of a related party.

Query parameters

Name Mandatory Type Comments
id yes string ID of a related_party object
curl -X GET "https://s.finprim.com/v2/related_parties"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "list",
  "data": [
    {
      "object": "related_party",
      "id": "relp_3c1f0c0b0f15474e90baf9f32692c6eb",
      "profile": "invp_9abd706565144b83947f4b498bc95e98",
      "name": "James Soprano",
      "pan": "ASFPJ2398R",
      "date_of_birth": "1972-02-29",
      "relationship": "father",
      "guardian_name": null,
      "guardian_pan": null,
      "created_at": "2022-12-06T12:26:41+05:30"
    }
  ]
}

GET /v2/related_parties

This API can be used to fetch all the related parties.

Query parameters

Name Mandatory Type Comments
profile yes string id of an investor profile

Demat Accounts

End Points
POST /v2/demat_accounts
GET /v2/demat_accounts/:id
GET /v2/demat_accounts?profile={profile}

Demat Account Object

Demat Account Object

{
  "object": "demat_account",
  "id": "dac_156e3c3bb66e447d8fe7e44d7d941f5a",
  "profile": "invp_ef68993a907b48849a02b403fab8da7f",
  "dp_id": "12081800",
  "client_id": "04571343",
  "created_at": "2023-05-25T14:09:05+05:30"
}

This will contain the demat accounts related to an investor.

Note: Demat account needs to be created with the broker\depositary participant. This object helps in associating an already created demat account to an investor in FP.

Demat Account Object attributes

Name Type Comments
object string Value is demat_account. String representing the object type. Objects of the same type share the same value
id string Unique identifier of the demat_account object
profile string ID of the Investor profile to which this demat account belongs to
dp_id string Depository participant ID
client_id string Client ID
created_at string Creation timestamp

Create a Demat Account Object

curl -X POST "https://s.finprim.com/v2/demat_accounts"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "profile": "invp_ef68993a907b48849a02b403fab8da7f",
  "dp_id": "12081800",
  "client_id": "04571343"
}

JSON Response

{
  "object": "demat_account",
  "id": "dac_156e3c3bb66e447d8fe7e44d7d941f5a",
  "profile": "invp_ef68993a907b48849a02b403fab8da7f",
  "dp_id": "12081800",
  "client_id": "04571343",
  "created_at": "2023-05-25T14:09:05+05:30"
}

POST /v2/demat_accounts

This API can be used to create a demat_account object.

Request Parameters

Name Mandatory Type Comments
profile Yes string ID of the investor profile to which this demat account belongs to
dp_id Yes string Depository participant ID
client_id Yes string Client ID

Fetch a Demat Account Object

curl -X GET "https://s.finprim.com/v2/demat_accounts/dac_156e3c3bb66e447d8fe7e44d7d941f5a"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "demat_account",
  "id": "dac_156e3c3bb66e447d8fe7e44d7d941f5a",
  "profile": "invp_ef68993a907b48849a02b403fab8da7f",
  "dp_id": "12081800",
  "client_id": "04571343",
  "created_at": "2023-05-25T14:09:05+05:30"
}

GET /v2/demat_accounts/:id

This API can be used to fetch a demat_account object by its ID.

Query Parameters

Name Mandatory Type Comments
id Yes string ID of the demat_account object

Fetch a Demat Account Object by its Investor Profile ID

curl -X GET "https://s.finprim.com/v2/demat_accounts?profile=invp_ef68993a907b48849a02b403fab8da7f"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "demat_account",
  "id": "dac_156e3c3bb66e447d8fe7e44d7d941f5a",
  "profile": "invp_ef68993a907b48849a02b403fab8da7f",
  "dp_id": "12081800",
  "client_id": "04571343",
  "created_at": "2023-05-25T14:09:05+05:30"
}

GET /v2/demat_accounts?profile={profile}

This API can be used to fetch a demat_account object linked to an investor profile

Name Mandatory Type Comments
profile Yes string ID of the investor profile to which the demat account belongs to

Tax Residencies (Early Access)

Endpoints:

POST /v2/tax_residencies
PATCH /v2/tax_residencies
GET /v2/tax_residencies/:id
GET /v2/tax_residencies

Tax Residencies Object

Tax Residencies Object

{
  "object": "tax_residency",
  "id": "tax_3dc80812a71e44389de80e731864ad92",
  "profile": "invpni_85d92a947b1e49e4a3dad5ef16f5fd2f",
  "country": "us",
  "taxid": "000-00-00000",
  "taxid_type": "tin",
  "created_at": "2023-11-02T13:08:57+05:30"
}

Tax Residency Object attributes

Attribute Type Comments
object string Value is tax_residency. String representing the object type. Objects of the same type share the same value
id string Unique identifier of the tax_residency object
profile string ID of the Non Individual Investor profile to which this tax residencies belongs to
country string ANSI code of the tax residency country.
Use Tax Residency only to capture tax liabilities in countries other than India
taxid string Tax Identification number issued against ID mentioned in taxid_type
taxid_type enum Tax Identification type.

Allowed values are - passport, id_card, driving_license, others, not_categorized, tin
created_at string Creation timestamp

Create a Tax Residency

curl -X POST "https://s.finprim.com/v2/tax_residencies"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "profile": "invpni_85d92a947b1e49e4a3dad5ef16f5fd2f",
  "country": "us"
}

JSON Response

{
  "object": "tax_residency",
  "id": "tax_3dc80812a71e44389de80e731864ad92",
  "profile": "invpni_85d92a947b1e49e4a3dad5ef16f5fd2f",
  "country": "us",
  "taxid": null,
  "taxid_type": null,
  "created_at": "2023-11-02T13:08:57+05:30"
}

POST /v2/tax_residencies

This API can be used to create a tax_residency object.

Request Parameters

Name Mandatory Type Comments
profile yes string ID of the Non individual investor profile to which this tax residency is linked to.

Once set, this cannot be modified.
country yes string ANSI code of the tax residency country
taxid no string Tax Identification number issued against ID mentioned in taxid_type
taxid_type no enum Tax Identification type.

Allowed values are - passport, id_card, driving_license, others, not_categorized, tin

Modify a Tax Residency

curl -X PATCH "https://s.finprim.com/v2/tax_residencies"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "id": "tax_3dc80812a71e44389de80e731864ad92",
  "taxid": "000-00-0000",
  "taxid_type": "tin"
}

JSON Response

{
  "object": "tax_residency",
  "id": "tax_3dc80812a71e44389de80e731864ad92",
  "profile": "invpni_85d92a947b1e49e4a3dad5ef16f5fd2f",
  "country": "us",
  "taxid": "000-00-00000",
  "taxid_type": "tin",
  "created_at": "2023-11-02T13:08:57+05:30"
}

PATCH /v2/tax_residencies

This API can be used to modify a tax residency object.

Body parameters

Name Mandatory Type Comments
id yes string ID of a tax_residency object
taxid no string Tax Identification number issued against ID mentioned in taxid_type
Use Tax Residency only to capture tax liabilities in countries other than India
taxid_type no enum Tax Identification type.

Allowed values are - passport, id_card, driving_license, others, not_categorized, tin

Fetch a Tax Residency

curl -X GET "https://s.finprim.com/v2/tax_residencies/tax_3dc80812a71e44389de80e731864ad92"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "tax_residency",
  "id": "tax_3dc80812a71e44389de80e731864ad92",
  "profile": "invpni_85d92a947b1e49e4a3dad5ef16f5fd2f",
  "country": "us",
  "taxid": "000-00-00000",
  "taxid_type": "tin",
  "created_at": "2023-11-02T13:08:57+05:30"
}

GET /v2/tax_residencies/:id

This API can be used to fetch the details of a tax residencies.

Query parameters

Name Mandatory Type Comments
id yes string ID of a tax_residency object

List all Tax Residency

curl -X GET "https://s.finprim.com/v2/tax_residencies"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "list",
  "data": [
    {
      "object": "tax_residency",
      "id": "tax_3dc80812a71e44389de80e731864ad92",
      "profile": "invpni_85d92a947b1e49e4a3dad5ef16f5fd2f",
      "country": "IN",
      "taxid": "DWEPS2837G",
      "taxid_type": "pan",
      "created_at": "2023-11-02T13:08:57+05:30"
    }
  ]
}

GET /v2/tax_residencies

This API can be used to fetch all the tax residencies.

Query parameters

Name Mandatory Type Comments
profile yes string id of an non individaul investor profile

Beneficial Owners (Early Access)

Endpoints:

POST /v2/beneficial_owners
PATCH /v2/beneficial_owners
GET /v2/beneficial_owners/:id
GET /v2/beneficial_owners

Beneficial Owner Object

Beneficial Owner Object

{
  "object": "beneficial_owner",
  "id": "bo_0b617ef89e244d2db7853404e6048466",
  "profile": "invpni_85d92a947b1e49e4a3dad5ef16f5fd2f",
  "beneficial_owner_profile": "invp_340da1d3b3164ffba5accf0d3852eef1",
  "beneficial_interest_percentage": 12.5,
  "beneficial_interest_means": "ownership",
  "created_at": "2023-11-02T13:30:30+05:30"
}

Beneficial Owner attributes

Attribute Type Comments
object string Value is beneficial_owner. String representing the object type. Objects of the same type share the same value
id string Unique identifier of the beneficial_owner object
profile string ID of the Non Individual Investor profile to which this tax residencies belongs to
beneficial_owner_profile string ID of the Investor profile
beneficial_interest_percentage decimal Intrest percentage of that beneficiary
beneficial_interest_means enum Allowed values are ownership, other_than_ownership, senior_managing_official
created_at string Creation timestamp

Create a Beneficial Owner

curl -X POST "https://s.finprim.com/v2/beneficial_owners"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "profile": "invpni_85d92a947b1e49e4a3dad5ef16f5fd2f",
  "beneficial_owner_profile": "invp_340da1d3b3164ffba5accf0d3852eef1"
}

JSON Response

{
  "object": "beneficial_owner",
  "id": "bo_0b617ef89e244d2db7853404e6048466",
  "profile": "invpni_85d92a947b1e49e4a3dad5ef16f5fd2f",
  "beneficial_owner_profile": "invp_340da1d3b3164ffba5accf0d3852eef1",
  "beneficial_interest_percentage": null,
  "beneficial_interest_means": null,
  "created_at": "2023-11-02T13:30:30+05:30"
}

POST /v2/beneficial_owners

This API can be used to create a beneficial_owner object.

Request Parameters

Name Mandatory Type Comments
profile yes string ID of the Non individual investor profile to which this tax residency is linked to.

Once set, this cannot be modified.
beneficial_owner_profile yes string ID of the Investor profile
beneficial_interest_percentage no decimal Intrest percentage of that beneficiary
beneficial_interest_means no enum Allowed values are ownership, other_than_ownership, senior_managing_official

Modify a Beneficial Owner

curl -X PATCH "https://s.finprim.com/v2/beneficial_owners"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "id": "bo_0b617ef89e244d2db7853404e6048466",
  "beneficial_interest_percentage": 12.5,
  "beneficial_interest_means": "ownership"
}

JSON Response

{
  "object": "beneficial_owner",
  "id": "bo_0b617ef89e244d2db7853404e6048466",
  "profile": "invpni_85d92a947b1e49e4a3dad5ef16f5fd2f",
  "beneficial_owner_profile": "invp_340da1d3b3164ffba5accf0d3852eef1",
  "beneficial_interest_percentage": 12.5,
  "beneficial_interest_means": "ownership",
  "created_at": "2023-11-02T13:30:30+05:30"
}

PATCH /v2/beneficial_owners

This API can be used to modify a beneficial owner object.

Body parameters

Name Mandatory Type Comments
id yes string ID of a beneficial_owner object
beneficial_interest_percentage no decimal Intrest percentage of that beneficiary
beneficial_interest_means no enum Allowed values are ownership, other_than_ownership, senior_managing_official

Fetch a Beneficial Owner

curl -X GET "https://s.finprim.com/v2/beneficial_owners/bo_0b617ef89e244d2db7853404e6048466"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "beneficial_owner",
  "id": "bo_0b617ef89e244d2db7853404e6048466",
  "profile": "invpni_85d92a947b1e49e4a3dad5ef16f5fd2f",
  "beneficial_owner_profile": "invp_340da1d3b3164ffba5accf0d3852eef1",
  "beneficial_interest_percentage": 12.5,
  "beneficial_interest_means": "ownership",
  "created_at": "2023-11-02T13:30:30+05:30"
}

GET /v2/beneficial_owners/:id

This API can be used to fetch the details of a beneficial owner.

Query parameters

Name Mandatory Type Comments
id yes string ID of a beneficial_owner object

List all Beneficial Owner

curl -X GET "https://s.finprim.com/v2/beneficial_owners"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "list",
  "data": [
    {
      "object": "beneficial_owner",
      "id": "bo_0b617ef89e244d2db7853404e6048466",
      "profile": "invpni_85d92a947b1e49e4a3dad5ef16f5fd2f",
      "beneficial_owner_profile": "invp_340da1d3b3164ffba5accf0d3852eef1",
      "beneficial_interest_percentage": 12.5,
      "beneficial_interest_means": "ownership",
      "created_at": "2023-11-02T13:30:30+05:30"
    }
  ]
}

GET /v2/beneficial_owners

This API can be used to fetch all the beneficial owners.

Query parameters

Name Mandatory Type Comments
profile yes string id of an non individaul investor profile

Sole Proprietorship (Early Access)

Endpoints:

POST /v2/sole_proprietorship
PATCH /v2/sole_proprietorship
GET /v2/sole_proprietorship/:id
GET /v2/sole_proprietorship

Sole Proprietorship Object

Sole Proprietorship Object

{
  "object": "sole_proprietorship",
  "id": "sopr_1985fcb8f9ae4623b7720a151b58b924",
  "profile": "invp_5520e01557d848699a0895f388f88480",
  "name": "Test PVT Ltd",
  "networth": {
    "amount": "₹5.55Cr",
    "as_on": "2022-12-12"
  },
  "services_provided": {
    "foreign_exchange": false,
    "money_changer": false,
    "money_lending": false,
    "pawning": false,
    "gaming": false,
    "gambling": false,
    "lottery": false,
    "casino": false
  },
  "created_at": "2023-11-02T15:58:34+05:30"
}

Sole Proprietorship attributes

Attribute Type Comments
object string Value is sole_proprietorship. String representing the object type. Objects of the same type share the same value
id string Unique identifier of the sole_proprietorship object
profile string ID of the Investor profile to which this sole proprietorship is linked to
name string Name of the entity
networth hash Details of the Company's networth
services_provided hash Details of the Company's services provided.
created_at string Creation timestamp

Networth hash

Attribute Type Comments
amount string Networth of company. in currency+number+unit format

possible values are as below
currency: , INR
number: 1-5 places before decimal, 0-2 places after decimal;
unit: Cr, L
as_on string Date of networth, in yyyy-MM-dd format

Services provided hash

Attribute Type Comments
foreign_exchange boolean Is company providing any service related to foreign exchange
money_changer boolean Is company providing any service related to money changer
money_lending boolean Is company providing any service related to money lending
pawning boolean Is company providing any service related to pawning
gaming boolean Is company providing any service related to gaming
gambling boolean Is company providing any service related to gambling
lottery boolean Is company providing any service related to lottery
casino boolean Is company providing any service related to casino

Create a Sole Proprietorship

curl -X POST "https://s.finprim.com/v2/sole_proprietorship"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "profile": "invp_0bc6cf638328413fb5a4864c18e6944b",
  "name": "Test PVT Ltd",
  "services_provided": {
    "foreign_exchange": false,
    "money_changer": false,
    "money_lending": false,
    "pawning": false,
    "gaming": false,
    "gambling": false,
    "lottery": false,
    "casino": false
  }
}

JSON Response

{
  "object": "sole_proprietorship",
  "id": "sopr_60060d3e80e24d3db46fe543acb28e68",
  "profile": "invp_0bc6cf638328413fb5a4864c18e6944b",
  "name": "Test PVT Ltd",
  "networth": null,
  "services_provided": {
    "foreign_exchange": false,
    "money_changer": false,
    "money_lending": false,
    "pawning": false,
    "gaming": false,
    "gambling": false,
    "lottery": false,
    "casino": false
  },
  "created_at": "2023-11-03T17:19:04+05:30"
}

POST /v2/sole_proprietorship

This API can be used to create a sole_proprietorship object.

Request Parameters

Name Mandatory Type Comments
profile yes string ID of the Investor profile to which this sole proprietorship is linked to
name yes string Name of the entity
networth no hash Details of the Company's networth
services_provided no hash Details of the Company's services provided.

Networth hash attributes

Name Mandatory Type Comments
amount no string Networth of company. in currency+number+unit format

possible values are as below
currency: , INR
number: 1-5 places before decimal, 0-2 places after decimal;
unit: Cr, L
as_on no string Date of networth, in yyyy-MM-dd format
This attribute is grouped with amount and both of these attributes have to be collected together.

Services provided hash attributes

Name Mandatory Type Comments
foreign_exchange no boolean Is company providing any service related to foreign exchange
money_changer no boolean Is company providing any service related to money changer
money_lending no boolean Is company providing any service related to money lending
pawning no boolean Is company providing any service related to pawning
gaming no boolean Is company providing any service related to gaming
gambling no boolean Is company providing any service related to gambling
lottery no boolean Is company providing any service related to lottery
casino no boolean Is company providing any service related to casino

Modify a Sole Proprietorship

curl -X PATCH "https://s.finprim.com/v2/sole_proprietorship"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "id": "sopr_60060d3e80e24d3db46fe543acb28e68",
  "networth": {
    "amount": "₹5.55Cr",
    "as_on": "2022-12-12"
  }
}

JSON Response

{
  "object": "sole_proprietorship",
  "id": "sopr_60060d3e80e24d3db46fe543acb28e68",
  "profile": "invp_0bc6cf638328413fb5a4864c18e6944b",
  "name": "Test PVT Ltd",
  "networth": {
    "amount": "₹5.55Cr",
    "as_on": "2022-12-12"
  },
  "services_provided": {
    "foreign_exchange": false,
    "money_changer": false,
    "money_lending": false,
    "pawning": false,
    "gaming": false,
    "gambling": false,
    "lottery": false,
    "casino": false
  },
  "created_at": "2023-11-03T17:19:04+05:30"
}

PATCH /v2/sole_proprietorship

This API can be used to modify a sole proprietorship object.

Body parameters

Name Mandatory Type Comments
id yes string ID of a sole_proprietorship object
networth no hash Details of the Company's networth
services_provided no hash Details of the Company's services provided.

Fetch a Sole Proprietorship

curl -X GET "https://s.finprim.com/v2/sole_proprietorship/sopr_60060d3e80e24d3db46fe543acb28e68"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "sole_proprietorship",
  "id": "sopr_60060d3e80e24d3db46fe543acb28e68",
  "profile": "invp_0bc6cf638328413fb5a4864c18e6944b",
  "name": "Test PVT Ltd",
  "networth": {
    "amount": "₹5.55Cr",
    "as_on": "2022-12-12"
  },
  "services_provided": {
    "foreign_exchange": false,
    "money_changer": false,
    "money_lending": false,
    "pawning": false,
    "gaming": false,
    "gambling": false,
    "lottery": false,
    "casino": false
  },
  "created_at": "2023-11-03T17:19:04+05:30"
}

GET /v2/sole_proprietorship/:id

This API can be used to fetch the details of a sole proprietorship.

Query parameters

Name Mandatory Type Comments
id yes string ID of a sole_proprietorship object

List all Sole Proprietorship

curl -X GET "https://s.finprim.com/v2/sole_proprietorship"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "list",
  "data": [
    {
      "object": "sole_proprietorship",
      "id": "sopr_1985fcb8f9ae4623b7720a151b58b924",
      "profile": "invp_5520e01557d848699a0895f388f88480",
      "name": "Test PVT Ltd",
      "networth": {
        "amount": "₹5.55Cr",
        "as_on": "2022-12-12"
      },
      "services_provided": {
        "foreign_exchange": false,
        "money_changer": false,
        "money_lending": false,
        "pawning": false,
        "gaming": false,
        "gambling": false,
        "lottery": false,
        "casino": false
      },
      "created_at": "2023-11-02T15:58:34+05:30"
    }
  ]
}

GET /v2/sole_proprietorship

This API can be used to fetch all the sole proprietorship.

Query parameters

Name Mandatory Type Comments
profile yes string id of an investor profile

Bank Account Verification (Early Access)

The primary purpose of FP Bank verification APIs is to provide you with mechanisms to answer the following questions

Endpoints:

POST /v2/bank_account_verifications

GET /v2/bank_account_verifications/:id

GET /v2/bank_account_verifications

Bank account verification object

{
  "object": "bank_account_verification",
  "id": "bav_bca82dad078a43e38b853058c8ab48dc",
  "bank_account": "bac_98367e8972b43867a9c68a7c4605a31d",
  "status": "pending",
  "confidence": null,
  "reason": "digital_verification",
  "created_at": "2022-07-07T10:28:53+05:30",
  "updated_at": "2022-07-07T10:28:53+05:30",
  "failed_at": null,
  "completed_at": null
}
Attribute Type Nullable Remarks
id string no Unique identifier of the bank account verification
object string no Indicates the type of object. bank_account_verification
bank_account string no Bank account id of the investor
status string No pending : Bank account verification is in progress.
failed : Failed to verify the bank account.
completed : Verification completed.
If verification is completed, check the confidence value to determine the likelihood of this bank account belonging to the investor.
confidence string Yes The value tells us how confident are we about the likelihood of a bank account belonging to a particular investor. Possible values are very_high, high,uncertain,low,very_low,and zero
reason string Yes Describes the reason for the current status of the verification.
created_at string no Verification request creation timestamp
failed_at string yes Failure timestamp
completed_at string yes Completion timestamp
updated_at string yes Last updated timestamp

Create Bank Verification

Use the below endpoint to create bank account verification.

curl -X POST "https://s.finprim.com/v2/bank_account_verifications"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

REQUEST:

{
  "bank_account": "bac_98367e8972b43867a9c68a7c4605a31d"
}

RESPONSE:

{
  "object": "bank_account_verification",
  "id": "bav_bca82dad078a43e38b853058c8ab48dc",
  "bank_account": "bac_98367e8972b43867a9c68a7c4605a31d",
  "status": "pending",
  "confidence": null,
  "reason": "digital_verification",
  "created_at": "2022-07-07T10:28:53+05:30",
  "updated_at": "2022-07-07T10:28:53+05:30",
  "failed_at": null,
  "completed_at": null
}

Request:
POST /v2/bank_account_verifications

Request parameters:

Name Mandatory Type Comments
bank_account yes string At present, this API accepts an id of a bank account created via Create Investor Profile API

Fetch Bank Account Verification by ID

Use the below endpoint to fetch details of the required bank account verification object.

GET /v2/bank_account_verifications/:id

curl -X GET "https://s.finprim.com/v2/bank_account_verifications/bav_bca82dad078a43e38b853058c8ab48dc"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

RESPONSE:

{
  "object": "bank_account_verification",
  "id": "bav_bca82dad078a43e38b853058c8ab48dc",
  "bank_account": "bac_98367e8972b43867a9c68a7c4605a31d",
  "status": "pending",
  "confidence": null,
  "reason": "digital_verification",
  "created_at": "2022-07-07T10:28:53+05:30",
  "updated_at": "2022-07-07T10:28:53+05:30",
  "failed_at": null,
  "completed_at": null
}

Path Parameters

Name Mandatory Type Comments
id yes string This is the unique identifier linked to the account verification. For example bav_bca82dad078a43e38b853058c8ab48dc

Fetch all Bank Account Verifications

Use the below endpoint to fetch details of bank account verifications based on the filters applied.

GET /v2/bank_account_verifications

curl -X GET "https://s.finprim.com/v2/bank_account_verifications"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

RESPONSE:

{
  "object": "list",
  "data": [
    {
      "object": "bank_account_verification",
      "id": "bav_bca82dad078a43e38b853058c8ab48dc",
      "bank_account": "bac_98367e8972b43867a9c68a7c4605a31d",
      "status": "completed",
      "confidence": "very_high",
      "reason": null,
      "created_at": "2022-07-07T08:59:58+05:30",
      "failed_at": null,
      "completed_at": "2022-07-07T09:00:06+05:30",
      "updated_at": "2022-07-07T09:00:06+05:30"
    }
  ]
}

Query Parameters

Name Mandatory Type Comments
status no string [] Possible Values:
- pending
- completed
- failed
reason no string [] Possible Values:
- digital_verification
- expiry
- digital_verification_failure
confidence no string [] Possible Values:
- very_high
- high
- uncertain
- low
- very_low
- zero
bank_accounts no string [] Bank account ids of an investor. For example, [bac_666929e99b7b4c9c94d4f838990eef89,bac_666929e99b7b4c9c94d4f838990eef89]

MF Investment Accounts

You need to create an investment account for your investors before you can start accepting orders. Any orders placed via an investment account and folios associated with those orders are organized under the investment account. When you migrate folios, folios having the same pans and holding pattern combination are organized under the investment accounts of matching pans and holding pattern. mf_investment_account object represents such investment accounts.

Endpoints:

POST /v2/mf_investment_accounts
PATCH /v2/mf_investment_accounts
GET /v2/mf_investment_accounts/:id
GET /v2/mf_investment_accounts

MF Investment Account Object

{
  "object": "mf_investment_account",
  "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "old_id": 110,
  "primary_investor_pan": "ACCPP55K7L",
  "second_investor_pan": null,
  "third_investor_pan": null,
  "primary_investor_old_id": null,
  "second_investor_old_id": null,
  "third_investor_old_id": null,
  "primary_investor": "invp_c55240e4b09d4617812bb9557b399a42",
  "second_investor": null,
  "third_investor": null,
  "holding_pattern": "single",
  "folio_defaults": {
    "communication_email_address": "email_bf1026954d0545e190727de1537d9e66",
    "communication_mobile_number": "phone_0f4a90134705474eb2e354d9b5ba5f56",
    "communication_address": "addr_8c50b6930ebf4ec7a7ddd58c34bdf1d8",
    "overseas_communication_address": "addr_bf1026954d0545e190727de1537d9e66",
    "payout_bank_account": "bac_8c50b6930ebf4ec7a7ddd58c34bdf1d8",
    "nominee1": "relp_8c50b6930ebf4ec7a7ddd58c34bdf1d8",
    "nominee1_allocation_percentage": 100,
    "nominee2": null,
    "nominee2_allocation_percentage": null,
    "nominee3": null,
    "nominee3_allocation_percentage": null,
    "demat_account": "dac_156e3c3bb66e447d8fe7e44d7d941f5a"
  },
  "created_at": "2020-04-06T15:32:52+05:30"
}
Attribute Type Comments
object string Value is mf_investment_account. String representing the object type. Objects of the same type share the same value
id string Unique identifier of the mf_investment_account object
old_id integer This is the numeric ID of this mf_investment_account object. We have provided this as some of our APIs use this ID like in holding API.
primary_investor_pan string PAN of the first holder
second_investor_pan string PAN of the second holder
third_investor_pan string PAN of the third holder
primary_investor_old_id (Deprecated) string Identifier of the first holder old investor object attached to this investment account
second_investor_old_id (Deprecated) string Identifier of the second holder old investor object attached to this investment account
third_investor_old_id (Deprecated) string Identifier of the third holder old investor object attached to this investment account
primary_investor string Identifier of the first holder's investor profile object or identifier of the non individual investor profile object.
If you are using investor profile, then it is mandatory input if primary_investor_old_id is not given
second_investor string Identifier of the second holder's investor profile object
third_investor string Identifier of the third holder's investor profile t
holding_pattern string This value indicates the holding nature of the folios that are mapped against this investment account. For example, if the holding pattern is single, you can create transactions against investor's folios where the investor is the primary investor and holding pattern is single.
Possible values: single, joint, either_or_survivor, anyone_or_survivor, first_or_survivor
For non individual investor profiles, only single holding_pattern is supported.
folio_defaults hash This hash contains the transaction data preferences that can be set
created_at string The time at which the investment_account is created

Folio Defaults hash

This hash will contain a set of attributes which can be set as default data values that would be used while submitting transaction requests.

Attribute Type Comments
communication_email_address string email_address object ID that contains a valid email address to which all the communications would be sent to.
communication_mobile_number string phone_number object ID that contains a valid mobile number to which all the communications would be sent to.
communication_address string address object ID that contains a valid address to which all the communications would be sent to.
overseas_communication_address string address object ID that contains a valid overseas communication address if any present
payout_bank_account string bank_account object ID that contains a valid bank account to which payouts will be made
nominee1 string related_party object ID that contains nominee information
nominee1_allocation_percentage numeric Allocation percentage for Nominee 1
nominee2 string related_party object ID that contains nominee information
nominee2_allocation_percentage numeric Allocation percentage for Nominee 2
nominee3 string related_party object ID that contains nominee information
nominee3_allocation_percentage numeric Allocation percentage for Nominee 3
demat_account string demat_account object ID that contains the demat account details of the investor.
If this attribute has demat_account object ID, then any new folio and respective orders using the investment account will be treated for delivery in demat mode, else folio and respective orders will be treated for delivery in physical mode

A note on working with Folio Defaults

Every Investor Profile that is created, has a capability where multiple values can be registered against a certain set of attributes. While this investor wants to make a transaction, he should be able to choose one among those values to register against his order. For ex., if an investor profile has 5 addresses present, he should be able to choose one among them as the communication_address and another as the overseas_communication_address, to send it as the supporting data for the transaction that he is making. FP has a capability of recording a set of default values that can be defined and used every time while making a transaction. You can choose to update these values as and when necessary.

Please note that, the folio_defaults behaviour is limited to investment accounts which are created using Investor Profile IDs alone. If you are creating an investment account with with investor ID(old investor object), all the attributes in folio_defaults hash would be set to null.


Create an MF Investment Account

POST /v2/mf_investment_accounts

curl -X POST "https://s.finprim.com/v2/mf_investment_accounts"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "primary_investor": "invp_c55240e4b09d4617812bb9557b399a42",
  "holding_pattern": "single"
}

JSON Response:

{
  "object": "mf_investment_account",
  "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "old_id": 110,
  "primary_investor_pan": "ACCPP55K7L",
  "second_investor_pan": null,
  "third_investor_pan": null,
  "primary_investor_old_id": null,
  "second_investor_old_id": null,
  "third_investor_old_id": null,
  "primary_investor": "invp_c55240e4b09d4617812bb9557b399a42",
  "second_investor": null,
  "third_investor": null,
  "holding_pattern": "single",
  "folio_defaults": {
    "communication_email_address": null,
    "communication_mobile_number": null,
    "communication_address": null,
    "overseas_communication_address": null,
    "payout_bank_account": null,
    "nominee1": null,
    "nominee1_allocation_percentage": null,
    "nominee2": null,
    "nominee2_allocation_percentage": null,
    "nominee3": null,
    "nominee3_allocation_percentage": null,
    "demat_account": null
  },
  "created_at": "2020-04-06T15:32:52+05:30"
}

Request Parameters

Name Mandatory Type Comments
primary_investor_old_id (Deprecated) conditional string Investor ID(old investor object) of the first holder. Mandatory if primary_investor is not given.
primary_investor conditional string Investor profile ID or non individual investor profile ID of the first holder. Mandatory if primary_investor_old_id is not given
holding_pattern no string Provide holding pattern for the investment account.
Default value = single
Supported values: single
folio_defaults no hash This hash contains the transaction data preferences that can be set. This can be set only if primary_investor is given

Folio Defaults hash

Attribute Mandatory Type Comments
communication_email_address no string email_address object ID that contains a valid email address to which all the communications would be sent to.
communication_mobile_number no string phone_number object ID that contains a valid mobile number to which all the communications would be sent to.
communication_address no string address object ID that contains a valid address to which all the communications would be sent to.
overseas_communication_address no string address object ID that contains a valid overseas communication address if any present
payout_bank_account no string bank_account object ID that contains a valid bank account to which payouts will be made
nominee1 no string related_party object ID that contains nominee information
nominee1_allocation_percentage no numeric Allocation percentage for Nominee 1
nominee2 no string related_party object ID that contains nominee information
nominee2_allocation_percentage no numeric Allocation percentage for Nominee 2
nominee3 no string related_party object ID that contains nominee information
nominee3_allocation_percentage no numeric Allocation percentage for Nominee 3
demat_account no string demat_account object ID that contains the demat account details of the investor.
If this attribute has demat_account object ID, then any new folio and respective orders using the investment account will be treated for delivery in demat mode, else folio and respective orders will be treated for delivery in physical mode

Note: Investor Details Validation

In accordance with "AMFI Best Practice Guidelines Circular No.97 /2021-22 published on March 28, 2022", FP performs following validations while creating/updating an investment account .

Attribute Validation
Investor Name
  • Name must not contain special characters such as : %, [ , . , = , & , - , \ , /, _ , : , ; , ?, ( , @ , * , + , ) , # , ! , $ , ^ , ] , ", and ,
  • Guardian Name
  • Name must not contain special characters.
  • Name should not be same as investor name.
  • Nominee Name
  • Name must not contain special characters.
  • Name should not be same as investor name.
  • If more than one nominee, Nominee names should be Unique.
  • Investor Mobile Number For indian numbers, i.e isd_code = 91
  • Acceptable length of the Mobile number is 10 digits.
  • Mobile number should not start with 0 or 1 or 2 or 3 or 4 or 5.
  • All the digits in a Mobile number should not be the same. (Example: 7777777777 is an invalid number)
  • Investor Email
  • A valid structured email address should be present in investor contact details. (Example: values like notprovided, noemail or empty will be considered invalid email)
  • The email address must contain exactly one occurence of '@' symbol. (Example: mf@investor@gmail.com is an invalid email address)
  • Email address must not end with a dot. (Example: mfinvestor@gmail.com. is an invalid email address)
  • Email address must not end with an invalid Top Level Domain. (Whitelisted TLD's : .com, .in, .org, .co, .net, .edu, .me, .uk)
  • Update an MF Investment Account

    PATCH /v2/mf_investment_accounts

    This API lets you associate an investor with an investment account. This will be necessary when you avail FP's folio migration facility.

    This API can also be used to set or modify the folio_defaults that is present in an investment account object. In order to do this, the investment account should contain a valid Investor Profile ID in primary_investor attribute.

    curl -X PATCH "https://s.finprim.com/v2/mf_investment_accounts"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Request:

    {
      "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
      "folio_defaults": {
        "communication_email_address": "email_bf1026954d0545e190727de1537d9e66",
        "communication_mobile_number": "phone_0f4a90134705474eb2e354d9b5ba5f56",
        "communication_address": "addr_8c50b6930ebf4ec7a7ddd58c34bdf1d8",
        "overseas_communication_address": "addr_bf1026954d0545e190727de1537d9e66",
        "payout_bank_account": "bac_8c50b6930ebf4ec7a7ddd58c34bdf1d8",
        "nominee1": "relp_8c50b6930ebf4ec7a7ddd58c34bdf1d8",
        "nominee1_allocation_percentage": 100,
        "demat_account": "dac_156e3c3bb66e447d8fe7e44d7d941f5a"
      }
    }
    

    JSON Response:

    {
      "object": "mf_investment_account",
      "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
      "old_id": 110,
      "primary_investor_pan": "ACCPP55K7L",
      "second_investor_pan": null,
      "third_investor_pan": null,
      "primary_investor_old_id": null,
      "second_investor_old_id": null,
      "third_investor_old_id": null,
      "primary_investor": "invp_c55240e4b09d4617812bb9557b399a42",
      "second_investor": null,
      "third_investor": null,
      "holding_pattern": "single",
      "folio_defaults": {
        "communication_email_address": "email_bf1026954d0545e190727de1537d9e66",
        "communication_mobile_number": "phone_0f4a90134705474eb2e354d9b5ba5f56",
        "communication_address": "addr_8c50b6930ebf4ec7a7ddd58c34bdf1d8",
        "overseas_communication_address": "addr_bf1026954d0545e190727de1537d9e66",
        "payout_bank_account": "bac_8c50b6930ebf4ec7a7ddd58c34bdf1d8",
        "nominee1": "relp_8c50b6930ebf4ec7a7ddd58c34bdf1d8",
        "nominee1_allocation_percentage": 100,
        "nominee2": null,
        "nominee2_allocation_percentage": null,
        "nominee3": null,
        "nominee3_allocation_percentage": null,
        "demat_account": "dac_156e3c3bb66e447d8fe7e44d7d941f5a"
      },
      "created_at": "2020-04-06T15:32:52+05:30"
    }
    

    Request Parameters

    Name Mandatory Type Comments
    id yes string ID of the investment account.
    primary_investor_old_id (Deprecated) no integer Provide Investor ID(old investor object) of the first holder. The PAN of the investor should match with the primary_investor_pan of the investment account.

    Mandatory if primary_investor is not given. This cannot as well co-exist with primary_investor.

    Once a value is set, this cannot be modified.
    primary_investor no string Provide Investor Profile ID of the first holder. The PAN of the investor should match with the primary_investor_pan of the investment account.

    Mandatory if primary_investor_old_id is not given. This cannot as well co-exist with primary_investor_old_id.

    Once a value is set, this cannot be modified.
    folio_defaults no hash This hash contains the transaction data preferences that can be set. This can be given only if primary_investor is being set or it already has a Investor Profile ID set.

    You cannot define folio_defaults if a value for primary_investor_old_id is set.

    Folio Defaults hash

    Attribute Mandatory Type Comments
    communication_email_address no string email_address object ID that contains a valid email address to which all the communications would be sent to.
    communication_mobile_number no string phone_number object ID that contains a valid mobile number to which all the communications would be sent to.
    communication_address no string address object ID that contains a valid address to which all the communications would be sent to.
    overseas_communication_address no string address object ID that contains a valid overseas communication address if any present
    payout_bank_account no string bank_account object ID that contains a valid bank account to which payouts will be made
    nominee1 no string related_party object ID that contains nominee information
    nominee1_allocation_percentage no numeric Allocation percentage for Nominee 1
    nominee2 no string related_party object ID that contains nominee information
    nominee2_allocation_percentage no numeric Allocation percentage for Nominee 2
    nominee3 no string related_party object ID that contains nominee information
    nominee3_allocation_percentage no numeric Allocation percentage for Nominee 3
    demat_account no string demat_account object ID that contains the demat account details of the investor.
    If this attribute has demat_account object ID, then any new folio and respective orders using the investment account will be treated for delivery in demat mode, else folio and respective orders will be treated for delivery in physical mode

    Note:

    Validations performed during Create a mf investment account , are also applied while Update a mf investment account.

    A note on mapping existing investment accounts with newly onboarded investors

    When folios are migrated, corresponding investment accounts are created and folios are organized under the investment accounts. No investor objects are created. Therefore, there will be investment accounts without any investor associated with them. When you onboard an investor, you can search whether there are any investment accounts are present or not. If they are present, you can associate an investor or an investor profile with the investment account using this API.

    Fetch an MF Investment Account

    GET /v2/mf_investment_accounts/:id

    This API is used to fetch a given investment account by its V2 identifier.

    curl -X GET "https://s.finprim.com/v2/mf_investment_accounts/mfia_14bafabfbfbc423d9b54412dd577981b"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Response:

    {
      "object": "mf_investment_account",
      "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
      "old_id": 110,
      "primary_investor_pan": "ACCPP55K7L",
      "second_investor_pan": null,
      "third_investor_pan": null,
      "primary_investor_old_id": null,
      "second_investor_old_id": null,
      "third_investor_old_id": null,
      "primary_investor": "invp_c55240e4b09d4617812bb9557b399a42",
      "second_investor": null,
      "third_investor": null,
      "holding_pattern": "single",
      "folio_defaults": {
        "communication_email_address": "email_bf1026954d0545e190727de1537d9e66",
        "communication_mobile_number": "phone_0f4a90134705474eb2e354d9b5ba5f56",
        "communication_address": "addr_8c50b6930ebf4ec7a7ddd58c34bdf1d8",
        "overseas_communication_address": "addr_bf1026954d0545e190727de1537d9e66",
        "payout_bank_account": "bac_8c50b6930ebf4ec7a7ddd58c34bdf1d8",
        "nominee1": "relp_8c50b6930ebf4ec7a7ddd58c34bdf1d8",
        "nominee1_allocation_percentage": 100,
        "nominee2": null,
        "nominee2_allocation_percentage": null,
        "nominee3": null,
        "nominee3_allocation_percentage": null,
        "demat_account": "dac_156e3c3bb66e447d8fe7e44d7d941f5a"
      },
      "created_at": "2020-04-06T15:32:52+05:30"
    }
    

    Query Parameters

    Name Mandatory Type Comments
    mf_investment_account_id yes string V2 or V1 id of the investment account

    List all MF Investment Accounts

    GET /v2/mf_investment_accounts

    curl -X GET "https://s.finprim.com/v2/mf_investment_accounts"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Response:

    {
      "object": "list",
      "data": [
        {
          "object": "mf_investment_account",
          "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
          "old_id": 110,
          "primary_investor_pan": "ACCPP55K7L",
          "second_investor_pan": null,
          "third_investor_pan": null,
          "primary_investor_old_id": null,
          "second_investor_old_id": null,
          "third_investor_old_id": null,
          "primary_investor": "invp_c55240e4b09d4617812bb9557b399a42",
          "second_investor": null,
          "third_investor": null,
          "holding_pattern": "single",
          "folio_defaults": {
            "communication_email_address": "email_bf1026954d0545e190727de1537d9e66",
            "communication_mobile_number": "phone_0f4a90134705474eb2e354d9b5ba5f56",
            "communication_address": "addr_8c50b6930ebf4ec7a7ddd58c34bdf1d8",
            "overseas_communication_address": "addr_bf1026954d0545e190727de1537d9e66",
            "payout_bank_account": "bac_8c50b6930ebf4ec7a7ddd58c34bdf1d8",
            "nominee1": "relp_8c50b6930ebf4ec7a7ddd58c34bdf1d8",
            "nominee1_allocation_percentage": 100,
            "nominee2": null,
            "nominee2_allocation_percentage": null,
            "nominee3": null,
            "nominee3_allocation_percentage": null,
            "demat_account": "dac_156e3c3bb66e447d8fe7e44d7d941f5a"
          },
          "created_at": "2020-04-06T15:32:52+05:30"
        },
        {
          "object": "mf_investment_account",
          "id": "mfia_24bafbbfbfbc423d9b54412dc57a9a11",
          "old_id": 111,
          "primary_investor_pan": "PCCPK55K7L",
          "second_investor_pan": null,
          "third_investor_pan": null,
          "primary_investor_old_id": 111,
          "second_investor_old_id": null,
          "third_investor_old_id": null,
          "primary_investor": null,
          "second_investor": null,
          "third_investor": null,
          "holding_pattern": "single",
          "folio_defaults": {
            "communication_email_address": null,
            "communication_mobile_number": null,
            "communication_address": null,
            "overseas_communication_address": null,
            "payout_bank_account": null,
            "nominee1": null,
            "nominee1_allocation_percentage": null,
            "nominee2": null,
            "nominee2_allocation_percentage": null,
            "nominee3": null,
            "nominee3_allocation_percentage": null,
            "demat_account": null
          },
          "created_at": "2020-04-06T15:32:52+05:30"
        }
      ]
    }
    

    Query Parameters

    Name Mandatory Type Comments
    primary_investor_pan no string Filter by primary investor pan.
    second_investor_pan no string Filter by second investor pan.
    third_investor_pan no string Filter by third investor pan.
    holding_pattern no string Filter by holding_pattern of investment account.
    investor no string Accepts a PAN as a value. Using this option, you can filter all the investment accounts in which this PAN is present either as primary, secondary or third investor

    Note:

    The response contains maximum of 100 records ordered by the created date desc

    Introduction to MF Orders

    Orders Overview

    FP supports 3 types of mutual fund orders -

    1. MF Purchases
    2. MF Redemptions
    3. MF Switches

    The following sections cover the general aspects of a mutual fund order.

    Note

    Order States

    State Remarks
    pending The order is created, but not ready for submission
    confirmed The order is ready for submission to the order gateway
    submitted The order has been submitted to the order gateway
    successful The order has been successfully processed by the order gateway
    failed The order is marked as failed
    cancelled The order has been explicitly cancelled from processing by the user
    reversed A previously successful order has been reversed by the order gateway for some reason. Changes in units will be reversed in such cases

    Order Expiry

    An order which is in pending state will be marked as failed if the order is not marked as confirmed within a specified time.

    The below window applies to all one time and recurring installments of orders.

    Note: If a purchase or a purchase installment order payment has been attempted and failed, the order remains in failed state and payment cannot be retried after the expiry window.

    Order type Expiry after
    Purchase T+7 working days(Order will be expired on T+8)
    Redemption T+1 working day(Order will be expired on T+2)
    Switch T+1 working day(Order will be expired on T+2)

    The order expiry for installments of a systematic purchase plan are as below:

    Read about auto cancellation of purchase plans due to consecutive failed installments

    Systematic purchase plan frequency Installment and plan expiry after
    Daily T day(Order will be expired on T+1)
    day_in_a_week T+4 calendar days(Order will be expired on T+5)
    four_times_a_month T+4 calendar days(Order will be expired on T+5)
    day_in_a_fortnight T+4 calendar days(Order will be expired on T+5)
    twice_a_month T+4 calendar days(Order will be expired on T+5)
    monthly T+6 calendar days(Order will be expired on T+7)
    quarterly T+6 calendar days(Order will be expired on T+7)
    half-yearly T+6 calendar days(Order will be expired on T+7)
    yearly T+6 calendar days(Order will be expired on T+7)

    Note

    T is the day on which the order is supposed to be submitted to the order gateway. Each order will expose this date via the scheduled_on attribute.

    Frequently Asked Questions(FAQs)

    Are order creation APIs idempotent?

    Order creation APIs are not idempotent. If you create two orders with the same parameters again, the second order will also be treated as a new order. However, while creating an order you can set a unique source_ref_id. If you try to create two orders with the same source_ref_id, the second order will fail with a validation error.

    How do I handle situations where there is a request timeout while creating an order ?

    Please note that this will not happen in general. However, in exceptional cases if this happens, there are two possible ways to handle it -

    1. Ignore the previous attempt to create an order and create a new order again. The previously attempted order will remain unused and will auto-expire as per the expiry schedule.
    2. You can always set a unique source_ref_id while creating an order. This way, when you try to create another order with the same source_ref_id, you will get an error.

    How do I handle situations where there is a request timeout while confirming an order ?

    You can fetch the order by its ID and check its status. Only if the order is pending, you can try to confirm the order again. Otherwise, you will get an error.

    MF Purchases

    Represents a mutual fund purchase order. The purchase order can be -

    1. A lump sum purchase order, or
    2. An installment created via a Purchase Plan

    Endpoints:

    POST /v2/mf_purchases
    PATCH /v2/mf_purchases
    GET /v2/mf_purchases/:id
    GET /v2/mf_purchases
    POST /v2/mf_purchases/:id/retry
    POST /v2/mf_purchases/:id/cancel

    MF Purchase Object

    {
      "object": "mf_purchase",
      "id": "mfp_177177219f634373b01072986d2eea7d",
      "old_id": 9123,
      "mf_investment_account": "mfia_367a75826694614a539c0f82b196027",
      "folio_number": "31171511",
      "state": "pending",
      "amount": 10000.0,
      "scheme": "INF173K01FE6",
      "gateway": "rta",
      "traded_on": null,
      "scheduled_on": "2020-04-07",
      "created_at": "2020-04-06T15:32:52+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "retried_at": null,
      "cancelled_at": null,
      "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1",
      "plan": null,
      "initiated_by": "investor",
      "initiated_via": "web",
      "euin": null,
      "partner": "ptnr_20751c37c0a548c3baf12a18bc72187b",
      "failure_code": null,
      "type": "additional_purchase",
      "allotted_units": null,
      "purchased_amount": null,
      "purchased_price": null,
      "confirmed_at": null
    }
    
    Attribute Type Comments
    object string Value is mf_purchase. String representing the object type. Objects of the same type share the same value
    id string Unique identifier of the mf_purchase object
    old_id integer This is the Numeric ID of the purchase object,We have provided this as some of our APIs use this ID like in Payments .
    mf_investment_account string This is the ID of the investment account object, and you can identify the investment account associated with the purchase order using this id
    folio_number string This value represents the folio number in which the investor has made the purchase.
    In case of fresh purchases, the folio number will be available only when the order becomes successful.
    state string State of the purchase order. Possible values: pending, confirmed, submitted, successful, failed, cancelled, reversed
    amount decimal Purchase amount in INR
    allotted_units decimal Number of units allotted for this purchase transaction. For example, the user might have placed a purchase order for Rs. 500 at a NAV of Rs. 296.0196. A stamp duty at 0.005% of Rs. 500 = 0.03(0.025 rounded up to 0.03) might get applied and the actual investment amount would be 500 - 0.03 = Rs. 499.97. Units allotted = 499.97/296.0196 = 1.68897600024 = 1.689 (Rounded up to 3 decimal points). The value will be available only after the order is submitted to the order gateway and is successfully processed
    purchased_amount decimal The actual purchase amount. For example, the user might have placed a purchase order for Rs. 500 at a NAV of Rs. 296.0196. A stamp duty at 0.005% of Rs. 500 = 0.03(0.025 rounded up to 0.03) might get applied and the actual investment amount would be 500 - 0.03 = Rs. 499.97. The value will be available only after the order is submitted to the order gateway and is successfully processed.
    purchased_price decimal NAV at which the trade happened
    scheme string ISIN of the scheme in which the investment was made
    type string This value indicates whether this purchase order is a fresh purchase or an additional purchase in an existing folio. Possible values: purchase, additional_purchase
    plan string The object id of the plan with which this purchase is associated. This value will be available only if this purchase order is created by a plan
    scheduled_on string The date on which the order is scheduled for submission to the order gateway for processing. In case the order is in confirmed state before the scheduled_on date, the order will be sent to the gateway on the date the order is confirmed
    traded_on string The date on which the trade happened. Please note that the trade will happen after the order is submitted to the order gateway
    created_at string The time at which the order was created
    confirmed_at string The time at which the order was confirmed
    submitted_at string The time at which the order was submitted to the order gateway
    succeeded_at string The time at which the order was processed successfully
    failed_at string The time at which the order was failed
    retried_at string The time at which the order was last retried
    reversed_at string The time at which the order was reversed
    cancelled_at string The time at which the order was cancelled
    gateway string The gateway through which the order was submitted for processing. Possible values: rta, bse
    source_ref_id string An identifier that is unique across orders of all types(purchases, redemptions, and switch). This is not generated by FP and is populated by API consumers for identification purposes. (ideally an auto generated identifier / uuid to identify the order in your application)
    user_ip string IP address of end user who has initiated the transaction.
    server_ip string IP address of server through which the request to create this transaction was made.
    euin string Unique identity number of the employee / relationship manager/ sales person of the distributor who has advised or interacted with the investor in any other manner for this purchase order.
    partner string ID of the partner via which this order is created if any.
    failure_code string Failure code of the failed purchase order. Possible values: payment_failure,order_expiry,order_failure_at_gateway and others
    initiated_by string The entity/person who has initiated this purchase. Possible values: investor, distributor
    initiated_via string The medium via which this transaction was initiated. Possible values: mobile_app, mobile_app_android, mobile_app_ios, mobile_web_android, mobile_web_ios, mobile_web, web

    Create a MF Purchase

    POST /v2/mf_purchases

    Note

    When you create an order using Create MF Purchase API, the order will be in pending state. The order would get submitted to the order gateway only after you mark the order as confirmed. There are two ways a purchase order is confirmed -

    1. If you are using our Payments API to make payment for the order, the order will get marked as confirmed upon successful payment by FP.

    2. If you have made the payment for the order using a different method, you can create a Settlement for the order and then use our Update MF Purchase API to mark the order as confirmed.

    An order which is in pending state will be marked as failed due to inactivity after T+7 market days post RTA order submission cut-off time, if the order is not confirmed within this duration.

    curl -X POST "https://s.finprim.com/v2/mf_purchases"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Request:

    {
      "mf_investment_account": "mfia_367a75826694614a539c0f82b196027",
      "scheme": "INF173K01FE6",
      "folio_number": "31171511",
      "amount": 10000,
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1",
      "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
      "euin": null
    }
    

    JSON Response:

    {
      "object": "mf_purchase",
      "id": "mfp_177177219f634373b01072986d2eea7d",
      "old_id": 9123,
      "mf_investment_account": "mfia_367a75826694614a539c0f82b196027",
      "folio_number": "31171511",
      "state": "pending",
      "amount": 10000.0,
      "scheme": "INF173K01FE6",
      "gateway": "rta",
      "traded_on": null,
      "scheduled_on": "2020-04-07",
      "created_at": "2020-04-06T15:32:52+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "retried_at": null,
      "cancelled_at": null,
      "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1",
      "plan": null,
      "initiated_by": "investor",
      "initiated_via": "web",
      "euin": null,
      "partner": "ptnr_20751c37c0a548c3baf12a18bc72187b",
      "failure_code": null,
      "type": "additional_purchase",
      "allotted_units": null,
      "purchased_amount": null,
      "purchased_price": null,
      "confirmed_at": null
    }
    

    Request Parameters

    Name Mandatory Type Comments
    mf_investment_account yes string ID of the investment account against which this order must be placed.
    scheme yes string ISIN of the scheme for which this order must be placed.
    folio_number no string If the folio number is given, the purchase will be made against the given folio.
    But if folio number is not given, FP requests AMC to create a new folio. In this case, please ensure that investor consent has been taken (by OTP 2FA method) to add nomination against the new folio before the purchase order is placed.
    amount yes integer Provide purchase amount in INR1
    user_ip no string See Details Here
    server_ip no string See Details Here
    source_ref_id no string See Details Here
    euin no string See Details Here
    scheduled_on no string See Details Here.
    order_gateway no string The gateway through which the order needs to be submitted for processing.
    Possible values: rta, bse.
    If value is null, then order will be routed through the default gateway which is configured for the tenant.
    This attribute can be used by tenants configured with the BSE gateway only.
    partner no string See Details Here

    1Each scheme has different constraints regarding the investment amount. You can fetch scheme details using Fund Scheme API to know the values for such constraints.

    1. In case of fresh purchases, the amount should be between min_initial_investment and max_initial_investment and should be a multiple of initial_investment_multiples
    2. In case of additional purchases, the amount should be between min_additional_investment and max_additional_investment and should be a multiple of additional_investment_multiples

    Create a MF Purchase Plan Installment

    curl -X POST "https://s.finprim.com/v2/mf_purchases"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Request:

    {
      "plan": "mfpp_dbabb25ba34c48329dbfbeff70c846f0"
    }
    

    JSON Response:

    {
      "object": "mf_purchase",
      "id": "mfp_177177219f634373b01072986d2eea7d",
      "old_id": 9123,
      "mf_investment_account": "mfia_367a75826694614a539c0f82b196027",
      "folio_number": "31171511",
      "state": "pending",
      "amount": 10000.0,
      "scheme": "INF173K01FE6",
      "gateway": "rta",
      "traded_on": null,
      "scheduled_on": "2020-04-07",
      "created_at": "2020-04-06T15:32:52+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "retried_at": null,
      "cancelled_at": null,
      "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1",
      "plan": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
      "initiated_by": "investor",
      "initiated_via": "web",
      "euin": null,
      "partner": "ptnr_20751c37c0a548c3baf12a18bc72187b",
      "failure_code": null,
      "type": "additional_purchase",
      "allotted_units": null,
      "purchased_amount": null,
      "purchased_price": null,
      "confirmed_at": null
    }
    

    POST /v2/mf_purchases

    You can use this API to simulate installment generation for a Purchase Plan which is active.

    Request Parameters

    Name Mandatory Type Comments
    plan yes string Provide the id of the mf_purchase_plan for which installment must be generated

    Update a MF Purchase

    PATCH /v2/mf_purchases

    For an existing purchase order, this API can be used to -

    1. Update the purchase order with the consent details
    2. Change the purchase order state to confirmed

    Note

    If the active order gateway is RTA -

    1. The purchase order needs to be first updated with consent only.
    2. If payment for the purchase order is done outside FP, first create the settlement details and then update the purchase order state to confirmed. This step is not required if payment was done via FP.

    If the active order gateway is BSE -

    1. The purchase order needs to be updated with the consent and state as confirmed.
    curl -X PATCH "https://s.finprim.com/v2/mf_purchases"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Request:

    {
      "id": "mfp_177177219f634373b01072986d2eea7d",
      "state": "confirmed",
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd_code": "91",
        "mobile": "9008580644"
      }
    }
    

    JSON Response:

    {
      "object": "mf_purchase",
      "id": "mfp_177177219f634373b01072986d2eea7d",
      "old_id": 9123,
      "mf_investment_account": "mfia_167a75826694614a539c0f82b196027",
      "folio_number": "39171511",
      "state": "confirmed",
      "amount": 10000.0,
      "scheme": "INF173K01FE6",
      "gateway": "rta",
      "traded_on": null,
      "scheduled_on": "2020-04-07",
      "created_at": "2020-04-06T15:32:52+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "retried_at": null,
      "cancelled_at": null,
      "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1",
      "plan": null,
      "initiated_by": "investor",
      "initiated_via": "web",
      "euin": null,
      "partner": "ptnr_20751c37c0a548c3baf12a18bc72187b",
      "failure_code": null,
      "type": "additional_purchase",
      "allotted_units": null,
      "purchased_amount": null,
      "purchased_price": null,
      "confirmed_at": "2020-04-06T20:32:52+05:30"
    }
    

    Request Parameters

    Name Mandatory Type Comments
    id Yes string ID of the purchase order.
    state Conditional string New state of the purchase order. Supported values: confirmed. Not mandatory if order gateway is RTA, and consent is present as a part of the request.
    consent Conditional hash Consent from investor for confirming the purchase order. Not mandatory if order gateway is RTA, and state is present as a part of the request.
    Once set, this cannot be modified.

    As per SEBI regulations, 2FA has been mandated for purchase orders -

    1. Before order is sent to RTAs, investor consent must be obtained by sending a One-Time Password to the investor at his email/phone number -

      • In case of order placed against an existing folio the OTP should be sent to the email/ mobile registered against the existing folio.
      • In case of an order placed without a folio, the OTP should be sent to the email/mobile present in the folio_defaults of MF investment account.
    2. Before order is sent to BSE, investor consent must be obtained by sending a One-Time Password to the investor at his email and phone number, and consent can be collected either by email/mobile -

      • In case of order placed against an existing folio the OTP should be sent to the email and mobile registered against the existing folio.
      • In case of order placed without folio the OTP should be sent to the email and mobile registered against the UCC.

    To comply with the above -

    1. While routing the order via RTA, either email or mobile or both can be added as a part of the consent object.
    2. While routing the order via BSE, both email and mobile should be added as a part of the consent object.
    Name Mandatory Type Comments
    email conditional string Mandatory if consent is obtained via email.
    isd_code conditional string Mandatory if consent is obtained via mobile.
    Only integers are allowed, also + can be added at the start.
    Max character length is 4 including +
    mobile conditional string Mandatory if consent is obtained via mobile.
    Only integers and - are allowed
    Min and Max character length is 7 and 20

    Fetch a MF Purchase

    GET /v2/mf_purchases/:id

    curl -X GET "https://s.finprim.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    This API is used to fetch a given purchase order by its identifier.

    Query Parameters

    Name Mandatory Type Comments
    id yes string id or old_id of the purchase order.

    JSON Response:

    {
      "object": "mf_purchase",
      "id": "mfp_177177219f634373b01072986d2eea7d",
      "old_id": 9123,
      "mf_investment_account": "mfia_367a75826694614a539c0f82b196027",
      "folio_number": "31171511",
      "state": "pending",
      "amount": 10000.0,
      "scheme": "INF173K01FE6",
      "gateway": "rta",
      "traded_on": null,
      "scheduled_on": "2020-04-07",
      "created_at": "2020-04-06T15:32:52+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "retried_at": null,
      "cancelled_at": null,
      "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1",
      "plan": null,
      "initiated_by": "investor",
      "initiated_via": "web",
      "euin": null,
      "partner": "ptnr_20751c37c0a548c3baf12a18bc72187b",
      "failure_code": null,
      "type": "additional_purchase",
      "allotted_units": null,
      "purchased_amount": null,
      "purchased_price": null,
      "confirmed_at": null
    }
    

    List all MF Purchases

    GET /v2/mf_purchases

    curl -X GET "https://s.finprim.com/v2/mf_purchases"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    This API used to fetch all purchase orders.

    JSON Response:

    {
      "object": "list",
      "data": [
        {
          "object": "mf_purchase",
          "id": "mfp_177177219f634373b01072986d2eea7d",
          "old_id": 9123,
          "mf_investment_account": "mfia_367a75826694614a539c0f82b196027",
          "folio_number": "31171511",
          "state": "pending",
          "amount": 10000.0,
          "scheme": "INF173K01FE6",
          "gateway": "rta",
          "traded_on": null,
          "scheduled_on": "2020-04-07",
          "created_at": "2020-04-06T15:32:52+05:30",
          "succeeded_at": null,
          "submitted_at": null,
          "reversed_at": null,
          "failed_at": null,
          "retried_at": null,
          "cancelled_at": null,
          "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
          "user_ip": "10.0.128.12",
          "server_ip": "126.1.10.1",
          "plan": null,
          "initiated_by": "investor",
          "initiated_via": "web",
          "euin": null,
          "partner": "ptnr_20751c37c0a548c3baf12a18bc72187b",
          "failure_code": null,
          "type": "additional_purchase",
          "allotted_units": null,
          "purchased_amount": null,
          "purchased_price": null,
          "confirmed_at": null
        },
        {
          "object": "mf_purchase",
          "id": "mfp_266177219f634373b01072986d2eea4d",
          "old_id": 9123,
          "mf_investment_account": "mfia_177a85826694614a531c0f82b196022",
          "folio_number": "11171611",
          "state": "pending",
          "amount": 10000.0,
          "scheme": "INF373K01FE1",
          "gateway": "rta",
          "traded_on": null,
          "scheduled_on": "2020-02-07",
          "created_at": "2020-03-06T15:32:52+05:30",
          "succeeded_at": null,
          "submitted_at": null,
          "reversed_at": null,
          "failed_at": null,
          "retried_at": null,
          "cancelled_at": null,
          "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
          "user_ip": "10.0.128.12",
          "server_ip": "126.1.10.1",
          "plan": null,
          "initiated_by": "investor",
          "initiated_via": "mobile_app",
          "euin": null,
          "partner": "ptnr_20751c37c0a548c3baf12a18bc72187b",
          "failure_code": null,
          "type": "additional_purchase",
          "allotted_units": null,
          "purchased_amount": null,
          "purchased_price": null,
          "confirmed_at": null
        }
      ]
    }
    

    Query Parameters

    Name Mandatory Type Comments
    mf_investment_account no string The investment account against which the purchases are made.
    skip_instruction no string Provide skip instruction id to fetch purchase orders that belong to the particular skip instruction.
    plan no string MF Purchase Plan ID
    states no string Comma separated values of purchase states

    Note

    The response can contain 100 latest orders at max.

    Retry MF Purchase

    POST /v2/mf_purchases/:id/retry

    curl -X POST "https://s.finprim.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d/retry"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    This API is used to retry the payment for an order which has failed.
    After running the API, the order state changes from failed to pending and the order is eligible for payment again.

    Note

    This API can be used only when gateway provider is RTA and the order has failed due to below reasons

    1. Payment failure and failure_code=payment_failure and order expiry window is not elapsed
    2. Order has expired failure_code=order_expiry and installment does not belong to systematic purchase plan.

    JSON Response:

    {
      "object": "mf_purchase",
      "id": "mfp_177177219f634373b01072986d2eea7d",
      "old_id": 9123,
      "mf_investment_account": "mfia_367a75826694614a539c0f82b196027",
      "folio_number": "31171511",
      "state": "pending",
      "amount": 10000.0,
      "scheme": "INF173K01FE6",
      "gateway": "rta",
      "traded_on": null,
      "scheduled_on": "2020-04-07",
      "created_at": "2020-04-06T15:32:52+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "retried_at": null,
      "cancelled_at": null,
      "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1",
      "plan": null,
      "initiated_by": "investor",
      "initiated_via": "web",
      "euin": null,
      "partner": "ptnr_20751c37c0a548c3baf12a18bc72187b",
      "failure_code": null,
      "type": "additional_purchase",
      "allotted_units": null,
      "purchased_amount": null,
      "purchased_price": null,
      "confirmed_at": null
    }
    

    Cancel MF Purchase

    POST /v2/mf_purchases/:id/cancel

    curl -X POST "https://s.finprim.com/v2/mf_purchases/mfp_fd83fef17dbf4905b01a425a4c386a82/cancel"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    This API is used to cancel the MF purchase order which is in pending state.
    After running the API, the order state changes from pending to cancelled.

    Note

    This API can be used only when gateway provider is RTA and the payment for order should not be in progress.

    JSON Response:

    {
      "object": "mf_purchase",
      "id": "mfp_fd83fef17dbf4905b01a425a4c386a82",
      "old_id": 818,
      "mf_investment_account": "mfia_dd6bf671c1b94a15a338235f00ab88b8",
      "folio_number": null,
      "state": "cancelled",
      "amount": 10000.0,
      "gateway": "rta",
      "traded_on": null,
      "scheduled_on": "2024-01-12",
      "created_at": "2024-01-12T10:37:54+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "confirmed_at": null,
      "retried_at": null,
      "cancelled_at": "2024-01-12T10:38:28+05:30",
      "source_ref_id": null,
      "user_ip": null,
      "server_ip": "127.0.0.1",
      "plan": null,
      "initiated_by": null,
      "initiated_via": null,
      "euin": null,
      "partner": null,
      "failure_code": null,
      "order_reference": null,
      "type": "purchase",
      "scheme": "INF846K018E9",
      "allotted_units": null,
      "purchased_amount": null,
      "purchased_price": null
    }
    

    MF Redemptions

    Represents a mutual fund redemption order. The redemption order can be -

    1. A lump sum redemption order, or
    2. An installment created via a Redemption Plan

    Endpoints:

    POST /v2/mf_redemptions
    PATCH /v2/mf_redemptions
    GET /v2/mf_redemptions/:id
    GET /v2/mf_redemptions

    MF Redemption Object

    {
      "object": "mf_redemption",
      "id": "mfr_15f8d86bae614801bab5accaed131abc",
      "old_id": 6597,
      "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
      "folio_number": "15075102",
      "state": "pending",
      "amount": 10000.0,
      "scheme": "INF173K01FQ0",
      "redemption_mode": "normal",
      "traded_on": null,
      "failed_at": null,
      "plan": null,
      "euin": null,
      "partner": "ptnr_20751c37c0a548c3baf12a18bc72187b",
      "failure_code": null,
      "units": null,
      "redeemed_price": null,
      "redeemed_units": null,
      "redeemed_amount": null,
      "redemption_bank_account_number": null,
      "redemption_bank_account_ifsc_code": null,
      "scheduled_on": "2020-04-07",
      "created_at": "2020-04-07T14:50:23+05:30",
      "confirmed_at": null,
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "cancelled_at": null,
      "gateway": "rta",
      "initiated_by": "investor",
      "initiated_via": "web",
      "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1"
    }
    
    Attribute Type Comments
    object string Value is mf_redemption. String representing the object type. Objects of the same type share the same value
    id string Unique identifier of the mf_redemption object
    old_id integer This is the Numeric ID of the redemption object,We have provided this as some of our APIs use this ID .
    mf_investment_account string This is the ID of the investment account object, and you can identify the investment account associated with the redemption order using this id
    folio_number string This value represents the mutual fund folio number. Using the folio number, you can determine the folio in which the investor has made the redemption.
    state string State of the redemption order. Possible values: pending, confirmed, submitted, successful, failed, cancelled, reversed
    amount decimal

    You can create a redemption order for a particular amount or you can create a redemption order for a particular number of units. If the redemption order was created for a specific amount, the value will not be empty. It will be empty otherwise.

    Please note that if the redemption amount and units are both empty, the entire holding amount would be redeemed upon successful processing of the order.

    units decimal

    You can create a redemption order for a particular amount or you can create a redemption order for a particular number of units. If the redemption order was created to redeem a certain number of units, the value will not be empty. It will be empty otherwise.

    Please note that if the redemption amount and units are both empty, the entire holding amount would be redeemed upon successful processing of the order.

    redeemed_amount decimal The actual amount that was redeemed.
    redeemed_units decimal The actual number of units that were deducted from the investors holdings after the redemption order was processed by the order gateway.
    redeemed_price decimal The NAV at which the redemption order was processed.
    scheme string The isin of the scheme from which the redemption has to be made.
    plan string The object id of the plan with which this rdemption is associated. This value will be available only if this redemption order is created by a plan.
    scheduled_on string The date on which the order is scheduled for submission to the order gateway for processing.
    traded_on string The date on which the trade happened. Please note that the trade will happen after the order is submitted to the order gateway.
    redemption_mode string Mode of redemption:

    normal: In this mode, FP sends orders via order gateway as it does for other types of orders. Usually, the investor will receive the redemption proceeds in the bank account after two to three working days depending on TAT for redemption proceeds defined by AMCs. You can place redemption orders for any schemes(including liquid funds) in this mode.

    instant: This mode is only applicable for liquid fund schemes and the investor will receive the redemption proceeds in the bank account instantly on successfully placing the redemption order. This mode is currently supported by a few AMCs as of now. Click here to know more

    redemption_bank_account_number string This value indicates the bank account number in which the instant redemption proceeds have been deposited. This value will be null if the redemption mode is normal.
    redemption_bank_account_ifsc_code string This value indicates the IFSC code of the bank account in which the instant redemption proceeds have been deposited. This value will be null if the redemption mode is normal.
    created_at string The time at which the order is created
    confirmed_at string The time at which the order is confirmed
    submitted_at string The time at which the order is submitted to the order gateway
    succeeded_at string The time at which the order is processed successfully
    failed_at string The time at which the order is failed
    reversed_at string The time at which the order is reversed
    cancelled_at string The time at which the order was cancelled
    gateway string The gateway through which the order was submitted for processing. Possible values: rta, bse
    source_ref_id string An identifier that is unique across orders of all types(purchases, redemptions, and switch). This is not generated by FP and is populated by API consumers for identification purposes. (ideally an auto generated identifier / uuid to identify the order in your application).
    user_ip string IP address of end user who has initiated the transaction.
    server_ip string IP address of server through which the request to create this transaction was made.
    euin string Unique identity number of the employee / relationship manager/ sales person of the distributor who has advised or interacted with the investor in any other manner for this order.
    partner string ID of the partner via which this order is created if any.
    failure_code string Failure code of the failed order. Possible values: order_expiry,order_failure_at_gateway and others
    initiated_by string The entity/person who has initiated this redemption. Possible values: investor, distributor
    initiated_via string The medium via which this transaction was initiated. Possible values: mobile_app, mobile_app_android, mobile_app_ios, mobile_web_android, mobile_web_ios, mobile_web, web

    Create a MF Redemption

    POST /v2/mf_redemptions

    Note:

    When you create an order using Create MF Redemption API, the order will be in the pending state. However, the orders would get submitted to the order gateway only after you mark the order as confirmed. You can use Update a MF Redemption API to mark the order as confirmed.

    An order which is in pending state will be marked as failed due to inactivity after T+1 market day post RTA order submission cut-off time, if the order is not confirmed within this duration.

    curl -X POST "https://s.finprim.com/v2/mf_redemptions"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Request:

    {
      "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
      "folio_number": "15075102",
      "amount": 10000,
      "scheme": "INF173K01FQ0",
      "units": null,
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1",
      "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
      "euin": null
    }
    

    JSON Response:

    {
      "object": "mf_redemption",
      "id": "mfr_15f8d86bae614801bab5accaed131abc",
      "old_id": 6597,
      "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
      "folio_number": "15075102",
      "state": "pending",
      "amount": 10000.0,
      "scheme": "INF173K01FQ0",
      "redemption_mode": "normal",
      "traded_on": null,
      "failed_at": null,
      "plan": null,
      "euin": null,
      "partner": "ptnr_20751c37c0a548c3baf12a18bc72187b",
      "failure_code": null,
      "units": null,
      "redeemed_price": null,
      "redeemed_units": null,
      "redeemed_amount": null,
      "redemption_bank_account_number": null,
      "redemption_bank_account_ifsc_code": null,
      "scheduled_on": "2020-04-07",
      "created_at": "2020-04-07T14:50:23+05:30",
      "confirmed_at": null,
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "cancelled_at": null,
      "gateway": "rta",
      "initiated_by": "investor",
      "initiated_via": "web",
      "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1"
    }
    

    Request Parameters

    Name Mandatory Type Comments
    mf_investment_account yes string Provide the id of the investment account against which this order must be placed.
    scheme yes string Provide the isin of the scheme for which this order must be placed
    folio_number yes string Provide the folio number mapped with the investment account against which order must be placed.
    amount no integer Provide redemption amount in Rupees.

    The amount should be between min_withdrawal_amount and max_withdrawal_amount and should be a multiple of withdrawal_multiples

    If the redemption amount and units are both empty, the entire holding amount would be redeemed upon successful processing of the order.

    Note : You can use Get holdings Report API to check the maximum redeemable amount for a given folio and a scheme.

    units no decimal Provide the number of units that you want to redeem

    The units should be between min_withdrawal_units and max_withdrawal_units and should be a multiple of withdrawal_multiples_units

    If the redemption amount and units are both empty, the entire holding amount would be redeemed upon successful processing of the order.

    Note : You can use Get holdings Report API to check the maximum redeemable units for a given folio and a scheme.

    user_ip no string Provide IP address of the end-user.
    server_ip no string Provide IP address of the server through which the request to create this order is made.
    source_ref_id no string An identifier that is unique across orders of all types(purchases, redemptions, and switch). This is not generated by FP and is populated by API consumers for identification purposes. (ideally an auto generated identifier / uuid to identify the order in your application).
    euin no string Provide EUIN associated with the distributor through which the order is being placed.
    order_gateway no string The gateway through which the order needs to be submitted for processing. Possible values: rta, bse.
    If value is null, then order will be routed through the default gateway which is configured for the tenant Currently this attribute can be used by tenants configured with the BSE gateway only.
    partner no string See Details Here

    Create a MF Redemption Plan Installment

    curl -X POST "https://s.finprim.com/v2/mf_redemptions"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Request:

    {
      "plan": "mfrp_dbabb25ba34c48329dbfbeff70c846f0"
    }
    

    JSON Response:

    {
      "object": "mf_redemption",
      "id": "mfr_15f8d86bae614801bab5accaed131abc",
      "old_id": 6597,
      "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
      "folio_number": "15075102",
      "state": "pending",
      "amount": 10000.0,
      "scheme": "INF173K01FQ0",
      "redemption_mode": "normal",
      "traded_on": null,
      "failed_at": null,
      "plan": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
      "euin": null,
      "partner": "ptnr_20751c37c0a548c3baf12a18bc72187b",
      "failure_code": null,
      "units": null,
      "redeemed_price": null,
      "redeemed_units": null,
      "redeemed_amount": null,
      "redemption_bank_account_number": null,
      "redemption_bank_account_ifsc_code": null,
      "scheduled_on": "2020-04-07",
      "created_at": "2020-04-07T14:50:23+05:30",
      "confirmed_at": null,
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "cancelled_at": null,
      "gateway": "rta",
      "initiated_by": "investor",
      "initiated_via": "web",
      "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1"
    }
    

    POST /v2/mf_redemptions

    You can use this API to simulate installment generation for a Redemption Plan which is active.

    Request Parameters

    Name Mandatory Type Comments
    plan yes string Provide the id of the mf_redemption_plan for which installment must be generated

    Update a MF Redemption

    PATCH /v2/mf_redemptions

    curl -X PATCH "https://s.finprim.com/v2/mf_redemptions"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Request:

    {
      "id": "mfr_15f8d86bae614801bab5accaed131abc",
      "state": "confirmed",
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd_code": "91",
        "mobile": "9008580644"
      }
    }
    

    JSON Response:

    {
      "object": "mf_redemption",
      "id": "mfr_15f8d86bae614801bab5accaed131abc",
      "old_id": 6597,
      "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
      "folio_number": "15075102",
      "state": "confirmed",
      "amount": 10000.0,
      "scheme": "INF173K01FQ0",
      "redemption_mode": "normal",
      "traded_on": null,
      "failed_at": null,
      "plan": null,
      "euin": null,
      "partner": "ptnr_20751c37c0a548c3baf12a18bc72187b",
      "failure_code": null,
      "units": null,
      "redeemed_price": null,
      "redeemed_units": null,
      "redeemed_amount": null,
      "redemption_bank_account_number": null,
      "redemption_bank_account_ifsc_code": null,
      "scheduled_on": "2020-04-07",
      "created_at": "2020-04-07T14:50:23+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "cancelled_at": null,
      "gateway": "rta",
      "initiated_by": "investor",
      "initiated_via": "web",
      "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1"
    }
    

    Request Parameters

    Name Mandatory Type Comments
    id yes string Id of the redemption order
    state yes string New state of the redemption order. Possible values:
    - confirmed
    consent conditional hash Consent from investor for confirming the redemption order
    Once set, this cannot be modified

    As per SEBI regulations, investor consent must be obtained by sending a One-Time Password to the investor at his/her email/phone number registered against the folio before the redemption order can be sent to rtas.

    Name Mandatory Type Comments
    email conditional string Mandatory if consent is obtained via email.
    The value must be one of the email addresses registered against the folio.
    isd_code conditional string Mandatory if consent is obtained via mobile.
    Only integers are allowed, also + can be added at the start.
    Max character length is 4 including +
    mobile conditional string Mandatory if consent is obtained via mobile.
    The value must be one of the mobile numbers registered against the folio.

    Only integers and - are allowed
    Min and Max character length is 7 and 20

    Fetch a MF Redemption

    GET /v2/mf_redemptions/:id

    curl -X GET "https://s.finprim.com/v2/mf_redemptions/mfr_15f8d86bae614801bab5accaed131abc"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    This API is used to fetch a given redemption order by its V2 identifier

    Query Parameters

    Name Mandatory Type Comments
    id yes string id or old_id of the redemption order.

    JSON Response:

    {
      "object": "mf_redemption",
      "id": "mfr_15f8d86bae614801bab5accaed131abc",
      "old_id": 6597,
      "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
      "folio_number": "15075102",
      "state": "pending",
      "amount": 10000.0,
      "scheme": "INF173K01FQ0",
      "redemption_mode": "normal",
      "traded_on": null,
      "failed_at": null,
      "plan": null,
      "euin": null,
      "partner": "ptnr_20751c37c0a548c3baf12a18bc72187b",
      "failure_code": null,
      "units": null,
      "redeemed_price": null,
      "redeemed_units": null,
      "redeemed_amount": null,
      "redemption_bank_account_number": null,
      "redemption_bank_account_ifsc_code": null,
      "scheduled_on": "2020-04-07",
      "created_at": "2020-04-07T14:50:23+05:30",
      "confirmed_at": null,
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "cancelled_at": null,
      "gateway": "rta",
      "initiated_by": "investor",
      "initiated_via": "web",
      "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1"
    }
    

    List all MF Redemptions

    GET /v2/mf_redemptions

    curl -X GET "https://s.finprim.com/v2/mf_redemptions"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    This API is used to fetch all MF Redemption orders.

    JSON Response:

    {
      "object": "list",
      "data": [
        {
          "object": "mf_redemption",
          "id": "mfr_15f8d86bae614801bab5accaed131abc",
          "old_id": 6597,
          "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
          "folio_number": "15075102",
          "state": "pending",
          "amount": 10000.0,
          "scheme": "INF173K01FQ0",
          "redemption_mode": "normal",
          "traded_on": null,
          "failed_at": null,
          "plan": null,
          "euin": null,
          "partner": "ptnr_20751c37c0a548c3baf12a18bc72187b",
          "failure_code": null,
          "units": null,
          "redeemed_price": null,
          "redeemed_units": null,
          "redeemed_amount": null,
          "redemption_bank_account_number": null,
          "redemption_bank_account_ifsc_code": null,
          "scheduled_on": "2020-04-07",
          "created_at": "2020-04-07T14:50:23+05:30",
          "confirmed_at": null,
          "succeeded_at": null,
          "submitted_at": null,
          "reversed_at": null,
          "cancelled_at": null,
          "gateway": "rta",
          "initiated_by": "investor",
          "initiated_via": "web",
          "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
          "user_ip": "10.0.128.12",
          "server_ip": "126.1.10.1"
        },
        {
          "object": "mf_redemption",
          "id": "mfr_21f8a86bae614101bab5accaed121abf",
          "old_id": 6597,
          "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
          "folio_number": "15075102",
          "state": "pending",
          "amount": 10000.0,
          "scheme": "INF213K04FQ0",
          "redemption_mode": "normal",
          "traded_on": null,
          "failed_at": null,
          "plan": null,
          "euin": null,
          "partner": "ptnr_20751c37c0a548c3baf12a18bc72187b",
          "failure_code": null,
          "units": null,
          "redeemed_price": null,
          "redeemed_units": null,
          "redeemed_amount": null,
          "redemption_bank_account_number": null,
          "redemption_bank_account_ifsc_code": null,
          "scheduled_on": "2020-04-07",
          "created_at": "2020-04-07T14:50:23+05:30",
          "confirmed_at": null,
          "succeeded_at": null,
          "submitted_at": null,
          "reversed_at": null,
          "cancelled_at": null,
          "gateway": "rta",
          "initiated_by": "investor",
          "initiated_via": "web",
          "source_ref_id": "aad6ca01-a002-46ar-8e1c-ea6fe191a5de",
          "user_ip": "10.1.128.11",
          "server_ip": "122.1.9.1"
        }
      ]
    }
    

    Query Parameters

    Name Mandatory Type Comments
    mf_investment_account no string The investment account against which the redemptions are made.
    skip_instruction no string Provide skip instruction id to fetch redemption orders that belong to the particular skip instruction.
    plan no string MF Redemption Plan ID
    states no string Comma separated values of redemption states

    Note:

    The response can contain 100 latest orders at max.

    MF Switches

    Represents a mutual fund switch order. The switch order can be -

    1. A lump sum switch order, or
    2. An installment created via a Switch Plan

    Endpoints:

    POST /v2/mf_switches
    PATCH /v2/mf_switches
    GET /v2/mf_switches/:id
    GET /v2/mf_switches

    MF Switch Object

    {
      "object": "mf_switch",
      "id": "mfs_b1aba06d52184619151d3b82efa65de6",
      "old_id": 16586,
      "mf_investment_account": "mfia_167a75826694614a539c0f82b196027",
      "folio_number": "39171511",
      "state": "pending",
      "amount": 1000.0,
      "units": null,
      "switch_out_scheme": "INF173K01FE6",
      "switch_in_scheme": "INF173K02FE5",
      "plan": null,
      "switched_out_units": null,
      "switched_out_amount": null,
      "switched_out_price": null,
      "switched_in_units": null,
      "switched_in_amount": null,
      "switched_in_price": null,
      "gateway": "rta",
      "traded_on": null,
      "scheduled_on": "2021-01-21",
      "created_at": "2021-01-03T19:21:04+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "confirmed_at": null,
      "cancelled_at": null,
      "source_ref_id": null,
      "user_ip": null,
      "server_ip": null,
      "initiated_by": "investor",
      "initiated_via": "web",
      "euin": null,
      "partner": null,
      "failure_code": null
    }
    
    Attribute Type Comments
    object string Value is mf_switch. A string representing the object type. Objects of the same type share the same value
    id string Unique identifier to identify a mf_switch order
    old_id integer This is the Numeric ID of the switch object,We have provided this as some of our APIs use this ID
    mf_investment_account string This is the ID of the investment account object, and you can identify the investment account associated with the switch order using this id
    folio_number string This value represents the mutual fund folio number. Using the folio number, you can determine the folio in which the investor has made the switch from one scheme to another
    state string State of the switch order
    Possible values: pending, confirmed, submitted, successful, failed, cancelled, reversed
    amount decimal The amount of money requested to be switched out from the source scheme during the creation of the switch order
    units decimal The number of units requested to be switched out from the source scheme during the creation of the switch order
    switch_out_scheme string The ISIN of the source scheme from which the switch must be made
    switch_in_scheme string The ISIN of the destination scheme to which the switch must be made
    plan string The object id of the plan with which this switch is associated. This value will be available only if this switch order is created by a plan
    switched_out_units decimal The actual number of units that are deducted from the source scheme after the switch order is processed successfully
    switched_out_amount decimal The actual amount of money that is deducted from the source scheme holdings after the switch order is processed successfully
    switched_out_price decimal Source scheme NAV which was applied for processing the switch order
    switched_in_units decimal The actual number of units in the target scheme that are switched after the switch order is processed successfully
    switched_in_amount decimal The actual amount of money that is invested in the target scheme after the switch order is processed successfully
    switched_in_price decimal Target scheme NAV which was applied for processing the switch order
    scheduled_on string The date on which the order is scheduled for submission to the order gateway for processing.
    traded_on string The date on which the trade happened. Please note that the trade will happen after the order is submitted to the order gateway
    created_at string The time at which the order is created
    confirmed_at string The time at which the order is confirmed
    submitted_at string The time at which the order is submitted to the order gateway
    succeeded_at string The time at which the order is processed successfully
    failed_at string The time at which the order is failed
    reversed_at string The time at which the order is reversed
    cancelled_at string The time at which the order was cancelled
    gateway string The gateway through which the order was submitted for processing. Possible values: rta, bse
    source_ref_id string An identifier that is unique across orders of all types(purchases, redemptions, and switch). This is not generated by FP and is populated by API consumers for identification purposes. (ideally an auto generated identifier / uuid to identify the order in your application)
    user_ip string IP address of end user who has initiated the transaction.
    server_ip string IP address of server through which the request to create this transaction was made.
    euin string Unique identity number of the employee / relationship manager/ sales person of the distributor who has advised or interacted with the investor in any other manner for this order.
    partner string ID of the partner via which this order is created if any.
    failure_code string Failure code of the failed order. Possible values: order_expiry,order_failure_at_gateway and others
    initiated_by string The entity/person who has initiated this order. Possible values: investor, distributor
    initiated_via string The medium via which this transaction was initiated. Possible values: mobile_app, mobile_app_android, mobile_app_ios, mobile_web_android, mobile_web_ios, mobile_web, web

    Create a MF Switch

    POST /v2/mf_switches

    Note:

    When you create an order using Create mf_switch order API, the order will be in the pending state. However, the orders would get submitted to the order gateway only after you mark the order as confirmed. You can use our Update a MF Switch order API to mark an order as confirmed.

    An order which is in pending state will be marked as failed due to inactivity after T+1 market day post RTA order submission cut-off time, if the order is not confirmed within this duration.

    curl -X POST "https://s.finprim.com/v2/mf_switches"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Request:

    {
      "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
      "folio_number": "15075102",
      "amount": 10000,
      "switch_out_scheme": "INF273K01FQ0",
      "switch_in_scheme": "INF171K07FQ0",
      "units": null,
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1",
      "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
      "euin": null
    }
    

    JSON Response:

    {
      "object": "mf_switch",
      "id": "mfs_b1aba06d52184619151d3b82efa65de6",
      "old_id": 16586,
      "mf_investment_account": "mfia_167a75826694614a539c0f82b196027",
      "folio_number": "39171511",
      "state": "pending",
      "amount": 1000.0,
      "units": null,
      "switch_out_scheme": "INF173K01FE6",
      "switch_in_scheme": "INF173K02FE5",
      "plan": null,
      "switched_out_units": null,
      "switched_out_amount": null,
      "switched_out_price": null,
      "switched_in_units": null,
      "switched_in_amount": null,
      "switched_in_price": null,
      "gateway": "rta",
      "traded_on": null,
      "scheduled_on": "2021-01-21",
      "created_at": "2021-01-03T19:21:04+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "confirmed_at": null,
      "cancelled_at": null,
      "source_ref_id": null,
      "user_ip": null,
      "server_ip": null,
      "initiated_by": "investor",
      "initiated_via": "web",
      "euin": null,
      "partner": null,
      "failure_code": null
    }
    

    Request Parameters

    Name Mandatory Type Comments
    mf_investment_account yes string Provide the id of the investment account against which this order must be placed.
    folio_number yes string Provide the folio number mapped against the investment account if you want to make an additional switch against a folio.
    switch_out_scheme yes string Provide the isin of the source scheme from which the switch must be made.
    switch_in_scheme yes string Provide the isin of the destination scheme to which the switch must be made.
    amount no integer Provide redemption amount in Rupees.

    The amount should be greater than or equals to min_switch_out_amount and should be a multiple of switch_out_amount_multiples

    If the switch amount and units are both empty, the entire holding amount would be switched upon successful processing of the order.

    Note : You can use Get holdings Report API to check the maximum switch amount for a given folio and a switch_out_scheme.

    units no decimal Provide the number of units that you want to switch

    The units should be greater than or equals to min_switch_out_units and should be a multiple of switch_out_unit_multiples

    If the switch amount and units are both empty, the entire holding amount would be switched upon successful processing of the order.

    Note : You can use Get holdings Report API to check the maximum switchable units for a given folio and a switch_out_scheme.

    user_ip no string Provide IP address of the end-user.
    server_ip no string Provide IP address of the server through which the request to create this order is made.
    source_ref_id no string An identifier that is unique across orders of all types(switches, redemptions, and switch). This is not generated by FP and is populated by API consumers for identification purposes. (ideally an auto generated identifier / uuid to identify the order in your application).
    euin no string Provide EUIN associated with the distributor through which the order is being placed.
    order_gateway no string The gateway through which the order needs to be submitted for processing. Possible values: rta, bse.
    If value is null, then order will be routed through the default gateway which is configured for the tenant. Currently this attribute can be used by tenants configured with the BSE gateway only.
    partner no string See Details Here

    Create a MF Switch Plan Installment

    curl -X POST "https://s.finprim.com/v2/mf_switches"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Request:

    {
      "plan": "mfsp_dbabb25ba34c48329dbfbeff70c846f0"
    }
    

    JSON Response:

    {
      "object": "mf_switch",
      "id": "mfs_b1aba06d52184619151d3b82efa65de6",
      "old_id": 16586,
      "mf_investment_account": "mfia_167a75826694614a539c0f82b196027",
      "folio_number": "39171511",
      "state": "pending",
      "amount": 1000.0,
      "units": null,
      "switch_out_scheme": "INF173K01FE6",
      "switch_in_scheme": "INF173K02FE5",
      "plan": "mfsp_dbabb25ba34c48329dbfbeff70c846f0",
      "switched_out_units": null,
      "switched_out_amount": null,
      "switched_out_price": null,
      "switched_in_units": null,
      "switched_in_amount": null,
      "switched_in_price": null,
      "gateway": "rta",
      "traded_on": null,
      "scheduled_on": "2021-01-21",
      "created_at": "2021-01-03T19:21:04+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "confirmed_at": null,
      "cancelled_at": null,
      "source_ref_id": null,
      "user_ip": null,
      "server_ip": null,
      "initiated_by": "investor",
      "initiated_via": "web",
      "euin": null,
      "partner": null,
      "failure_code": null
    }
    

    POST /v2/mf_switches

    You can use this API to simulate installment generation for a Switch Plan which is active.

    Request Parameters

    Name Mandatory Type Comments
    plan yes string Provide the id of the mf_switch_plan for which installment must be generated

    Update a MF Switch

    PATCH /v2/mf_switches

    curl -X PATCH "https://s.finprim.com/v2/mf_switches"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Request:

    {
      "id": "mfs_b1aba06d52184619151d3b82efa65de6",
      "state": "confirmed",
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd_code": "91",
        "mobile": "9008580644"
      }
    }
    

    JSON Response:

    {
      "object": "mf_switch",
      "id": "mfs_b1aba06d52184619151d3b82efa65de6",
      "old_id": 16586,
      "mf_investment_account": "mfia_167a75826694614a539c0f82b196027",
      "folio_number": "39171511",
      "state": "confirmed",
      "amount": 1000.0,
      "units": null,
      "switch_out_scheme": "INF173K01FE6",
      "switch_in_scheme": "INF173K02FE5",
      "plan": null,
      "switched_out_units": null,
      "switched_out_amount": null,
      "switched_out_price": null,
      "switched_in_units": null,
      "switched_in_amount": null,
      "switched_in_price": null,
      "gateway": "rta",
      "traded_on": null,
      "scheduled_on": "2021-01-21",
      "created_at": "2021-01-03T19:21:04+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "confirmed_at": "2021-01-03T20:32:52+05:30",
      "cancelled_at": null,
      "source_ref_id": null,
      "user_ip": null,
      "server_ip": null,
      "initiated_by": "investor",
      "initiated_via": "web",
      "euin": null,
      "partner": null,
      "failure_code": null
    }
    

    Request Parameters

    Name Mandatory Type Comments
    id yes string Id of the switch order.
    state yes string New state of the switch order. Supported values: confirmed
    consent yes hash Consent from investor for confirming the redemption
    Once set, this cannot be modified

    As per SEBI regulations, investor consent must be obtained by sending a One-Time Password to the investor at his/her email/phone number registered against the folio before the switch order can be sent to rtas.

    Name Mandatory Type Comments
    email conditional string Mandatory if consent is obtained via email.
    The value must be one of the email addresses registered against the folio.
    isd_code conditional string Mandatory if consent is obtained via mobile.
    Only integers are allowed, also + can be added at the start.
    Max character length is 4 including +
    mobile conditional string Mandatory if consent is obtained via mobile.
    The value must be one of the mobile numbers registered against the folio.

    Only integers and - are allowed
    Min and Max character length is 7 and 20

    Fetch a MF Switch

    GET /v2/mf_switches/:id

    curl -X GET "https://s.finprim.com/v2/mf_switches/mfs_b1aba06d52184619151d3b82efa65de6"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    This API is used to fetch a given switch order by its identifier.

    Query Parameters

    Name Mandatory Type Comments
    id yes string id or old_id of the switch order.

    JSON Response:

    {
      "object": "mf_switch",
      "id": "mfs_b1aba06d52184619151d3b82efa65de6",
      "old_id": 16586,
      "mf_investment_account": "mfia_167a75826694614a539c0f82b196027",
      "folio_number": "39171511",
      "state": "pending",
      "amount": 1000.0,
      "units": null,
      "switch_out_scheme": "INF173K01FE6",
      "switch_in_scheme": "INF173K02FE5",
      "plan": null,
      "switched_out_units": null,
      "switched_out_amount": null,
      "switched_out_price": null,
      "switched_in_units": null,
      "switched_in_amount": null,
      "switched_in_price": null,
      "gateway": "rta",
      "traded_on": null,
      "scheduled_on": "2021-01-21",
      "created_at": "2021-01-03T19:21:04+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "confirmed_at": null,
      "cancelled_at": null,
      "source_ref_id": null,
      "user_ip": null,
      "server_ip": null,
      "initiated_by": "investor",
      "initiated_via": "web",
      "euin": null,
      "partner": null,
      "failure_code": null
    }
    

    List all MF Switches

    GET /v2/mf_switches

    curl -X GET "https://s.finprim.com/v2/mf_switches"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    This API used to fetch all switch orders.

    JSON Response:

    {
      "object": "list",
      "data": [
        {
          "object": "mf_switch",
          "id": "mfs_b1aba06d52184619151d3b82efa65de6",
          "old_id": 16586,
          "mf_investment_account": "mfia_167a75826694614a539c0f82b196027",
          "folio_number": "39171511",
          "state": "pending",
          "amount": 1000.0,
          "units": null,
          "switch_out_scheme": "INF173K01FE6",
          "switch_in_scheme": "INF173K02FE5",
          "plan": null,
          "switched_out_units": null,
          "switched_out_amount": null,
          "switched_out_price": null,
          "switched_in_units": null,
          "switched_in_amount": null,
          "switched_in_price": null,
          "gateway": "rta",
          "traded_on": null,
          "scheduled_on": "2021-01-21",
          "created_at": "2021-01-03T19:21:04+05:30",
          "succeeded_at": null,
          "submitted_at": null,
          "reversed_at": null,
          "failed_at": null,
          "confirmed_at": null,
          "cancelled_at": null,
          "source_ref_id": null,
          "user_ip": null,
          "server_ip": null,
          "initiated_by": "investor",
          "initiated_via": "web",
          "euin": null,
          "partner": null,
          "failure_code": null
        }
      ]
    }
    

    Query Parameters

    Name Mandatory Type Comments
    mf_investment_account no string The investment account against which the switch orders are made.
    skip_instruction no string Provide skip instruction id to fetch switch orders that belong to the particular skip instruction.
    plan no string MF Switch Plan ID
    states no string Comma separated values of switch states

    Note:

    The response can contain 100 latest orders at max.

    FP Transaction Plans

    Transaction plans are used to generate orders on a recurring basis. FP supports 3 types of orders: Mutual fund purchase orders, Mutual fund redemption orders, and Mutual fund switch orders. If you want to generate these orders on a recurring basis, there are transaction plans for each order type viz. MF Purchase plans, MF Redemption plans, and MF Switch plans. All these plans (Purchase plan, Redemption plan, or Switch plan) have certain common characteristics. A solid understanding of these common characteristics will aid in implementing any kind of plan.

    Plan Mode

    By default, an MF Purchase plan generates lump sum purchases as installments, an MF Redemption plan generates redemption orders as installments and an MF switch plan generates switch orders as installments. The validations that are applicable when you create such orders manually are also applicable for installments generated via such plans. Apart from these validations, there are no restrictions on such plans. However, you can also register a plan as systematic. In such cases, an MF Purchase plan will be treated as a SIP, an MF Redemption plan will be treated as an SWP, and an MF Switch plan will be treated as STP. When a plan's mode is systematic, there will be some restrictions depending on the order gateway and other factors.

    Plan States

    State Description
    created The plan has been registered on FP but is yet to be activated. Irrespective of the type of plan, activation is automatically attempted by FP without any further intervention.
    active The plan is active. Only installments of an active plan can be generated and processed.
    cancelled The plan has been deactivated. No further installments will be generated.
    completed Lifecycle of a plan is completed i.e all the installments have been generated.
    failed Failure to activate a plan.

    State Transitions

    created active cancelled completed failed
    created NA Yes Yes No Yes
    active No NA Yes Yes No
    cancelled No No NA No No
    completed No No No NA No
    failed No No No No NA

    1. Transitioning from created to active

    Restrictions when the mode is systematic

    For example:
    Plan created_date= 01/05/2023 and installment_day= 4 then plan will move to active state on 05/05/2023 and first installment date would be 04/06/2023.

    Another example:

    Plan created_date= 29/01/2024 and mandate approved_at= 02/02/2024 and installment_day= 9 then plan will move to active state on 10/02/2023 and first installment date would be 09/03/2023.

    2. Transitioning from created to failed

    As noted earlier, if the mode is systematic, and order gateway = BSE, the plan becomes active only if the plan is registered at BSE also. If for some reason, the plan registration at BSE fails, the plan transitions from created ⇒ failed state.

    3. Transitioning from created to cancelled

    In cases of plans where delayed activation is opted for, you can request a cancellation before the plan becomes active, and the plan will transition from created to cancelled state.

    Note: As noted earlier, if mode = systematic, and order gateway = BSE, it takes time for a plan to become active. In such cases, if you choose to cancel a plan even before activation, the plan can have a created to cancelled transition.

    4. Transitioning from active to completed

    This transition happens automatically once all installments of a plan are generated. If the last installment of a plan is generated but is yet to be processed completely, the plan will still be marked as completed.

    5. Transitioning from active to cancelled

    Installments that are already generated, will not be impacted by the cancellation of a transaction plan. However, no installments of the plan can be generated after a plan reaches a cancelled state. Also, no modification can be made to a plan after a plan reaches the cancelled state. The cancellation of the plan happens immediately.

    Restrictions when the mode is systematic

    If mode is systematic, and order gateway = BSE, the cancellation happens asynchronously and will take some time. We will cover more on this topic when we discuss Purchase plans, Redemption plans, and Switch plans.

    Attribute Data type Nullable? Remarks
    state string No Plan's state
    created_at timestamp No Plan creation timestamp
    activated_at timestamp Yes Plan activation timestamp
    cancelled_at timestamp Yes Plan cancellation timestamp
    failed_at timestamp Yes Plan failure timestamp
    completed_at timestamp Yes Plan completion timestamp
    reason string Yes Reason for the state of the plan. For example, if the state is cancelled, the reason might contain a cancellation reason.

    Managing Recurrence of a Plan.

    Any transaction plan will let you specify the following -

    Different frequencies of a transaction plan

    Frequency Remarks Gateway Supported values for installment_day
    daily Transactions will be processed every business day. Transactions are not processed on market holidays.installment_day value is not applicable in this case. RTA only Not Applicable
    day_in_a_week You can select installment_day as any day between 1 (Monday) to 5 (Friday). On every selected day of the week, installments will be processed. For example, if you choose the installment_day as 1, every Monday installments will be processed. If a particular Monday falls on a market holiday, the installment will be processed on the immediate next working day. Also, in a particular month, there are 5 Mondays and in another month, there are 4 Mondays, installments will be processed 5 times and 4 times in those months respectively. RTA only 1-5
    four_times_a_month This is a variation of weekly SIP where every month, a fixed number of installments(4 per month with a gap of 7 days between consecutive installments) is processed.
    For example, if a user creates a plan on 28th February with installment_day as 22, the first installment is generated on 22nd March and post that the installments will be generated on the 1st, 8th, 15th and 22nd of every month.
    RTA only 1-28
    day_in_a_fortnight You can select installment_day as any day between 1 (Monday) to 5 (Friday). On every selected day of the alternate week, installments will be processed. For example, if you choose the installment_day as 1, every alternate Monday installments will be processed. If a particular Monday falls on a market holiday, the installment will be processed on the immediate next working day. Also, in a particular month, if there are 5 Mondays, installments will be processed 3 times for that month if the first installment of that month is processed on the first Monday. RTA only. 1-5
    twice_a_month This is a variation of fortnightly SIP where every month, a fixed number of installments (2 per month with a gap of 14 days) is processed.
    For example, if a user creates a plan on 28th February with installment_day as 22, the first installment is generated on 22nd March and post that the installments will be generated on the 8th and 22nd of every month.
    RTA only 1-28
    monthly 1 installment per month on the day specified via installment_day. If the day of installment happens to be a market holiday, the installment will be processed on the next business day.If the installment_day is 29,30 or 31 and in a particular month those days are not present, the installments will be processed on day 1 of the next month. If day 1 of next month is a market holiday, the transaction will be processed on the immediate next working day. RTA, BSE 1-28
    quarterly 1 installment per quarter on the day specified via installment_day. If the day of installment happens to be a market holiday, the installment will be processed on the next business day.If the installment_day is 29, 30 or 31 and in a particular month of the quarter those days are not present, the installments will be processed on day 1 of the next month. If day 1 of next month is a market holiday, the transaction will be processed on the immediate next working day. When quarterly plans are registered, FP will automatically try to generate the first installment on installment_day in the current month of the quarter. If that is not possible, an installment will be generated in the next quarter. From there, installments are generated after every quarter. However, using requested_activation_date, you can choose the month of the quarter on which the first installment should start.For example:
    SIP Registration date:July 21st 2022
    Requested activation date:August 15th 2022
    installment_day:1
    First installment date:September 1st 2022
    RTA only 1-28
    half-yearly Very similar to quarterly in behavior. 1 installment per 6 months on the day specified via installment_day. RTA only 1-28
    yearly Very similar to quarterly in behavior. 1 installment per year on the day specified via installment_day. RTA only 1-28

    Using number_of_installments to specify when to complete a plan.

    Special considerations when the mode is systematic - In cases of systematic plans, RTAs expect the installment count to be greater than a certain threshold. For example, this threshold is 6 minimum installments for SIPs usually. If you register an RTA SIP on FP with number_of_installments = 1, we internally register the SIP with RTAs with installment count as 6(which is the threshold.). However, after 1 installment is processed, we stop sending further installments to RTAs. - If the order gateway is BSE, the minimum number_of_installments must be greater than or equal to the minimum number_of_installments expected by that scheme/plan type. For example, in the case of SIPs, number_of_installments must be greater than or equal to 6 usually.

    Attribute Data type Nullable
    frequency string No
    installment_day integer Yes
    requested_activation_date date Yes
    number_of_installments integer No

    Installment Generation

    For a transaction plan, you can delegate the responsibility of generating installments to FP by creating a plan with auto_generate_installments = true.

    Behavior when installment generation is done by FP

    Definition of the day of the installment

    The definition of the day of installment depends on the plan type. FP supports 3 types of plans and the day installment definition is as follows

    Plan type Definition
    MF Purchase plan The day on which the payment collection happens
    MF Redemption plan The day on which redemption orders are submitted to RTA
    MF Switch plan The day on which redemption orders are submitted to RTA

    Minimum Gap

    Examples

    Plan Installment type Gateway Frequency Installment day Registration date First installment date
    Purchase plan Systematic RTA Monthly 15 August 15th, 2022 September 15th, 2022
    Purchase plan Systematic RTA Monthly 16 August 15th, 2022 August 16th, 2022
    Purchase plan Systematic BSE Monthly 15 August 15th, 2022 September 15th, 2022
    Purchase plan Systematic BSE Monthly 17 August 15th, 2022 September 17th, 2022
    Purchase plan Normal RTA Monthly 15 August 15th, 2022 September 15th, 2022
    Purchase plan Normal RTA Monthly 16 August 15th, 2022 August 16th, 2022
    Purchase plan Normal BSE Monthly 15 August 15th, 2022 September 15th, 2022
    Purchase plan Normal BSE Monthly 16 August 15th, 2022 August 16th, 2022
    Redemption/Switch plan Any Any Monthly 15 August 15th. 2022 September 15th, 2022
    Redemption/Switch plan Any Any Monthly 16 August 15th, 2022 August 16th, 2022

    Overcoming the minimum gap restrictions

    Simulate Installment Generation

    To help developers with testing in sandbox (non-production), the below respective manual installment generation APIs can be used to simulate the generation of installments.
    Installment generation can be simulated only for plans which are active.

    MF Purchase Plan Installment Generation
    MF Redemption Plan Installment Generation
    MF Switch Plan Installment Generation

    Installment information exposed by every transaction plan

    start_date - Date of installment of the first installment of the plan. - Will be available post plan activation if auto_generate_installments=true. - In the case of auto_generate_installments=false, the start_date will be populated only after you generate the first installment and it will be the date of generation of the first installment.

    end_date - Date of installment of the last installment of the plan. - Will be available post plan activation if auto_generate_installments=true. - In the case of auto_generate_installments=false, the end_date will be populated only when the plan is marked as completed. - This date will not be available if number_of_installments=null

    previous_installment_date - Date of installment of the previous installment - After plan completion, the value will equal end_date - Will be null at first. If FP is managing installment generation, once the date of installment of the nth (where n>=1) installment of the plan is passed, the previous_installment_date is set as the date of installment of nth installment. - If you are managing the installment generation, once you generate nth (where n>=2) installment, the previous_installment_date is set as the date of installment of n-1th installment.

    next_installment_date - Date of installment of the next installment - Will always be null if auto_generate_installments = false. - If FP is managing installment generation, next_installment_date will be set as the date of the first installment once the plan becomes active. After that, once the date of installment of the nth (where n>=1) installment of the plan is passed, the next_installment_date is set as date of installment of n+1th installment. - If a plan is completed, the next_installment_date will be null.

    remaining_installments - The number of installments yet to be generated. - Will be null if state = created or failed - Will always be null if number_of_installments = null (Perpetual plans) - Will be equal to number_of_installments when the plan becomes active. - Will always be null if the frequency is sporadic - Will become 0 once the plan is completed.

    Other Common Plan Attributes

    Attribute Data type Can be null? Remarks
    object string No Name of the transaction plan type object : Example: mf_purchase_plan, mf_redemption_plan etc
    id string No Unique id assigned by FP to identify the plan
    mf_investment_account string No Id of the investment account against which this plan is created.
    folio_number string Yes If the plan is a mutual fund transaction plan, every plan will also have this attribute to specify the folio against which the installments will be mapped.
    source_ref_id string Yes A unique identifier generated by API consumer to identity a particular plan. This is unique across plans of all types(purchase_plan, redemption_plan, and switch_plan).
    partner string No The id of the distributor/ria associated with the plan.
    gateway string No Can be bse or rta
    euin string Yes Unique identity number of the employee / relationship manager/ salesperson of the distributor who has advised or interacted with the investor in any other manner for this plan.
    user_ip string Yes IP address of end-user who has initiated the transaction.
    server_ip string No IP address of server through which the request to create this transaction was made.
    initiated_by string Yes The entity/person who has initiated this transaction. Possible values: investor, distributor
    initiated_via string Yes The medium via which this transaction was initiated. Possible values: mobile_app, mobile_app_android, mobile_app_ios, mobile_web_android, mobile_web_ios, mobile_web, web
    cancellation_scheduled_on date Yes The date on which the plan is scheduled for cancellation

    Skip Installments via Skip Instructions

    As per SEBI circular SEBI/HO/OW/IMD/IMD-SEC1/P/2024/270/1 dated 3rd January 2024, AMCs are required to follow common practice to allow "number of failed instalments" for a purchase plan from April 1st, 2024. Hence, while creating a skip instruction, FP will validate that the total number of installment to be skipped within from & to date is at least 1 less than the no. of installments that can be skipped as per the SEBI regulation applicable for the frequency of the purchase plan

    Frequency specific installments cancellation limit for systematic purchase plans

    FP Frequency No. of consecutive failed installment limit as per SEBI Remark
    daily 3 Currently, limit applicable for systematic plan only
    day_in_a_week 3 Currently, limit applicable for systematic plan only
    four_times_a_month 3 Currently, limit applicable for systematic plan only
    day_in_a_fortnight 3 Currently, limit applicable for systematic plan only
    twice_a_month 3 Currently, limit applicable for systematic plan only
    monthly 3 Currently, limit applicable for systematic plan only
    quarterly 2 Currently, limit applicable for systematic plan only
    half-yearly 2 Currently, limit applicable for systematic plan only
    yearly 2 Currently, limit applicable for systematic plan only

    Validations while skipping a systematic purchase plan

    This is only for reference. The behaviour applies to all frequencies of systematic purchase plan. Installment no. is determined using the from and to date of the skip instruction

    Scenario Skip instruction Result Remarks
    Say in a daily plan, installment 1, 2 ,3 are payment completed and awaiting order processing updates from RTA Investor tries to skip installment no. 20, 21 Allowed
    Installment 1 is success, 2&3 failed Investor tries to skip installment no. 20, 21 Allowed There is scope that installment 4 can be successful
    Installment 1 is success, 2&3 failed Investor tries to skip installment no. 4, 5 Not allowed Cancelling installment 4 will result in 3 consecutive failures and crosses the limit defined by SEBI
    Installment 1,2,3 success Investor tries to skip installment no. 4, 5, 6 Not allowed Regardless of previous installment statuses, this will result in 3 consecutive failures and crosses the limit defined by SEBI

    Read more











    Skip Instruction Object Attributes

    {
      "object": "plan_skip_instruction",
      "id": "psi_c59dc2c59a44442aa24f34b675f5ca63",
      "plan": "mfpp_4ff42f15028d41c4ab6fbf38a5311d10",
      "state": "PENDING",
      "remaining_installments": "3",
      "skipped_installments": "0",
      "created_at": "2023-02-16T06:50:18+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "from_date": "2023-03-15",
      "to_date": "2023-06-23"
    }
    
    Attribute Data type Can be null? Remarks
    object string No Will always be skip_instruction
    id string No Unique id assigned by FP to identify skip instruction
    plan string No Transaction plan identifier
    state string No Values : pending,active,completed, cancelled
    from string No The date from which the installments must be skipped
    to string conditional The date till which the installments must be skipped. Mandatory if plan is systematic purchase
    remaining_installments int No The number of installments remaining to be skipped.
    skipped_installments int No The number of installments skipped already.
    created_at date No The date on which this skip instruction is created.
    cancelled_at date Yes The date on which this skip instruction was cancelled.
    completed_at date Yes The date on which this skip instruction was cancelled.









    Create a skip instruction

    curl -X POST "https://s.finprim.com/v2/mf_purchase_plans/mfpp_4ff42f15028d41c4ab6fbf38a5311d1/skip_instructions"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    POST /v2/mf_purchase_plans/:id/skip_instructions
    POST /v2/mf_redemption_plans/:id/skip_instructions
    POST /v2/mf_switch_plans/:id/skip_instructions

    JSON Request:

    {
      "from": "2023-03-15",
      "to": "2023-06-23"
    }
    

    Request Parameters

    Name Mandatory Type Comments
    from Yes date The date from which the installments must be skipped.
    to No date The date till which the installments must be skipped.

    JSON Response:

    {
      "object": "plan_skip_instruction",
      "id": "psi_c59dc2c59a44442aa24f34b675f5ca63",
      "plan": "mfpp_4ff42f15028d41c4ab6fbf38a5311d10",
      "state": "PENDING",
      "remaining_installments": "3",
      "skipped_installments": "0",
      "created_at": "2023-02-16T06:50:18+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "from_date": "2023-03-15",
      "to_date": "2023-06-23"
    }
    


















    Fetch a skip instruction by its id

    JSON Request:

    curl -X GET "https://s.finprim.com/v2/mf_purchase_plans/skip_instructions/psi_c59dc2c59a44442aa24f34b675f5ca63"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    GET /v2/mf_purchase_plans/skip_instructions/:id
    GET /v2/mf_redemption_plans/skip_instructions/:id
    GET /v2/mf_switch_plans/skip_instructions/:id

    This API is used to fetch a skip instruction by its id

    Query Parameters

    Name Mandatory Type Comments
    id yes string Id of the skip instruction.

    JSON Response:

    {
      "object": "plan_skip_instruction",
      "id": "psi_c59dc2c59a44442aa24f34b675f5ca63",
      "plan": "mfpp_4ff42f15028d41c4ab6fbf38a5311d10",
      "state": "PENDING",
      "remaining_installments": "3",
      "skipped_installments": "0",
      "created_at": "2023-02-16T06:50:18+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "from_date": "2023-03-15",
      "to_date": "2023-06-23"
    }
    















    Cancel a skip instruction

    JSON Request:

    curl -X POST "https://s.finprim.com/v2/mf_purchase_plans/skip_instructions/psi_c59dc2c59a44442aa24f34b675f5ca63/cancel"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    POST /v2/mf_purchase_plans/skip_instructions/:id/cancel
    POST /v2/mf_redemption_plans/skip_instructions/:id/cancel
    POST /v2/mf_switch_plans/skip_instructions/:id/cancel

    This API is used to cancel a skip instruction.

    JSON Response:

    {
      "object": "plan_skip_instruction",
      "id": "psi_5cbc6c2e094647379a5c53613ba43368",
      "plan": "mfpp_9374c954dd384c1489b6d8cf11a227db",
      "state": "PENDING",
      "remaining_installments": "2",
      "skipped_installments": "0",
      "created_at": "2023-01-30T05:22:24+05:30",
      "cancelled_at": "2023-01-30T05:29:23+05:30",
      "completed_at": null,
      "from_date": "2023-04-01",
      "to_date": "2023-05-01"
    }
    


















    List all skip instructions for a plan

    JSON Request:

    curl -X GET "https://s.finprim.com/v2/mf_purchase_plans/mfpp_9374c954dd384c1489b6d8cf11a227db/skip_instructions?status=pending"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    GET /v2/mf_purchase_plans/:id/skip_instructions
    GET /v2/mf_redemption_plans/:id/skip_instructions
    GET /v2/mf_switch_plans/:id/skip_instructions

    This API is used to list all skip instructions against a plan.

    JSON Response:

    {
      "object": "list",
      "data": [
        {
          "object": "plan_skip_instruction",
          "id": "psi_7313fd80a3c54e769dfcb06a93ba1368",
          "plan": "mfpp_9374c954dd384c1489b6d8cf11a227db",
          "state": "PENDING",
          "remaining_installments": "2",
          "skipped_installments": "0",
          "created_at": "2023-01-30T04:49:25+05:30",
          "cancelled_at": null,
          "completed_at": null,
          "from_date": "2023-04-01",
          "to_date": "2023-05-01"
        },
        {
          "object": "plan_skip_instruction",
          "id": "psi_5cbc6c2e094647379a5c53613ba43368",
          "plan": "mfpp_9374c954dd384c1489b6d8cf11a227db",
          "state": "PENDING",
          "remaining_installments": "2",
          "skipped_installments": "0",
          "created_at": "2023-01-30T05:22:24+05:30",
          "cancelled_at": "2023-01-30T05:29:23+05:30",
          "completed_at": null,
          "from_date": "2023-04-01",
          "to_date": "2023-05-01"
        },
        {
          "object": "plan_skip_instruction",
          "id": "psi_5b0e683b71124e9ebd5f21b6d1b95734",
          "plan": "mfpp_9374c954dd384c1489b6d8cf11a227db",
          "state": "PENDING",
          "remaining_installments": "2",
          "skipped_installments": "0",
          "created_at": "2023-01-30T05:35:58+05:30",
          "cancelled_at": null,
          "completed_at": null,
          "from_date": "2023-04-01",
          "to_date": "2023-05-01"
        }
      ]
    }
    

    Query Parameters

    Name Mandatory Type Comments
    statuses no string array Skip instruction statuses. By default, the value will be null i.e. skip instructions of all statuses against a particular plan will be displayed. You can provide status values like pending,active,completed, cancelled to filter by statuses

    Modifying Plans

    Below modification can only be done in case of non-systematic plans.

    Changing the number of installments of a non-systematic plan

    Changing the installment day of a non-systematic plan

    Example (frequency = twice_a_month)

    Field Value
    plan registered on 28th Feb'23
    frequency twice_a_month
    current start_date 1st Mar'23
    no. of installments 5
    current end_date 1st May'23
    current installment_day 1
    Expected installment dates 1, 14 of the month
    installment_day changed on new installment_day new installment dates new start_date next installment number next_installment_date new end_date
    28th Feb'23 26 12, 26 of the month 01-03-2023 2nd 26-03-2023 12-05-2023
    7th Mar'23 26 12, 26 of the month 01-03-2023 2nd 26-03-2023 12-05-2023
    17th Mar'23 26 12, 26 of the month 01-03-2023 3rd 12-04-2023 12-05-2023


    Example (frequency = four_times_a_month)

    Field Value
    plan registered on 28th Feb'23
    frequency four_times_a_month
    current start_date 1st Mar'23
    no. of installments 5
    current end_date 1st Apr'23
    current installment_day 1
    Expected installment dates 1, 7, 14, 21 of the month
    installment_day changed on new installment_day new installment dates new start_date next installment number next_installment_date new end_date
    28th Feb'23 26 5, 12, 19, 26 of the month 01-03-2023 2nd 12-03-2023 05-04-2023
    7th Mar'23 26 5, 12, 19, 26 of the month 01-03-2023 3rd 19-03-2023 05-04-2023
    17th Mar'23 26 5, 12, 19, 26 of the month 01-03-2023 4th 26-03-2023 05-04-2023
    22nd Mar'23 26 5, 12, 19, 26 of the month 01-03-2023 5th 05-04-2023 05-04-2023

    Cancelling a plan

    Restrictions when the mode is systematic and order gateway is BSE
    In the case of MF Purchase plans, gap is 7 working days. i.e. only if you cancel the plan before 7 working days from the date of the next installment, the next installment will not be processed. If not, the next installment will be processed and subsequent installments after that will not be processed.
    In the case of MF Redemption plans/ MF Switch plans, gap is 1 working day.

    MF Purchase Plans

    MF Purchase plan represents a plan defined to create purchase orders on a recurring basis.

    Endpoints

    POST /v2/mf_purchase_plans
    PATCH /v2/mf_purchase_plans
    GET /v2/mf_purchase_plans/:id
    GET /v2/mf_purchase_plans
    POST /v2/mf_purchase_plans/:id/cancel
    POST /v2/mf_purchase_plans/:id/skip_instructions
    GET /v2/mf_purchase_plans/skip_instructions/:id
    POST /v2/mf_purchase_plans/skip_instructions/:id/cancel
    GET /v2/mf_purchase_plans/:id/skip_instructions

    Purchase Plan Object Structure

    {
      "object": "mf_purchase_plan",
      "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "created",
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "systematic": true,
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "auto_generate_instalments": true,
      "installment_day": 1,
      "start_date": "2022-04-01",
      "end_date": "2022-11-01",
      "requested_activation_date": null,
      "number_of_installments": 7,
      "next_installment_date": "2022-06-01",
      "previous_installment_date": "2022-05-01",
      "remaining_installments": 6,
      "amount": 1000.0,
      "payment_method": null,
      "payment_source": null,
      "purpose": "children_education",
      "source_ref_id": null,
      "euin": null,
      "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2022-04-01T17:51:21+05:30",
      "activated_at": "2022-04-01T17:51:21+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "cancellation_scheduled_on": null,
      "cancellation_code": null,
      "reason": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": "investor",
      "initiated_via": "mobile_app"
    }
    
    Attribute Data type Can be null? Remarks
    object string No Will always be mf_purchase_plan
    id string No Unique identifier of the mf_purchase_plan object
    mf_investment_account string No This is the ID of the investment account object, and you can identify the investment account associated with the purchase plan using this id
    folio_number string Yes Indicates the folio in which the purchases resulting from this plan will be made
    scheme string No ISIN of the scheme against whose units must be purchased periodically.
    amount decimal No Periodic purchase amount
    systematic boolean No The value of this attribute indicates the way this purchase plan is registered with order gateways.
    - If the value is true, it means that the plan is registered as a Systematic Investment Plan with RTA/BSE and every installment is considered as a traditional SIP installment.
    - If the value is false, FP will create a lumpsum purchase order according to the defined schedule and send it to order gateway. Since each installment of this plan is a lumpsum purchase order and not a traditional SIP installment, consent is required before creating payment for each installment. You can create a non systematic purchase plan in case of both RTA and BSE gateway.
    frequency string No See details here
    installment_day integer Conditional See details here
    requested_activation_date date Yes See details here
    number_of_installments integer No See details here
    start_date date Yes See details here
    end_date date Yes See details here
    next_installment_date date Yes See details here
    previous_installment_date date Yes See details here
    remaining_installments integer Yes See details here
    state string No See details here
    auto_generate_installments boolean No See details here
    payment_method string Yes The payment method that must be used for collecting payments against the installments.Possible value:mandate.
    payment_source string Yes Unique identifier identifying the payment collection instrument. For example, If payment_method is mandate, payment_source will be the mandate id.
    purpose string Yes Why was this purchase plan created? Possible values can be children_education, children_marriage, house, car, travel, retirement, others
    source_ref_id string Yes See details here
    partner string No See details here
    gateway string No See details here
    euin string Yes See details here
    user_ip string Yes See details here
    server_ip string Yes See details here
    initiated_by string Yes See details here
    initiated_via string Yes See details here
    created_at timestamp No See details here
    activated_at timestamp Yes See details here
    cancelled_at timestamp Yes See details here
    cancellation_scheduled_on date Yes See details here
    failed_at timestamp Yes See details here
    completed_at timestamp Yes See details here
    cancellation_code string Yes See details allowed cancellation codes here

    Create a purchase plan

    POST /v2/mf_purchase_plans

    curl -X POST "https://s.finprim.com/v2/mf_purchase_plans"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Request:

    {
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "scheme": "INF204KA1B64",
      "frequency": "monthly",
      "folio_number": "1234567890",
      "amount": 1000.0,
      "installment_day": 1,
      "number_of_installments": 7,
      "systematic": true,
      "payment_method": "mandate",
      "payment_source": "24",
      "purpose": "children_education",
      "generate_first_installment_now": true,
      "auto_generate_installments": true,
      "activate_after": null,
      "euin": null,
      "initiated_by": "investor",
      "initiated_via": "mobile_app",
      "user_ip": null,
      "server_ip": null,
      "source_ref_id": null,
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd_code": "91",
        "mobile": "9008580644"
      }
    }
    

    JSON Response:

    {
      "object": "mf_purchase_plan",
      "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "created",
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "systematic": true,
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "auto_generate_instalments": true,
      "installment_day": 1,
      "start_date": "2022-04-01",
      "end_date": "2022-11-01",
      "requested_activation_date": null,
      "number_of_installments": 7,
      "next_installment_date": "2022-06-01",
      "previous_installment_date": "2022-05-01",
      "remaining_installments": 6,
      "amount": 1000.0,
      "payment_method": null,
      "payment_source": null,
      "purpose": "children_education",
      "source_ref_id": null,
      "euin": null,
      "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2022-04-01T17:51:21+05:30",
      "activated_at": "2022-04-01T17:51:21+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "cancellation_scheduled_on": null,
      "cancellation_code": null,
      "reason": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": "investor",
      "initiated_via": "mobile_app"
    }
    

    Request Parameters

    Name Mandatory Type Comments
    mf_investment_account Yes string The id of the investment account against which the plan must be created.
    scheme Yes string The isin of the scheme against which purchases must be made.
    frequency Yes string See details here
    folio_number No string If the folio number is given, purchases will be made against the given folio.
    But if folio number is not given, FP requests AMC to create a new folio. In this case, please ensure that investor consent has been taken (by OTP 2FA method) to add nomination against the new folio before the plan creation.
    amount Yes decimal The installment amount.
    1) If systematic = true, amount should be in multiples of sip_multiples and between min_sip_amount and max_sip_amount
    2) If systematic = false and folio number is not provided,the amount should be between min_initial_investment and max_initial_investment and should be a multiple of initial_investment_multiples
    3) If systematic = false and folio number is provided, the amount should be between min_additional_investment and max_additional_investment and should be a multiple of additional_investment_multiples
    installment_day Conditional integer Should be null for frequency = daily
    See details here
    number_of_installments Yes integer See details here
    systematic Yes string See Details Here
    payment_method Yes, if systematic = true and gateway = bse string The payment method that must be used for collecting payments against the installments.Possible value:mandate.
    Mandatory if payment_source is not null.
    This feature is not supported in BSE for plans with systematic = false
    payment_source Yes, if systematic = true and gateway = bse string Unique identifier identifying the payment collection instrument. For example, If payment_method is mandate, payment_source will be the mandate id.
    Mandatory if payment_method is not null.
    This feature is not supported in BSE for plans with systematic = false
    purpose No string Why was this purchase plan created? Possible values can be children_education, children_marriage, house, car, travel, retirement, others
    generate_first_installment_now No boolean See details here
    The value is false by default.
    auto_generate_installments No boolean See details here
    activate_after No string A date in the future on which the registration of this plan must be initiated.
    This feature is available for plans created via RTA route only.
    initiated_by No string See details here
    initiated_via No string See details here
    euin No string See details here
    user_ip No string See details here
    server_ip No string See details here
    source_ref_id No string See details here
    order_gateway no string The gateway through which the order needs to be submitted for processing. Possible values: rta, bse.
    If value is null, then order will be routed through the default gateway which is configured for the tenant. Currently this attribute can be used by tenants configured with the BSE gateway only.
    consent No hash Consent from investor for confirming the order
    Once set, this cannot be modified.
    partner no string See Details Here

    Note:- If consent is not collected in create API then the plan would be in created state. To move it to active state you need to collect consent via update API.

    As per SEBI regulations, 2FA has been mandated for SIP registrations -

    1. Before order is sent to RTAs, investor consent must be obtained by sending a One-Time Password to the investor at his email/phone number -

      • In case of order placed against an existing folio the OTP should be sent to the email/ mobile registered against the existing folio.
      • In case of an order placed without a folio, the OTP should be sent to the email/mobile present in the folio_defaults of MF investment account.
    2. Before order is sent to BSE, investor consent must be obtained by sending a One-Time Password to the investor at his email and phone number, and consent can be collected either by email/mobile -

      • In case of order placed against an existing folio the OTP should be sent to the email and mobile registered against the existing folio.
      • In case of order placed without folio the OTP should be sent to the email and mobile registered against the UCC.

    To comply with the above -

    1. While registering for a SIP via RTA, either email or mobile or both can be added as a part of the consent object.
    2. While registering for a SIP via BSE, both email and mobile should be added as a part of the consent object.
    Name Mandatory Type Comments
    email conditional string Mandatory if consent is obtained via email.
    isd_code conditional string Mandatory if consent is obtained via mobile.
    Only integers are allowed, also + can be added at the start.
    Max character length is 4 including +
    mobile conditional string Mandatory if consent is obtained via mobile.
    Only integers and - are allowed
    Min and Max character length is 7 and 20

    Update a purchase plan

    PATCH /v2/mf_purchase_plans

    Note

    curl -X PATCH "https://s.finprim.com/v2/mf_purchase_plans"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Request:

    {
      "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
      "amount": 1500.0
    }
    

    JSON Response:

    {
      "object": "mf_purchase_plan",
      "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "active",
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567899",
      "systematic": false,
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "auto_generate_instalments": true,
      "installment_day": 1,
      "start_date": "2022-04-01",
      "end_date": "2022-11-01",
      "requested_activation_date": null,
      "number_of_installments": 7,
      "next_installment_date": "2022-06-01",
      "previous_installment_date": "2022-05-01",
      "remaining_installments": 6,
      "amount": 1500.0,
      "payment_method": null,
      "payment_source": null,
      "purpose": "children_education",
      "source_ref_id": null,
      "euin": null,
      "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2022-04-01T17:51:21+05:30",
      "activated_at": "2022-04-01T17:51:21+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "cancellation_scheduled_on": null,
      "cancellation_code": null,
      "reason": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": "investor",
      "initiated_via": "mobile_app"
    }
    

    Request Parameters

    Name Mandatory Type Comments
    id Yes string V2 plan ID
    amount No decimal Installment amount
    installment_day No integer See Details Here
    number_of_installments No integer See Details Here
    payment_method No string Possible values: mandate
    payment_source No string If payment_method is mandate, payment_source will be the mandate id. Mandatory input if payment_method is not null.
    consent No hash Consent from investor for confirming the order
    Once set, this cannot be modified.

    Note for BSE

    You can only update mandate(payment_source) for the MF purchase plans if plan gateway = bse. When you update mandate via FP API changes would only be reflected in FP and not in BSE. You have to manually update mandate of SIP in BSE member portal,

    Follow below steps in order to update a mandate

    Fetch a purchase plan by its id

    GET /v2/mf_purchase_plans/:id

    This API can be used to fetch a purchase plan by its plan ID.

    curl -X GET "https://s.finprim.com/v2/mf_purchase_plans/mfpp_dbabb25ba34c48329dbfbeff70c846f0"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Response:

    {
      "object": "mf_purchase_plan",
      "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "created",
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "systematic": true,
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "auto_generate_instalments": true,
      "installment_day": 1,
      "start_date": "2022-04-01",
      "end_date": "2022-11-01",
      "requested_activation_date": null,
      "number_of_installments": 7,
      "next_installment_date": "2022-06-01",
      "previous_installment_date": "2022-05-01",
      "remaining_installments": 6,
      "amount": 1000.0,
      "payment_method": null,
      "payment_source": null,
      "purpose": "children_education",
      "source_ref_id": null,
      "euin": null,
      "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2022-04-01T17:51:21+05:30",
      "activated_at": "2022-04-01T17:51:21+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "cancellation_scheduled_on": null,
      "cancellation_code": null,
      "reason": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": "investor",
      "initiated_via": "mobile_app"
    }
    

    List all purchase plans

    GET /v2/mf_purchase_plans

    This API is used to fetch all purchase plans.

    curl -X GET "https://s.finprim.com/v2/mf_purchase_plans?mf_investment_account=mfia_798fa03aba614840b983609e89ed16f2&states=active"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Response:

    {
      "object": "list",
      "data": [
        {
          "object": "mf_purchase_plan",
          "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
          "state": "active",
          "systematic": true,
          "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
          "folio_number": "1234567890",
          "frequency": "monthly",
          "scheme": "INF204KA1B64",
          "installment_day": 1,
          "start_date": "2022-04-01",
          "end_date": "2022-11-01",
          "requested_activation_date": null,
          "auto_generate_instalments": true,
          "number_of_installments": 7,
          "next_installment_date": "2022-06-01",
          "previous_installment_date": "2022-05-01",
          "remaining_installments": 6,
          "amount": 1000.0,
          "source_ref_id": null,
          "euin": null,
          "payment_method": null,
          "payment_source": null,
          "purpose": "children_education",
          "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
          "created_at": "2022-04-01T17:51:21+05:30",
          "activated_at": "2022-04-01T17:51:21+05:30",
          "cancelled_at": null,
          "completed_at": null,
          "failed_at": null,
          "cancellation_scheduled_on": null,
          "cancellation_code": null,
          "gateway": "rta",
          "user_ip": null,
          "server_ip": null,
          "initiated_by": null,
          "initiated_via": null
        },
        {
          "object": "mf_purchase_plan",
          "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
          "state": "active",
          "systematic": true,
          "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
          "folio_number": "1234567890",
          "frequency": "monthly",
          "scheme": "INF204KA1B64",
          "installment_day": 1,
          "start_date": "2022-01-01",
          "end_date": "2022-07-01",
          "requested_activation_date": null,
          "auto_generate_instalments": true,
          "number_of_installments": 7,
          "next_installment_date": "2022-04-01",
          "previous_installment_date": "2022-05-01",
          "remaining_installments": 6,
          "amount": 1000.0,
          "source_ref_id": null,
          "euin": null,
          "payment_method": null,
          "payment_source": null,
          "purpose": "children_education",
          "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
          "created_at": "2022-04-01T17:51:21+05:30",
          "activated_at": "2022-04-01T17:51:21+05:30",
          "cancelled_at": null,
          "completed_at": null,
          "failed_at": null,
          "cancellation_scheduled_on": null,
          "cancellation_code": null,
          "gateway": "rta",
          "user_ip": null,
          "server_ip": null,
          "initiated_by": null,
          "initiated_via": null
        }
      ]
    }
    

    Query Parameters

    Name Mandatory Type Comments
    mf_investment_account no string The investment account against which the purchase plans are created.
    states no string-array Multiple plan states separated by comma.

    Cancel a purchase plan

    POST /v2/mf_purchase_plans/:id/cancel (Deprecated)

    This end point is planned to be deprecated by Mar 29th, 2024. Check more details here

    POST /v2/mf_purchase_plans/cancel

    This API can be used to cancel a plan using its plan ID. For more details, please see here

    curl --location 'https://s.finprim.com//v2/mf_purchase_plans/cancel'
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    -- data '{
    
        "id":"mfpp_312ce2258eb743c2a05b60bb99216409" ,
        "cancellation_code":"investment_returns_not_as_expected"
    }'
    

    JSON Response:

    {
      "object": "mf_purchase_plan",
      "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "cancelled",
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "systematic": true,
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "auto_generate_instalments": true,
      "installment_day": 1,
      "start_date": "2022-04-01",
      "end_date": "2022-11-01",
      "requested_activation_date": null,
      "number_of_installments": 7,
      "next_installment_date": "2022-06-01",
      "previous_installment_date": "2022-05-01",
      "remaining_installments": 6,
      "amount": 1000.0,
      "payment_method": null,
      "payment_source": null,
      "purpose": "children_education",
      "source_ref_id": null,
      "euin": null,
      "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2022-04-01T17:51:21+05:30",
      "activated_at": "2022-04-01T17:51:21+05:30",
      "cancelled_at": "2022-05-04T17:51:21+05:30",
      "completed_at": null,
      "failed_at": null,
      "cancellation_scheduled_on": null,
      "cancellation_code": "investment_returns_not_as_expected",
      "reason": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": "investor",
      "initiated_via": "mobile_app"
    }
    

    Request Parameters

    Name Mandatory Type Comments
    id Yes string V2 plan ID
    cancellation_code Yes string Mandatory

    Allowed cancellation codes to cancel a purchase plan

    cancellation_code Remarks
    amount_not_available Investor does not have amount or is unable to continue due to some bank level debit issues
    investment_returns_not_as_expected Investor did not get returns as expected as the scheme is not performing
    exit_load_not_as_expected Investor is not satisfied with exit load (existing or revised)
    switch_to_other_scheme Investor wishes to switch to another scheme
    fund_manager_changed Investor is not satisfied with change in fund manager
    investment_goal_complete Investor has achieved the investment goal earlier than planned
    mandate_not_ready Mandate is not ready for use (either not in approved state or not created)
    invest_later Investor chose to invest at a later point in time
    customer_support_not_satisfactory Investor not satisfied with the service at distribution level
    amc_support_not_satisfactory Investor not satisfied with the service at AMC level

    Auto cancellation of systematic purchase plans

    As per SEBI circular SEBI/HO/OW/IMD/IMD-SEC1/P/2024/270/1 dated 3rd January 2024, AMCs are required to follow common practice to allow "number of failed instalments" for a purchase plan from April 1st, 2024.

    Frequency specific installments cancellation limit

    FP Frequency No. of consecutive failed installment limit as per SEBI Remark
    daily 3 Currently, limit applicable for systematic plan only
    day_in_a_week 3 Currently, limit applicable for systematic plan only
    four_times_a_month 3 Currently, limit applicable for systematic plan only
    day_in_a_fortnight 3 Currently, limit applicable for systematic plan only
    twice_a_month 3 Currently, limit applicable for systematic plan only
    monthly 3 Currently, limit applicable for systematic plan only
    quarterly 2 Currently, limit applicable for systematic plan only
    half-yearly 2 Currently, limit applicable for systematic plan only
    yearly 2 Currently, limit applicable for systematic plan only
    1. FP will mark a purchase plan as cancelled automatically if the plan is systematic and the number of consecutive failed\skipped instalments is more than the limit suggested by SEBI. Purchase plan will also have a cancellation_code attribute with value as consecutive_failed_installment_limit_exceeded. Read more

    2. We recommend you to make a note of these limits if you are skipping installments from your front end application.

    3. More importantly, we recommend you to keep the investors informed about auto cancellation of the plans via notifications every-time an installment is skipped\failed or when the plan is cancelled due to consecutive installment failures.

    MF Redemption Plans

    MF Redemption plan represents a plan defined to create redemption orders on a recurring basis.

    Endpoints

    POST /v2/mf_redemption_plans
    PATCH /v2/mf_redemption_plans
    GET /v2/mf_redemption_plans/:id
    GET /v2/mf_redemption_plans
    POST /v2/mf_redemption_plans/:id/cancel
    POST /v2/mf_redemption_plans/:id/skip_instructions
    GET /v2/mf_redemption_plans/skip_instructions/:id
    POST /v2/mf_redemption_plans/skip_instructions/:id/cancel
    GET /v2/mf_redemption_plans/:id/skip_instructions

    Redemption Plan Object Structure

    {
      "object": "mf_redemption_plan",
      "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "created",
      "systematic": true,
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "installment_day": 1,
      "start_date": "2022-04-01",
      "end_date": "2022-11-01",
      "number_of_installments": 7,
      "auto_generate_installments": true,
      "next_installment_date": "2022-06-01",
      "previous_installment_date": "2022-05-01",
      "remaining_installments": 6,
      "amount": 1000.0,
      "source_ref_id": null,
      "euin": null,
      "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2022-04-01T17:51:21+05:30",
      "activated_at": "2022-04-01T17:51:21+05:30",
      "requested_activation_date": null,
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "cancellation_scheduled_on": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null,
      "reason": null,
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd_code": "91",
        "mobile": "9008580644"
      }
    }
    
    Attribute Data type Can be null? Remarks
    object string No Will always be mf_redemption_plan
    id string No Unique identifier of the mf_redemption_plan object
    mf_investment_account string No This is the ID of the investment account object, and you can identify the investment account associated with the redemption plan using this id
    folio_number string Yes Indicates the folio from which the redemptions must be made.
    scheme string No ISIN of the scheme from which units must be sold.
    amount decimal No Periodic redemption amount
    systematic boolean No The value of this attribute indicates the way this redemption plan is registered with order gateways.
    - If the value is true, it means that the plan is registered as a Systematic Withdrawal Plan with RTA/BSE and every installment is considered as a traditional SWP installment.
    - If the value is false, FP will create a redemption order according to the defined schedule and send it to order gateway. Since each installment of this plan is a redemption order and not a traditional SWP installment, consent for each installment is required before the order is sent to the order gateway. You cannot create a non systematic redemption plan in case if order gateway is BSE
    frequency string No See details here
    installment_day integer Conditional See details here
    requested_activation_date date Yes See details here
    number_of_installments integer No See details here
    start_date date Yes See details here
    end_date date Yes See details here
    next_installment_date date Yes See details here
    previous_installment_date date Yes See details here
    remaining_installments Yes integer See details here
    state string No See details here
    auto_generate_installments boolean No See details here
    source_ref_id string Yes See details here
    partner string No See details here
    gateway string No See details here
    euin string Yes See details here
    user_ip string Yes See details here
    server_ip string Yes See details here
    initiated_by string Yes See details here
    initiated_via string Yes See details here
    created_at timestamp No See details here
    activated_at timestamp Yes See details here
    cancelled_at timestamp Yes See details here
    cancellation_scheduled_on date Yes See details here
    failed_at timestamp Yes See details here
    completed_at timestamp Yes See details here
    reason string Yes See details here
    consent object No Consent from investor for confirming the redemption

    As per SEBI regulations, investor consent must be obtained by sending a One-Time Password to the investor at his/her email/phone number registered against the folio before the redemption order can be sent to rtas.

    Name Mandatory Type Comments
    email conditional string Mandatory if consent is obtained via email. The value must be one of the email addresses registered against the folio.
    isd_code conditional string Mandatory if consent is obtained via mobile.
    Only integers are allowed, also + can be added at the start.
    Max character length is 4 including +
    mobile conditional string Mandatory if consent is obtained via mobile.
    The value must be one of the mobile numbers registered against the folio.

    Only integers and - are allowed
    Min and Max character length is 7 and 20

    Create a redemption plan

    POST /v2/mf_redemption_plans

    curl -X POST "https://s.finprim.com/v2/mf_redemption_plans"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Request:

    {
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "amount": 1000.0,
      "scheme": "INF204KA1B64",
      "frequency": "monthly",
      "installment_day": 1,
      "number_of_installments": 7,
      "generate_first_installment_now": true,
      "auto_generate_installments": true,
      "activate_after": null,
      "initiated_by": null,
      "initiated_via": null,
      "user_ip": null,
      "server_ip": null,
      "source_ref_id": null,
      "euin": null,
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd_code": "91",
        "mobile": "9008580644"
      }
    }
    

    JSON Response:

    {
      "object": "mf_redemption_plan",
      "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "created",
      "systematic": true,
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "installment_day": 1,
      "start_date": "2022-04-01",
      "end_date": "2022-11-01",
      "number_of_installments": 7,
      "auto_generate_installments": true,
      "next_installment_date": "2022-06-01",
      "previous_installment_date": "2022-05-01",
      "remaining_installments": 6,
      "amount": 1000.0,
      "source_ref_id": null,
      "euin": null,
      "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2022-04-01T17:51:21+05:30",
      "activated_at": "2022-04-01T17:51:21+05:30",
      "requested_activation_date": null,
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "cancellation_scheduled_on": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null,
      "reason": null,
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd_code": "91",
        "mobile": "9008580644"
      }
    }
    

    Request Parameters

    Name Mandatory Type Comments
    mf_investment_account Yes string The id of the investment account against which the plan must be created.
    scheme Yes string The isin of the scheme against which redemptions must be made.
    frequency Yes string See details here
    folio_number Yes string Folio from which the redemptions must be made
    amount Yes decimal The installment amount.
    1) If systematic = true, amount should be in multiples of swp_multiples and between min_swp_amount and max_swp_amount
    2) If systematic = false and folio number is not provided,the amount should be between min_swp_amount and max_swp_amount and should be a multiple of swp_multiples
    3) If systematic = false, the amount should be between min_withdrawal_amount and max_withdrawal_amount and should be a multiple of withdrawal_multiples
    installment_day Conditional integer Should be null for frequency = daily
    See details here
    number_of_installments Yes integer See details here
    systematic Yes string See Details Here
    generate_first_installment_now No boolean See details here
    The value is false by default.
    auto_generate_installments No boolean The facility of installment generation on demand is not available for BSE SIPs. In other words, when gateway is bse and systematic=true, this value cannot be false. By default, the value is true.
    activate_after No string A date in the future on which the registration of this plan must be initiated.
    This feature is available for plans created via RTA route only.
    initiated_by No string See details here
    initiated_via No string See details here
    euin No string See details here
    user_ip No string See details here
    server_ip No string See details here
    source_ref_id No string See details here
    order_gateway no string The gateway through which the order needs to be submitted for processing. Possible values: rta, bse.
    If value is null, then order will be routed through the default gateway which is configured for the tenant. Currently this attribute can be used by tenants configured with the BSE gateway only.
    consent No hash Consent from investor for confirming the redemption
    Once set,this cannot be modified
    partner no string See Details Here

    Note:- If consent is not collected in create API then the plan would be in created state. To move it to active state you need to collect consent via update API.

    Update a redemption plan

    PATCH /v2/mf_redemption_plans

    Note

    curl -X PATCH "https://s.finprim.com/v2/mf_redemption_plans"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Request:

    {
      "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
      "amount": "1000"
    }
    

    JSON Response:

    {
      "object": "mf_redemption_plan",
      "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "active",
      "systematic": true,
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "installment_day": 1,
      "start_date": "2022-04-01",
      "end_date": "2022-11-01",
      "number_of_installments": 7,
      "auto_generate_installments": true,
      "next_installment_date": "2022-06-01",
      "previous_installment_date": "2022-05-01",
      "remaining_installments": 6,
      "amount": 1000.0,
      "source_ref_id": null,
      "euin": null,
      "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2021-04-01T17:51:21+05:30",
      "activated_at": "2021-04-01T17:51:21+05:30",
      "requested_activation_date": null,
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "cancellation_scheduled_on": "2022-05-09",
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null,
      "reason": null,
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd_code": "91",
        "mobile": "9008580644"
      }
    }
    

    Request Parameters

    Name Mandatory Type Comments
    id Yes string Plan ID
    amount No decimal Installment Amount
    installment_day No integer See Details Here
    number_of_installments No integer See Details Here
    consent No hash Consent from investor for confirming the redemption
    Once set,this cannot be modified

    Fetch a redemption plan by its id

    GET /v2/mf_redemption_plans/:id

    This API can be used to fetch a redemption plan by its plan ID.

    curl -X GET "https://s.finprim.com/v2/mf_redemption_plans/mfrp_dbabb25ba34c48329dbfbeff70c846f0"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Response:

    {
      "object": "mf_redemption_plan",
      "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "created",
      "systematic": true,
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "installment_day": 1,
      "start_date": "2022-04-01",
      "end_date": "2022-11-01",
      "number_of_installments": 7,
      "auto_generate_installments": true,
      "next_installment_date": "2022-06-01",
      "previous_installment_date": "2022-05-01",
      "remaining_installments": 6,
      "amount": 1000.0,
      "source_ref_id": null,
      "euin": null,
      "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2022-04-01T17:51:21+05:30",
      "activated_at": "2022-04-01T17:51:21+05:30",
      "requested_activation_date": null,
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "cancellation_scheduled_on": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null,
      "reason": null,
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd_code": "91",
        "mobile": "9008580644"
      }
    }
    

    List all redemption plans

    GET /v2/mf_redemption_plans

    This API is used to fetch all redemption plans.

    curl -X GET "https://s.finprim.com/v2/mf_redemption_plans?mf_investment_account=mfia_798fa03aba614840b983609e89ed16f2&states=active"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Response:

    {
      "object": "list",
      "data": [
        {
          "object": "mf_redemption_plan",
          "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
          "state": "active",
          "systematic": true,
          "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
          "folio_number": "1234567890",
          "frequency": "monthly",
          "scheme": "INF204KA1B64",
          "installment_day": 1,
          "auto_generate_installments": true,
          "start_date": "2022-04-01",
          "end_date": "2022-11-01",
          "requested_activation_date": null,
          "number_of_installments": 7,
          "next_installment_date": "2022-06-01",
          "previous_installment_date": "2022-05-01",
          "remaining_installments": 6,
          "amount": 1000.0,
          "source_ref_id": null,
          "euin": null,
          "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
          "created_at": "2022-04-01T17:51:21+05:30",
          "activated_at": "2022-04-01T17:51:21+05:30",
          "cancelled_at": null,
          "completed_at": null,
          "failed_at": null,
          "cancellation_scheduled_on": null,
          "gateway": "rta",
          "user_ip": null,
          "server_ip": null,
          "initiated_by": null,
          "initiated_via": null,
          "consent": {
            "email": "mfp@cybrilla.com",
            "isd_code": "91",
            "mobile": "9008580644"
          }
        },
        {
          "object": "mf_redemption_plan",
          "id": "mfrp_1ba5b25b534c48329dbfbeff70c846f0",
          "state": "active",
          "systematic": true,
          "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
          "folio_number": "5234567890",
          "frequency": "monthly",
          "scheme": "INF204KA1B64",
          "transaction_day": 1,
          "auto_generate_installments": true,
          "start_date": "2022-04-01",
          "end_date": "2022-11-01",
          "requested_activation_date": null,
          "number_of_installments": 7,
          "next_installment_date": "2022-06-01",
          "previous_installment_date": "2022-05-01",
          "remaining_installments": 6,
          "amount": 1000.0,
          "source_ref_id": null,
          "euin": null,
          "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
          "created_at": "2022-04-01T17:51:21+05:30",
          "activated_at": "2022-04-01T17:51:21+05:30",
          "cancelled_at": null,
          "completed_at": null,
          "failed_at": null,
          "cancellation_scheduled_on": null,
          "gateway": "rta",
          "user_ip": null,
          "server_ip": null,
          "initiated_by": null,
          "initiated_via": null,
          "consent": {
            "email": "mfp@cybrilla.com",
            "isd_code": "91",
            "mobile": "9008580644"
          }
        }
      ]
    }
    

    Query Parameters

    Name Mandatory Type Comments
    mf_investment_account no string The investment account against which the redemption plans are created.
    states no string-array Multiple plan states separated by comma.

    Cancel a redemption plan

    POST /v2/mf_redemption_plans/:id/cancel

    This API can be used to cancel a plan using its plan ID. For more details, please see here

    curl -X POST "https://s.finprim.com/v2/mf_redemption_plans/mfrp_dbabb25ba34c48329dbfbeff70c846f0/cancel"
      -H "x-tenant-id: <tenant name>"
      -H "Authorization: Bearer ACCESS_TOKEN"
    

    JSON Response:

    {
      "object": "mf_redemption_plan",
      "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "cancelled",
      "systematic": true,
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "installment_day": 1,
      "start_date": "2022-04-01",
      "end_date": "2022-11-01",
      "number_of_installments": 7,
      "auto_generate_installments": true,
      "next_installment_date": "2022-06-01",
      "previous_installment_date": "2022-05-01",
      "remaining_installments": 6,
      "amount": 1000.0,
      "sou