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

• Tenant authentication: To access the FP APIs in the context of a tenant, this authentication type must be used. This will let you access resources across partners and investors. Please note that this authentication must be only used when you are accessing FP APIs from your server.
• Investor authentication: Instead of authenticating the investors by yourself, use FP's investor authentication service and get an investor specific access token. Once you get this token, you can access any FP API with that token and the API will be aware of this investor context and behave accordingly to ensure that investors can access only those resources which they are supposed to access.
• Partner authentication(Coming soon): If you rely on partners like sub-distributors to distribute mutual funds, instead of authenticating your partners by yourself, use FP's partner authentication service and get a partner-specific access token. Once you get this token, you can access any FP API with that token and the API will be aware of this partner context and behave accordingly to ensure that partners can access only those resources which they are supposed to access.

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	yes	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",
      "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",
      "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

• Status Check

Parameter	Mandatory	Default	Description
pan	yes	-	A valid PAN number to check the kyc status for

• Fetch KYC Data

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",
      "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",
      "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

Active nfe related to listed hash

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

Active nfe related to listed hash attributes

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

Related Party Object

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.

Related Party object attributes

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

Create a Related Party

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.

Modify a Related Party

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

Fetch a Related Party

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

List all Related Parties

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

• Does this bank account exists?
• Does this bank account belong to a particular person?

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

• Any order is always created against an investment account. So before creating an order ensure that you have a MF Investment Account.
• In case your investment account is mapped against an Investor Profile, make sure to set the folio_defaults for your investment account before you place any order.

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
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.
partner	no	string	See Details Here

¹Each 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.

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.

Purchase Consent Details

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

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.

To comply with the above -

While routing the order via RTA, either email or mobile or both can 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
** GET /v2/mf_redemptions/summary

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 (Upcoming): In this mode, the redemption orders for liquid funds which support instant redemption can be placed directly to AMC and the investor will receive the redemption proceeds in the bank account within 30 minutes.
redemption_bank_account_number	string	This value will be null if the redemption mode is normal.
redemption_bank_account_ifsc_code	string	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
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.
partner	no	string	See Details Here
redemption_mode	no	string	By default, the value will be normal. However, for liquid funds of AMCs for which FP supports instant redemption, you can provide instant for placing an instant redemption order

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

Consent Detail

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

• Use mf_folios to fetch details registered against the folio

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.

** Pre redemption summary ^Upcoming

Pre redemption summary object

{
  "object": "pre_redemption_summary",
  "mf_investment_account": "mfia_fe9348c57a4a04eaca50deb684cb502",
  "as_on": "2024-10-29T16:33:09.158+05:30",
  "schemes": [
    {
      "scheme": "INF209K01RU9",
      "folio": "15075102",
      "max_instant_redemption_amount": 50000
    }
  ]
}

Pre redemption summary object contains information that helps investor make an informed redemption decision.

Attribute	Type	Comments
object	string	Shall always be pre_redemption_summary
mf_investment_account	string	This is the ID of the investment account object, and you can identify the investment account associated with the pre redemption summary using this id
as_on	string	The time at which this redemption summary was created
schemes	array	List of folio+scheme hash which belong to the investor and contains pre-redemption summary details

schemes hash

Attribute	Type	Comments
scheme	string	ISIN of the scheme
folio	string	Folio number
max_instant_redemption_amount	numeric	Maximum permissible amount available for instant redemption today for the given investment account

List Pre redemption summary^Upcoming

** GET /v2/mf_redemptions/summary

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

Lists the pre redemption summary for the given investment account.

JSON Response:

{
  "object": "pre_redemption_summary",
  "mf_investment_account": "mfia_fe9348c57a4a04eaca50deb684cb502",
  "as_on": "2024-10-29T16:33:09.158+05:30",
  "schemes": [
    {
      "scheme": "INF209K01RU9",
      "folio": "15075102",
      "max_instant_redemption_amount": 50000
    }
  ]
}

Query Parameters

Name	Mandatory	Type	Comments
mf_investment_account	yes	string	The investment account against which the redemption must be made
folio	yes	string	The folio number against which the redemption must be made.
scheme	yes	string	ISIN of the scheme against which the redemption must be made

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
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.
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

Consent Detail

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

• Use mf_folios to fetch details registered against the folio

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
created	NA	Yes	Yes	No
active	No	NA	Yes	Yes
cancelled	No	No	NA	No
completed	No	No	No	NA

1. Transitioning from created to active

• Transition from created to active happens immediately and automatically.
• While creating a transaction plan, you can request FP to activate the transaction plan on a date in the future. In such cases, the plan will remain in the created state till that date in the future and will be marked as active afterward. In such cases, the plan will become active on the date on which activation was requested while creating the plan.

2. 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.

3. 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.

4. 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.

Object attributes of a transaction plan related to the plan states.

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 -

• How often a transaction must be generated (Ex: Monthly, Quarterly etc). This is known as the frequency of a transaction plan.
• On what specific day a transaction must be generated (Ex: 25th of every month) - This is known as installment_day of a transaction plan.
• From what point in time must the transactions start getting processed (Ex: 25th August 2024) - This is known as the requested_activation_date of a transaction plan. By default, no requested_activation_date is required and FP will automatically start the plan on an immediately possible date.
• How many times a plan must generate installments according to the frequency? - This is known as the number_of_installments of a transaction plan.

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	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.

• You can specify the number_of_installments while creating a plan to let us know how many installments must be generated by a plan according to the frequency of a plan.
• The number_of_installments must be greater than or equal to 1.

Object attributes of a transaction plan related to recurrence

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

• The installment will be accessible via FP APIs only on and after the day of installment, but not before that.
• For example, if you register a SIP(RTA gateway) on August 1, 2022, and installment_day = 15, and use FP APIs for payment collection, we ensure that the payment collection happens on August 15th, 2022 despite the fact that August 15th, 2022 is a market holiday. This means that day of the installment is August 15th, 2022, and this installment will be available from August 15th, 2022 via FP APIs and not before that.

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

• Minimum gap is the minimum number of days between transaction plan registration and first installment generation. Please note that minimum gap as a concept is applicable when FP manages installment generation
• If the mode is systematic and the order gateway is BSE and the plan is a purchase plan, the minimum gap is 7 bank working days. In other cases, the minimum gap is 1 calendar day*. Please see the examples below for a better understanding.

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	Normal	RTA	Monthly	15	August 15th, 2022	September 15th, 2022
Purchase plan	Normal	RTA	Monthly	16	August 15th, 2022	August 16th, 2022
Redemption/Switch plan	Any	RTA	Monthly	15	August 15th. 2022	September 15th, 2022
Redemption/Switch plan	Any	RTA	Monthly	16	August 15th, 2022	August 16th, 2022

Overcoming the minimum gap restrictions

• Irrespective of plan type, installment type, and order gateway, if you delegate the responsibility of installment generation to FP, the minimum gap is at least 1 calendar day. However, if you want to overcome this behavior and prepone the generation of the first installment, you can do so by specifying generate_first_installment_now = true while creating a transaction plan. The first installment will be generated immediately. You can fetch details of that installment in respective order type list all api by passing the plan id(purchase,redemption,switch).After the installment is fetched you can use Payment APIs to create a payment. Please note that even if the mandate is APPROVED during SIP creation, no payment will be created for the first installment if it is generated in case of where generate_first_installment_now is true.
• This option is currently available for purchase plans only.

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 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

• If you delegate the responsibility of installment generation to FP, you can also set up skip instructions against a plan to ask FP to skip specific installments.
• This facility is not available when auto_generate_installments=false.
• You create a skip instruction by specifying 3 things
  • ID of the plan against which skip instruction must be created.
  • The date from which the installments must be skipped
  • The date till which the installments must be skipped. However, the to date is optional.
• from date must be greater than the skip instruction creation date
• to date can be null only for non systematic plans. If it is not null, it must be greater than or equal to from date. If no to date is specified during plan creation, installments will be skipped till the plan is cancelled or completed for a non systematic plan.
• 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
• When you create a skip instruction, the skip instruction will be in pending state. On the day of from date, the skip instruction will be marked as active. From this day onwards, any installment having the day of installment greater than or equal to from date will be generated and automatically marked as cancelled till to date of skip instruction.
• If a plan is cancelled or completed, any pending or active skip instruction is also marked as cancelled automatically.
• Once the day is past to date, the skip instruction is marked as completed.
• You can also cancel a skip instruction if it is in a pending or active state. In such cases, a skip instruction will be marked as cancelled.
• Once you cancel a skip instruction, only those installments that are not yet generated will not be marked as cancelled because of this particular cancelled skip instruction. Already cancelled installments will remain cancelled.
• You can create multiple skip instructions for the same plan. Each skip instruction is independent of the other. However, if there are multiple skip instructions against the plan for the same installment, the installment will be skipped by the first active skip instruction. The other skip instruction will not have any impact on the installment because the installment is already skipped because of the first skip instruction.

• Note

  1. This feature is currently available for RTA (systematic as well as non-systematic plans) .
  2. Currently skip instructions are supported for plans with the following frequencies - monthly, quarterly, half_yearly and yearly.
  3. If we need to activate a skip instruction from day T, we should place the skip instruction order at least 2 calendar days before day T. E.g. if we need to activate a skip instruction from 15 January 2022, we should place the skip instruction at least by 13 January 2022.
  4. If you skip installments beyond a certain threshold, the RTAs might cancel the systematic plan registration at their end. For example, if you skip 3 or more SIP installments, RTA might cancel the registration depending on the scheme and frequency. Please note that FP doesn't block creation of skip instructions if you are trying to skip installments beyond allowed threshold set by RTAs.

• Note on 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. 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

• You can change number_of_installments only when a plan is in active state.

Changing the installment day of a non-systematic plan

• This is not applicable for plans with frequency as daily because installments are generated on a daily basis and installment_day is not taken as an input during plan creation.
• If you wish to update the installment_day from T day, then update the installment_day at least 2 calendar days before T day.

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

• You can cancel a plan when a plan is in either created state or active state.
• Cancellation gap: The cancellation gap is an indicator using which you can figure out how soon you must cancel a plan to avoid generating and processing the next installment that is yet to be generated. Please note that this concept is applicable when FP is managing installment generation on its own. The cancellation gap is 0 days i.e. cancellation happens immediately.

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 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.
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
reason	string	Yes	See details 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	No	string	The payment method that must be used for collecting payments against the installments.Possible value:mandate. Mandatory if payment_source is not null.
payment_source	No	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.
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
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.

Purchase Plan Consent Details

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

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.

To comply with the above -

While registering for a SIP via RTA, either email or mobile or both can 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

• A plan can be updated only if plan gateway = rta.
• To update a plan right from the next installment, the plan must be modified at least 2 calendar days before the next installment is scheduled.
• To learn about common condtions and how to update a transaction plan read modifying plans.

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.

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,
      "reason": 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,
      "reason": 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/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 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.
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

Consent Detail

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	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
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

• A plan can be updated only if plan gateway = rta.
• To update a plan right from the next installment, the plan must be modified at least 2 calendar days before the next installment is scheduled.
• To learn about common condtions and how to update a transaction plan read modifying plans.

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,
      "reason": 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,
      "reason": 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,
  "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": "2022-05-08T17:51:21+05:30",
  "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"
  }
}

MF Switch Plans

MF Switch plan represents a plan defined to create switch orders on a recurring basis.

Endpoints

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

Switch Plan Object Structure

{
  "object": "mf_switch_plan",
  "id": "mfsp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "created",
  "systematic": true,
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "switch_in_scheme": "INF204KA1B64",
  "switch_out_scheme": "INF205KA1B65",
  "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_switch_plan
id	string	No	Unique identifier of the mf_switch_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 switch plan using this id
folio_number	string	Yes	Indicates the folio from which the switches must be made.
switch_out_scheme	string	No	ISIN of the scheme from which units must be switched out.
switch_in_scheme	string	No	ISIN of the scheme to which units must be switched to.
amount	decimal	No	Periodic switch amount.
systematic	boolean	No	The value of this attribute indicates the way this switch plan is registered with order gateways. - If the value is true, it means that the plan is registered as a Systematic Transfer Plan with RTA and every installment is considered as a traditional STP installment. - If the value is false, FP will create a switch order according to the defined schedule and send it to order gateway. Since each installment of this plan is a switch order and not a traditional STP installment, consent for each installment is required before the order is sent to the order 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	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 switch

Consent Detail

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

Create a switch plan

POST /v2/mf_switch_plans

curl -X POST "https://s.finprim.com/v2/mf_switch_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,
  "switch_in_scheme": "INF204KA1B64",
  "switch_out_scheme": "INF205KA1B65",
  "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_switch_plan",
  "id": "mfsp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "created",
  "systematic": true,
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "switch_in_scheme": "INF204KA1B64",
  "switch_out_scheme": "INF205KA1B65",
  "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.
switch_out_scheme	Yes	string	The isin of the scheme from which switches must be made.
switch_in_scheme	Yes	string	The isin of the scheme to which switches must be made.
frequency	Yes	string	See details here
folio_number	Yes	string	Folio from which the switches must be made
amount	Yes	decimal	The installment amount. 1) If systematic = true, amount should be in multiples of stp_multiples and between min_stp_amount and max_stp_amount 2) If systematic = false and folio number is not provided,the amount should be between min_stp_amount and max_stp_amount and should be a multiple of stp_multiples 3) If systematic = false, the amount should be between min_switch_out_amount and max_switch_out_amount and should be a multiple of switch_out_amount_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	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
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 switch plan

PATCH /v2/mf_switch_plans

Note

• A plan can be updated only if plan gateway = rta.
• To update a plan right from the next installment, the plan must be modified at least 2 calendar days before the next installment is scheduled.
• To learn about common condtions and how to update a transaction plan read modifying plans.

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

JSON Request:

{
  "id": "mfsp_dbabb25ba34c48329dbfbeff70c846f0",
  "amount": "2050"
}

JSON Response:

{
  "object": "mf_switch_plan",
  "id": "mfsp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "systematic": true,
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "switch_in_scheme": "INF204KA1B64",
  "switch_out_scheme": "INF205KA1B65",
  "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 switch plan by its id

GET /v2/mf_switch_plans/:id

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

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

JSON Response:

{
  "object": "mf_switch_plan",
  "id": "mfsp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "created",
  "systematic": true,
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "switch_in_scheme": "INF204KA1B64",
  "switch_out_scheme": "INF205KA1B65",
  "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 switch plans

GET /v2/mf_switch_plans

This API is used to fetch all switch plans.

curl -X GET "https://s.finprim.com/v2/mf_switch_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_switch_plan",
      "id": "mfsp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "active",
      "systematic": true,
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "frequency": "monthly",
      "switch_in_scheme": "INF204KA1B64",
      "switch_out_scheme": "INF205KA1B65",
      "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,
      "reason": null,
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd_code": "91",
        "mobile": "9008580644"
      }
    },
    {
      "object": "mf_switch_plan",
      "id": "mfsp_1ba5b25b534c48329dbfbeff70c846f0",
      "state": "active",
      "systematic": true,
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "5234567890",
      "frequency": "monthly",
      "switch_in_scheme": "INF204KA1B64",
      "switch_out_scheme": "INF208KA1B68",
      "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,
      "reason": 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 switch plans are created.
states	no	string-array	Multiple plan states separated by comma.

Cancel a switch plan

POST /v2/mf_switch_plans/:id/cancel

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

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

JSON Response:

{
  "object": "mf_switch_plan",
  "id": "mfsp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "cancelled",
  "systematic": true,
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "switch_in_scheme": "INF204KA1B64",
  "switch_out_scheme": "INF205KA1B65",
  "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": "2022-05-08T17:51:21+05:30",
  "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"
  }
}

MF Settlement Details

MF Settlement object capture the details of money transfer from investor's bank account to the AMC's bank account. If you are using FP's payment APIs for payment collection, settlement details are auto captured by FP. However, if you are managing payment collection from your investors by yourselves, you will have to report the settlement details to us so that we can report this information to RTAs and AMCs for compliance and reconcilliation purposes.

Managing payment collection on your own :

a) Create a purchase order.
b) Accept payment from the investor and initiate the transfer of money to AMC's bank account.
c) Capture the transfer initiation details using Create mf settlement details API. Please note that, at this stage, you don't have to share the UTR number and settlement time.
d) Mark the order as confirmed. Without transfer initiation details, purchase orders cannot be marked as confirmed.
e) When the settlement to the AMC's bank account is complete, provide the UTR number and settlement time using Update mf settlement detail API

Endpoints:

POST /v2/mf_settlement_details
GET /v2/mf_settlement_details/:id
GET /v2/mf_settlement_details
PATCH /v2/mf_settlement_details

MF Settlement Detail Object

{
  "object": "mf_settlement_detail",
  "id": "mfsd_3c496b27ece044418e7eda9e101875e1",
  "mf_purchase": "mfp_621f8a91658b41c3b1f41f005dc393b6",
  "utr_number": "UTB123312",
  "bank_account_number": "999900002222",
  "bank_ifsc": "UTIB0003098",
  "bank_name": "AXIS BANK",
  "bank_account_type": "SAVINGS",
  "payment_type": "netbanking",
  "beneficiary_account_number": "1233453",
  "beneficiary_account_title": "PMF MF Collection A/c",
  "beneficiary_bank_name": "Amc Bank Name",
  "settlement_processed_at": "2022-03-17T06:30:09"
}

Attribute	Type	Comments
object	string	Value is mf_settlement_detail. String representing the object type. Objects of the same type share the same value
mf_purchase	string	The id of the purchase order for which these settlement details have been provided
utr_number	string	Unique transaction reference number that can be used to identify the payment that was made to the AMC's bank account against the order
bank_account_number	string	Bank account number of the source bank account from which the investor has made the payment
bank_ifsc	string	IFSC of the branch in which the source bank account,the bank account from which the payment was made, is located
bank_name	string	Name of the bank in which the investor has his source bank account
bank_account_type	string	Source bank account type
payment_type	string	Mode of payment used by the investor to make the payment. Possible values: netbanking, nach, neft, rtgs
beneficiary_account_number	string	AMC's bank account number to which the transfer was made
beneficiary_account_title	string	AMC's bank account name
beneficiary_bank_name	string	Name of the bank in which the AMC has its beneficiary bank account, the bank account to which you have transferred the investor's money.
settlement_processed_at	string	Time at which the settlement is processed

Create a MF Settlement Detail

POST /v2/mf_settlement_details

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

JSON Request:

{
  "mf_purchase": "mfp_621f8a91658b41c3b1f41f005dc393b6",
  "payment_type": "netbanking",
  "utr_number": "UTB123312",
  "bank_account_number": "999900002222",
  "bank_ifsc": "UTIB0003098",
  "beneficiary_account_number": "1233453",
  "beneficiary_account_title": "PMF MF Collection A/c",
  "beneficiary_bank_name": "Amc Bank Name",
  "settlement_processed_at": "2022-03-17T06:30:09+05:30"
}

JSON Response:

{
  "object": "mf_settlement_detail",
  "id": "mfsd_3c496b27ece044418e7eda9e101875e1",
  "mf_purchase": "mfp_621f8a91658b41c3b1f41f005dc393b6",
  "utr_number": "UTB123312",
  "bank_account_number": "999900002222",
  "bank_ifsc": "UTIB0003098",
  "bank_name": "AXIS BANK",
  "bank_account_type": "SAVINGS",
  "payment_type": "netbanking",
  "beneficiary_account_number": "1233453",
  "beneficiary_account_title": "PMF MF Collection A/c",
  "beneficiary_bank_name": "Amc Bank Name",
  "settlement_processed_at": "2022-03-17T06:30:09"
}

Request Parameters

Name	Mandatory	Type	Comments
mf_purchase	yes	string	Provide the id of the purchase for which this settlement was made
payment_type	yes	string	Provide the payment mode using which the investor made the payment. Possible values: netbanking, nach, neft, rtgs
utr_number	no	string	Provide the unique transaction reference of the transfer made to the AMC
bank_account_number	yes	string	Provide the account number of the investor's bank account from which the payment originated
bank_ifsc	yes	string	Provide the ifsc of the investor's bank account from which the payment originated
beneficiary_account_number	yes	string	Provide the AMC's bank account number to which the transfer was made
beneficiary_account_title	yes	string	Provide the bank account name of the AMC's bank account to which the transfer was made
beneficiary_bank_name	yes	string	Provide the bank name of the AMC's bank account to which the transfer was made
settlement_processed_at	no	string	Provide the settlement timestamp in ISO Local Date Time yyyy-MM-ddThh:mm:ss format

Update a MF Settlement Detail

PATCH /v2/mf_settlement_details

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

JSON Request:

{
  "id": "mfsd_3c496b27ece044418e7eda9e101875e1",
  "utr_number": "UTB123312",
  "settlement_processed_at": "2022-03-17T06:30:09"
}

JSON Response:

{
  "object": "mf_settlement_detail",
  "id": "mfsd_3c496b27ece044418e7eda9e101875e1",
  "mf_purchase": "mfp_621f8a91658b41c3b1f41f005dc393b6",
  "utr_number": "UTB123312",
  "bank_account_number": "999900002222",
  "bank_ifsc": "UTIB0003098",
  "bank_name": "AXIS BANK",
  "bank_account_type": "SAVINGS",
  "payment_type": "netbanking",
  "beneficiary_account_number": "1233453",
  "beneficiary_account_title": "PMF MF Collection A/c",
  "beneficiary_bank_name": "Amc Bank Name",
  "settlement_processed_at": "2022-03-17T06:30:09"
}

Request Parameters

Name	Mandatory	Type	Comments
id	yes	string	id of the settlement detail
utr_number	yes	string	Provide the unique transaction reference of the transfer made to the AMC
settlement_processed_at	yes	string	Provide the settlement timestamp in ISO Local Date Time yyyy-MM-ddThh:mm:ss format

Fetch a MF Settlement Detail

GET /v2/mf_settlement_details/:id

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

This API is used to fetch a given settlement detail by its identifier

Query Parameters

Name	Mandatory	Type	Comments
id	yes	string	id of the settlement detail.

JSON Response:

{
  "object": "mf_settlement_detail",
  "id": "mfsd_3c496b27ece044418e7eda9e101875e1",
  "mf_purchase": "mfp_621f8a91658b41c3b1f41f005dc393b6",
  "utr_number": "UTB123312",
  "bank_account_number": "999900002222",
  "bank_ifsc": "UTIB0003098",
  "bank_name": "AXIS BANK",
  "bank_account_type": "SAVINGS",
  "payment_type": "netbanking",
  "beneficiary_account_number": "1233453",
  "beneficiary_account_title": "PMF MF Collection A/c",
  "beneficiary_bank_name": "Amc Bank Name",
  "settlement_processed_at": "2022-03-17T06:30:09"
}

Search MF Settlement Details

GET /v2/mf_settlement_details

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

This API can be used to fetch a settlement detail for a given purchase order.

Query Parameters

Name	Mandatory	Type	Comments
mf_purchase	yes	string	V2 id of the purchase order.

JSON Response:

{
  "object": "mf_settlement_detail",
  "id": "mfsd_3c496b27ece044418e7eda9e101875e1",
  "mf_purchase": "mfp_621f8a91658b41c3b1f41f005dc393b6",
  "utr_number": "UTB123312",
  "bank_account_number": "999900002222",
  "bank_ifsc": "UTIB0003098",
  "bank_name": "AXIS BANK",
  "bank_account_type": "SAVINGS",
  "payment_type": "netbanking",
  "beneficiary_account_number": "1233453",
  "beneficiary_account_title": "PMF MF Collection A/c",
  "beneficiary_bank_name": "Amc Bank Name",
  "settlement_processed_at": "2022-03-17T06:30:09"
}

Introduction to Non-Commercial Transactions

Here, we talk about initiating and working with various types of non-commercial transactions, also known as NCTs.

Non-Commercial Transactions Overview

Currently, FP supports below NCTs -
1. Phone Number NCT

Notes:

• FP currently supports NCTs only on the folios that are present on its system. To check if a folio exists on FP or not, use Fetch All Folios
• FP has defined one object non_commercial_transaction which can initiate a request for all the types of NCTs that are available
• Based on the type of NCT, the behaviour of Create Non-Commercial Transaction and Update Non-Commercial Transaction APIs would change
• However, for any type of NCT, Fetch Non-Commercial Transaction API and List all Non-Commercial Transactions API would remain the same

Non-Commercial Transaction Object

{
  "object": "non_commercial_transaction",
  "id": "nct_db503f08ed1abbed2b9811ef7accc7bb",
  "type": "update_phone_number",
  "status": "successful",
  "failure_code": null,
  "mf_investment_account": "mfia_904b5ba315514981bfbe4fb680ba8730",
  "folios": [
    "1045078424"
  ],
  "data": {
    "phone_number": "9028173912",
    "belongs_to": "self"
  },
  "source_ref_id": "20",
  "consent_required_at": "2023-11-30T13:25:28.409+05:30",
  "second_consent_required_at": "2023-11-30T13:27:28.409+05:30",
  "submitted_at": "2023-11-30T13:29:28.409+05:30",
  "expired_at": null,
  "successful_at": "2023-11-30T13:31:28.409+05:30",
  "failed_at": null,
  "created_at": "2023-11-30T13:25:27.441+05:30",
  "updated_at": "2023-11-30T13:27:28.409+05:30"
}

Name	Type	Comments
object	string	Value is non_commercial_transaction. String representing the object type. Objects of the same type share the same value
id	string	Unique identifier of the non_commercial_transaction object
type	string	Indicates the type of of NCT. Possible values are - update_phone_number
status	string	Indicates the status of the non_commercial_transaction object. Possible values are - consent_required, second_consent_required, submitted, successful, failed and expired
failure_code	string	Indicates the reason behind failure or expiry of NCT request. Possible values and descriptions are as given below - failure_at_gateway - The request could not be processed at the gateway first_otp_incorrect - The OTP given when non_commercial_transaction.status = consent_required was incorrect and hence the NCT request failed second_otp_incorrect - The OTP given when non_commercial_transaction.status = second_consent_required was incorrect and hence the NCT request failed first_otp_expired - The non_commercial_transaction was expecting the first consent to be provided but the OTP validity elapsed and the transaction cannot be further processed second_otp_expired - The non_commercial_transaction was expecting the second consent to be provided but the OTP validity elapsed and the transaction cannot be further processed phone_number_relationship_mismatch - These would be the cases where an NCT request would be submitted to the gateway with belongs_to = self but was rejected by the gateway due to the reason that the given phone number was mapped as self to another PAN in the RTA databases
mf_investment_account	string	MF Investment Account ID
folios	array	List of folios on which NCT has to be initiated
data	hash	This is a dynamic hash that stores the specific details of the NCT. These details vary based on the non_commercial_transaction.type
source_ref_id	string	An identifier that is unique across all types of NCTs. This is not generated by FP and is populated by API consumers for identification purposes (ideally an auto generated identifier / uuid to identify the NCT in your application)
consent_required_at	string	The timestamp at which NCT object was created and is awaiting a consent from the investor
second_consent_required_at	string	The timestamp at which NCT object is expecting a second consent from the investor to proceed ahead
submitted_at	string	The timestamp at which the NCT request was submitted to the gateway for further processing
successful_at	string	The timestamp at which the NCT request was successfully completed at the gateway
failed_at	string	The timestamp at which the NCT request was rejected by the gateway
expired_at	string	The timestamp at which the NCT request was expired
created_at	string	The timestamp at which the non_commercial_transaction object was created at
updated_at	string	The timestamp at which the non_commercial_transaction object was last updated at

Fetch Non-Commercial Transaction

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

JSON response:

{
  "object": "non_commercial_transaction",
  "id": "nct_db503f08ed1abbed2b9811ef7accc7bb",
  "type": "update_phone_number",
  "status": "successful",
  "failure_code": null,
  "mf_investment_account": "mfia_904b5ba315514981bfbe4fb680ba8730",
  "folios": [
    "1045078424"
  ],
  "data": {
    "phone_number": "9028173912",
    "belongs_to": "self"
  },
  "source_ref_id": "20",
  "consent_required_at": "2023-11-30T13:25:28.409+05:30",
  "second_consent_required_at": "2023-11-30T13:27:28.409+05:30",
  "submitted_at": "2023-11-30T13:29:28.409+05:30",
  "expired_at": null,
  "successful_at": "2023-11-30T13:31:28.409+05:30",
  "failed_at": null,
  "created_at": "2023-11-30T13:25:27.441+05:30",
  "updated_at": "2023-11-30T13:27:28.409+05:30"
}

The endpoint is used to fetch the details of an NCT request.

HTTP Request

GET /v2/non_commercial_transactions/:id

Query Parameters

Name	Mandatory	Type	Comments
id	yes	string	ID of the non_commercial_transaction object

List all Non-Commercial Transactions

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

JSON response:

{
  "object": "list",
  "data": [
    {
      "object": "non_commercial_transaction",
      "id": "nct_db503f08ed1abbed2b9811ef7accc7bb",
      "type": "update_phone_number",
      "status": "successful",
      "failure_code": null,
      "mf_investment_account": "mfia_904b5ba315514981bfbe4fb680ba8730",
      "folios": [
        "1045078424"
      ],
      "data": {
        "phone_number": "9028173912",
        "belongs_to": "self"
      },
      "source_ref_id": "20",
      "consent_required_at": "2023-11-30T13:25:28.409+05:30",
      "second_consent_required_at": "2023-11-30T13:27:28.409+05:30",
      "submitted_at": "2023-11-30T13:29:28.409+05:30",
      "expired_at": null,
      "successful_at": "2023-11-30T13:31:28.409+05:30",
      "failed_at": null,
      "created_at": "2023-11-30T13:25:27.441+05:30",
      "updated_at": "2023-11-30T13:27:28.409+05:30"
    }
  ]
}

The endpoint is used to fetch the details of an NCT request.

HTTP Request

GET /v2/non_commercial_transactions

Query Parameters

Name	Mandatory	Type	Comments
mf_investment_account	yes	string	MF Investment Account ID
type	no	string	Comma separated NCT types. Allowed values - update_phone_number. If this is given, then you will only be able to see the NCTs belonging to these types for the given mf_investment_account

Phone Number NCT ^{(Early Access)}

These APIs can be used to update the phone number on a particular folio or a set of folios.

Endpoints:

POST /v2/non_commercial_transactions
PATCH /v2/non_commercial_transactions
GET /v2/non_commercial_transactions/:id

Basic workflow to perform Phone Number NCT

1. List down all the relevant folios where NCT has to be initiated
2. Create an update_phone_number NCT by giving the MF Investment Account ID, folio number, the phone number that has to be updated in that folio and the relationship of the phone number with the investor. The status would be consent_required at this stage
3. Use Update Phone Number NCT API to provide the OTP that the investor received on the existing phone number mapped to the folio. Now the status would be changed to second_consent_required provided the OTP provided was successfully validated
4. Use Update Phone Number NCT API again to provide the second OTP that the investor received on the new phone number that has to be updated on the folio. Now the status would be changed to submitted provided the second OTP was also successfully validated
5. In case either first OTP or second OTP was not provided within the valid time range, the status of such NCT requests would be marked as expired with failure_code as either first_otp_expired or second_otp_expired depending on the scenario
6. Now the Phone Number NCT request would be submitted to the gateway. Use Fetch Non-Commercial Transaction API using the non_commercial_transaction ID to get the updated status of the NCT
7. If the gateway successfully processed the NCT request, the status would be changed to successful
8. If the gateway rejected the NCT request, the status would be changed to failed and a relevant failure reason would be mentioned in the failure_code attribute

Create Phone Number NCT

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

JSON request:

{
  "mf_investment_account": "mfia_904b5ba315514981bfbe4fb680ba8730",
  "folios": [
    "1045078424"
  ],
  "type": "update_phone_number",
  "data": {
    "phone_number": "9028173912",
    "belongs_to:": "self"
  },
  "source_ref_id": "20"
}

JSON response:

{
  "object": "non_commercial_transaction",
  "id": "nct_db503f08ed1abbed2b9811ef7accc7bb",
  "type": "update_phone_number",
  "status": "consent_required",
  "failure_code": null,
  "mf_investment_account": "mfia_904b5ba315514981bfbe4fb680ba8730",
  "folios": [
    "1045078424"
  ],
  "data": {
    "phone_number": "9028173912",
    "belongs_to": "self"
  },
  "source_ref_id": "20",
  "consent_required_at": "2023-11-30T13:25:28.409+05:30",
  "second_consent_required_at": null,
  "submitted_at": null,
  "expired_at": null,
  "successful_at": null,
  "failed_at": null,
  "created_at": "2023-11-30T13:25:27.441+05:30",
  "updated_at": "2023-11-30T13:25:28.788+05:30"
}

The endpoint is used to create a Phone Number NCT request.

HTTP Request

POST /v2/non_commercial_transactions

Request Parameters

Name	Mandatory	Type	Comments
mf_investment_account	yes	string	MF Investment Account ID
folios	yes	array	List of folios on which NCT has to be initiated on
type	yes	string	Type of NCT. To pass - update_phone_number
data	yes	hash	Data needed to initiate an update_phone_number NCT
source_ref_id	no	string	An identifier that is unique across all types of NCTs. This is not generated by FP and is populated by API consumers for identification purposes (ideally an auto generated identifier / uuid to identify the NCT in your application)

data hash for Update Phone Number NCT

Name	Mandatory	Type	Comments
phone_number	yes	string	Actual phone number that has to be updated on the listed folios
belongs_to	yes	string	Relationship of the phone number with the investor. Allowed values are - self

NOTE: Currently the NCT request can accept only one folio number at any point in time.

Update Phone Number NCT

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

JSON request:

{
  "id": "nct_db503f08ed1abbed2b9811ef7accc7bb",
  "otp": "001234"
}

JSON response:

{
  "object": "non_commercial_transaction",
  "id": "nct_db503f08ed1abbed2b9811ef7accc7bb",
  "type": "update_phone_number",
  "status": "second_consent_required",
  "failure_code": null,
  "mf_investment_account": "mfia_904b5ba315514981bfbe4fb680ba8730",
  "folios": [
    "1045078424"
  ],
  "data": {
    "phone_number": "9028173912",
    "belongs_to": "self"
  },
  "source_ref_id": "20",
  "consent_required_at": "2023-11-30T13:25:28.409+05:30",
  "second_consent_required_at": "2023-11-30T13:27:28.409+05:30",
  "submitted_at": null,
  "expired_at": null,
  "successful_at": null,
  "failed_at": null,
  "created_at": "2023-11-30T13:25:27.441+05:30",
  "updated_at": "2023-11-30T13:27:28.409+05:30"
}

The endpoint is used to collect the consent for a Phone Number NCT request.

HTTP Request

PATCH /v2/non_commercial_transactions

Request Parameters

Name	Mandatory	Type	Comments
id	yes	string	ID of the non_commercial_transaction
otp	yes	string	OTP as received on the phone number If non_commercial_transaction.status = consent_required then the OTP would be sent to the existing phone number on the folio If non_commercial_transaction.status = second_consent_required then the OTP would be sent to the new phone number that would get updated on the folio

Mandates

Represents an authorization given by the investor to automatically debit payment from his bank account for onetime and recurring purchase orders.

Endpoints:

POST /api/pg/mandates
POST /api/pg/payments/emandate/auth
GET /api/pg/mandates/:id
GET /api/pg/mandates
POST /api/pg/mandates/:id/cancel

Mandate object

Attribute	Type	Comments
id	Integer	FP unique identifier of mandate
bank_account_id	Integer	Investor bank account old_id created using Bank account creation API for which the mandate is created against.
mandate_ref	String	Customer reference passed to Payment provider.
mandate_token	String	Mandate reference ID in the payment provider system
valid_from	String	Mandate Valid from date
valid_to	String	Mandate Valid to date. Mandate can be created for a max validity of 30 years.
mandate_limit	Integer	Amount that can be debited from the mandate. Refer here for more details.
mandate_type	String	This value represents if the mandate is NACH or UPI Autopay
mandate_status	String	For more details, refer here.
umrn		Unique mandate reference number provided by NPCI/Bank
created_at	string	Refer here
received_at	string	Refer here
submitted_at	string	Refer here
approved_at	string	Refer here
rejected_at	string	Refer here
cancelled_at	string	Refer here
rejected_reason	String	Mandate rejection reason.
provider_name	String	Payment provider through which the mandate is created. Possible values: BILLDESK and RAZORPAY.

Create a mandate (eNACH & UPI Autopay)

curl -X POST "https://s.finprim.com/api/pg/mandates"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '
    {
  "mandate_type": "E_MANDATE",
  "bank_account_id": 1,
  "mandate_limit": 100000
}
  '

JSON Response:

{
  "id": 1
}

POST /api/pg/mandates

This endpoint is used to create eNACH and UPI Autopay mandates. The API returns mandate ID in response.

Parameters

Parameter	Mandatory	Type	Description
mandate_type	yes	String	Possible values: E_MANDATE (or) UPI E_MANDATE for NACH mandate and UPI for UPI Autopay.
bank_account_id	yes	Long	FP bank account old_id generated using Create Bank Account API
mandate_limit	yes	Integer	mandate limit For E_MANDATE, the maximum limit is ₹1 Cr. For UPI, the limits are ₹1 Lakh max and ₹10 min for Razorpay, and ₹1 min for Billdesk. Razorpay's limits are per transaction, while Billdesk's are per day.
provider_name	no	String	RAZORPAY (or) BILLDESK
valid_from	no	String	valid_from in yyyy-mm-dd format. For BILLDESK as payment provider, default value is date of mandate authorisation. If valid_from date passed is lesser than authorisation date, then it will be changed to authorisation date. For Razorpay as payment provider, valid_from parameter is not used; the mandate creation date is always automatically applied.
valid_to	no	String	valid_to in yyyy-mm-dd format. Default value is (valid_from date + 30 years) and must be lower than (valid_from date + 30 years).

Note

• UPI Autopay is an on-demand feature. To enable this functionality, kindly reach out to our support team.

Authorize a mandate (eNACH and UPI Autopay)

curl "https://s.finprim.com/api/pg/payments/emandate/auth"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '
    {
  "mandate_id": 1,
  "payment_postback_url": "https://example.com/"
}
  '

JSON Response:

{
  "token_url": "https://tenant.s.finprim.com/api/pg/payments/netbanking/razorpay?txnId=bdbd1396-3197-460b-afd3-adc3f6e09123&txnType=1",
  "id": 1
}

POST /api/pg/payments/emandate/auth

This endpoint is used for authorizing the eNACH and UPI Autopay mandates. Once the authorization is done from the bank side, subsequent payments need not be authorized again and will be made automatically. The response contains payment provider URL along with payment ID.

Parameters

Parameter	Mandatory	Type	Description
mandate_id	yes	Integer	ID of created e-mandate
payment_postback_url	no	String	Application url where the investor will be redirected back after emandate auth transaction (https://example.com/payment_confirmation).]

Multiple authorisations can be created against a mandate as long as mandate is in created state. After e-mandate is authorized at the payment gateway, a post request using HTTP POST will be made via web browser to the preconfigured URL provided by tenant

HTTP Form POST Parameters

Parameter	Type	Description
paymentId	String	ID of the generated payment
status	String	payment status either success or failure
failureReason	String	payment failure reason, empty if payment is successful

You can use this data for displaying the authorization status to the investor and if required retry.

Fetch a mandate

curl "https://s.finprim.com/api/pg/mandates/1"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response:

{
  "id": 1,
  "bank_account_id": 1,
  "mandate_ref": null,
  "mandate_token": "token_WxyDNskmds",
  "valid_from": "2017-10-23",
  "mandate_limit": 50000,
  "mandate_type": "NACH",
  "mandate_status": "SUBMITTED",
  "umrn": null,
  "created_at": "2017-10-23T04:49:21+05:30",
  "received_at": null,
  "submitted_at": "2017-10-23T04:30:21+05:30",
  "cancelled_at": null,
  "approved_at": null,
  "rejected_at": null,
  "rejected_reason": null,
  "provider_id": 1,
  "provider_name": "RAZORPAY"
}

GET /api/pg/mandates/:id

This endpoint retrieves mandate info based on the mandate ID

Note

• For Razorpay, mandate token will be available only after mandate is APPROVED
• Mandates approved before 2020-09-30 will not have value in mandate_token

List all mandates

curl "https://s.finprim.com/api/pg/mandates?bank_account_id=18,12"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response:

{
  "last": true,
  "total_pages": 1,
  "total_elements": 2,
  "size": 20,
  "number": 0,
  "first": true,
  "number_of_elements": 2,
  "mandates": [
    {
      "id": 2,
      "bank_account_id": 1,
      "mandate_ref": "391335121",
      "mandate_token": "token_WxyDNskmds",
      "valid_from": "2017-10-23",
      "mandate_limit": 50000,
      "mandate_type": "NACH",
      "mandate_status": "CREATED",
      "umrn": "1592",
      "created_at": "2017-10-23T04:51:27+05:30",
      "received_at": null,
      "submitted_at": null,
      "approved_at": null,
      "cancelled_at": null,
      "rejected_at": null,
      "rejected_reason": null,
      "provider_id": 1,
      "provider_name": "RAZORPAY"
    },
    {
      "id": 3,
      "bank_account_id": 1,
      "mandate_ref": "391115121",
      "mandate_token": "token_YnhDsFgos",
      "valid_from": "2017-11-24",
      "mandate_limit": 50000,
      "mandate_type": "NACH",
      "mandate_status": "CREATED",
      "umrn": "1512",
      "created_at": "2017-11-24T04:51:27+05:30",
      "received_at": null,
      "submitted_at": null,
      "approved_at": null,
      "cancelled_at": null,
      "rejected_at": null,
      "rejected_reason": null,
      "provider_id": 1,
      "provider_name": "RAZORPAY"
    }
  ]
}

GET /api/pg/mandates

This endpoint retrieves mandate info based on given filters.

Query Parameters

Parameter	Mandatory	Default	Description
bank_account_id	no	-	List of bank account ids
page	no	0	page number of the result set
size	no	20	number of results per page, size should not be greater than 100

Cancel a mandate

curl "https://s.finprim.com/api/pg/mandates/1/cancel"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response:

{
  "id": 1,
  "bank_account_id": 1,
  "mandate_ref": null,
  "mandate_token": "token_WxyDNskmds",
  "valid_from": "2017-10-23",
  "mandate_limit": 50000,
  "mandate_type": "E_MANDATE",
  "mandate_status": "CANCELLED",
  "umrn": null,
  "created_at": "2017-10-23T04:49:21+05:30",
  "received_at": null,
  "submitted_at": "2017-10-23T04:30:21+05:30",
  "cancelled_at": "2022-10-23T04:30:21+05:30",
  "approved_at": null,
  "rejected_at": null,
  "rejected_reason": null,
  "provider_id": 1,
  "provider_name": "RAZORPAY"
}

POST /api/pg/mandates/:id/cancel

This API can be used to cancel an APPROVED mandate. Once CANCELLED, this mandate cannot be used for making any payments. Also, you cannot authorize a cancelled mandate again. If there are any existing SIPs using this mandate, after the cancellation, the payments will be marked as FAILED.

Query Parameters

Parameter	Mandatory	Description
id	yes	ID of the mandate to be cancelled

Payments

Represents a payment transaction. The API allows you to create a payment and fetch the payment details.

Endpoints:

POST /api/pg/payments/netbanking
POST /api/pg/payments/nach
GET /api/pg/payments/:id
GET /api/pg/payments

Payment Object

Attribute	Type	Comments
id	Integer	FP unique identifier of payment
from_bank_account_id	integer	Investor bank account old_id created using Bank account creation API for which the mandate is created against.
payment_type	string	Identifies if the payment is through Netbanking/UPI or through Mandate. Possible values: NETBANKING, NACH, AUTH_TRANSACTION
status	String	For Netbanking/UPI payment statuses, refer here. For eNACH/UPI Autopay payment statuses, refer here
amount	decimal	Amount collected from the Investor through the payment. Summation of the AMC order value.
method	String	Possible values: NETBANKING, UPI, EMANDATE
debit_date		Possible date of debit from the Investor
amc_order_ids	Array	Array of AMC orders for which the payment is collected.
failure_code	String	Failure code of the failed payment. For detailed failure codes, Refer here
failed_reason		Failure reason description of the failed payment. For detailed failure codes, Refer here
created_at	string	Refer here
submitted_at	string	Refer here
debit_confirmed_at	string	Refer here
failed_at	string	Refer here
transfer_initiated_at	string	Refer here
settled_at	string	Refer here
provider_name	String	Payment provider through which the mandate is created. Possible values: BILLDESK and RAZORPAY.
late_auth	Boolean	Denotes if the payment is late authorised. Refer here
refund_reference	string	Payment provider refund reference
refund_reason	string	Refund reason. Generally refund happens for late authorisation or duplicate payments.
refund_status	string	Refund status. Possible values: created, successful, failed
refund_created_at	string	Refund creation time stamp

Create a payment

curl -X POST "https://s.finprim.com/api/pg/payments/netbanking"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '
    {
  "amc_order_ids": [
    1,
    2
  ],
  "payment_postback_url": "https://example.com/"
}
  '

JSON Response

{
  "id": 1,
  "token_url": "https://tenant.s.finprim.com/api/pg/payments/netbanking/razorpay?txnId=d1c3242b-a74d-46f1-9c46-7704383be9bc&txnType=0",
  "sdk_options": {
    "razorpay": {
      "callback_url": "https://tenant.s.finprim.com/api/pg/payments/netbanking/razorpay/capture/1",
      "bank_code": "ICIC",
      "amount": 500000,
      "method": {
        "wallet": false,
        "netbanking": true,
        "card": false,
        "upi": true
      },
      "contact": "9642991181",
      "order_id": "order_NftqGAVGBEC5xM",
      "key": "rzp_test_wsjrkenfrke",
      "email": "abc@cybrilla.com"
    }
  }
}

POST /api/pg/payments/netbanking

Make payment for multiple orders together. It returns a URL to which the user has to be redirected to complete the payment. Netbanking and UPI are the allowed payment methods.

Parameters

Parameter	Mandatory	Type	Description
amc_order_ids	yes	Array	contains the list of amc order ids. These are the old_id of purchase orders.
method	no	String	NETBANKING or UPI
payment_postback_url	no	String	Application url where the investor will be redirected back after payment operation (http://example.com/payment_confirmation)
bank_account_id	no	Integer	FP bank account old_id generated using Create Bank Account API. TPV is done based on these bank account details.
provider_name	no	String	RAZORPAY (or) BILLDESK

Response Code : 200

After payment is completed, a post back using HTTP POST will be made via web browser to payment_postback_url if provided. Else, the callback will be sent to preconfigured default postback URL.

HTTP Form POST Parameters

Parameter	Type	Description
paymentId	String	ID of the generated payment
status	String	payment status either success or failure or pending
failureCode	String	payment failure code, empty if payment is successful or pending
failureReason	String	payment failure reason, empty if payment is successful or pending

You can use this data for displaying the status of the payment to the investor. The failureCode can be used for programmatic actions upon payment failure or for creating custom failure messages displayed to investors. The failureReason can be directly shown to investors. Please refer to the failure codes list.

Note

• Tenants using Billdesk V2 APIs can only create a payment for single AMC order due to absence of cart functionality in this version.
• For Billdesk as payment provider, to enable the UPI Intent, please refer here

Create an eNACH or UPI Autopay Payment

POST /api/pg/payments/nach

curl -X POST "https://s.finprim.com/api/pg/payments/nach"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '
    {
  "mandate_id": 1,
  "amc_order_ids": [
    1,
    2
  ]
}
  '

JSON Response

{
  "id": 1,
  "mandate_id": 1,
  "amount": 80000,
  "amc_order_ids": [
    1,
    2
  ]
}

This endpoint can be used to create payments for multiple purchase orders which are in pending status and belong to a single investment account.

Limitations :

1. Can make payments only for purchase orders placed via RTA route .
2. During the creation of payments that are triggered from this API, the platform doesn't check whether there are payments already created for the orders. Therefore, please ensure that there you are not creating multiple payments for the same order.
3. For Billdesk as payment provider, payment can be created only for one AMC order at a time.

Parameters

Parameter	Mandatory	Type	Description
mandate_id	yes	Integer	Id of the mandate which is returned as a part of the response of Create Mandate API. Please note that if the mandate is not in the APPROVED state, the payment that is created will be marked as FAILED
amc_order_ids	yes	Array	old_id of mf purchase orders for which the payments must be made using the mandate. Please note that there are following restrictions. a) All the orders must be in the PENDING state. b) All the orders must belong to a single investment account. c) The mandate must be associated with the investor mapped to the investment account.

Response Code : 200

Fetch a payment

curl "https://s.finprim.com/api/pg/payments/1"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "payment_type": "NETBANKING",
  "status": "FAILED",
  "amount": 7000.0,
  "debit_date": "2024-01-16",
  "amc_order_ids": [
    1
  ],
  "failed_reason": "Payment was not completed within the allotted time. Please retry the payment",
  "method": "NETBANKING",
  "created_at": "2024-01-16T12:30:55+05:30",
  "submitted_at": null,
  "debit_confirmed_at": null,
  "failed_at": "2024-01-16T12:31:14+05:30",
  "transfer_initiated_at": null,
  "settled_at": null,
  "rejected_at": null,
  "from_bank_account_id": 1,
  "provider_name": "RAZORPAY",
  "failure_code": "pg_payment_expired",
  "late_auth": true,
  "refund_reference": "rfnd_NPC5uKsdkfF",
  "refund_reason": "late_authorization",
  "refund_status": "SUCCESSFUL",
  "refund_created_at": "2024-01-16T12:31:28+05:30",
  "id": 1
}

GET /api/pg/payments/:id

Retrieve a particular payment with id

List all payments

curl "https://s.finprim.com/api/pg/payments"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "last": true,
  "total_pages": 1,
  "total_elements": 2,
  "size": 20,
  "number": 0,
  "first": true,
  "number_of_elements": 2,
  "payments": [
    {
      "id": 1,
      "payment_type": "NETBANKING",
      "status": "FAILED",
      "amount": 1000,
      "debit_date": "2019-01-01",
      "amc_order_ids": [
        1
      ],
      "failed_reason": "Failed by system due to inactivity",
      "method": null,
      "created_at": "2018-12-31T01:00:02+05:30",
      "submitted_at": null,
      "debit_confirmed_at": null,
      "failed_at": null,
      "transfer_initiated_at": null,
      "settled_at": null,
      "rejected_at": null,
      "from_bank_account_id": 666,
      "provider_name": "RAZORPAY"
    },
    {
      "id": 2,
      "payment_type": "NACH",
      "status": "SUBMITTED",
      "amount": 2000,
      "debit_date": "2019-01-01",
      "amc_order_ids": [
        2
      ],
      "failed_reason": null,
      "method": null,
      "created_at": "2018-12-31T01:00:02+05:30",
      "submitted_at": "2018-12-31T01:30:02+05:30",
      "debit_confirmed_at": null,
      "failed_at": null,
      "transfer_initiated_at": "2018-12-31T01:10:02+05:30",
      "settled_at": null,
      "rejected_at": null,
      "from_bank_account_id": 668,
      "provider_name": "RAZORPAY"
    }
  ]
}

GET /api/pg/payments

Retrieve the list of all payments and filter the result with the following parameters

Query Parameters

Parameter	Mandatory	Default	Description	Allowed values
from	no	-	from which date you want to search	valid date (yyyy-MM-dd format)
to	no	-	up to which date you want to search. Should only be passed when from is provided	valid date (yyyy-MM-dd format)
payment_type	no	-	type of payment you want to get	NACH, NETBANKING, ECS, CHEQUE or AUTH_TRANSACTION
payment_status	no	-	multiple payment status separated by a comma	SUBMITTED, APPROVED,REJECTED, INITIATED,PENDING,SUCCESS,FAILED
amc_order_ids	no	-	multiple amc order IDs separated by a comma
direction	no	desc	ascending order or Descending order	asc or desc
page	no	0	page number of the result set
size	no	20	number of results per page, size should not be greater than 100

MF Folios

When a mutual fund investor invests a sum into a mutual fund scheme, a unique folio number is generated by the asset management company (AMC). It is also known as folio_number. The data will be available in FP after the successful migration of the reporting files provided by the individual RTAs.

Endpoints:

GET /v2/mf_folios Patch /v2/mf_folios

MF Folio Object

{
  "object": "mf_folio",
  "amc": "103",
  "number": "61576584",
  "dp_id": null,
  "client_id": null,
  "primary_investor_pan": "EWLPS1890F",
  "secondary_investor_pan": null,
  "third_investor_pan": null,
  "holding_pattern": "single",
  "primary_investor_name": "ANANDHAN S",
  "secondary_investor_name": null,
  "third_investor_name": null,
  "primary_investor_dob": "1993-04-07",
  "secondary_investor_dob": null,
  "third_investor_dob": null,
  "primary_investor_gender": null,
  "secondary_investor_gender": null,
  "third_investor_gender": null,
  "primary_investor_tax_status": "individual",
  "primary_investor_occupation": "service",
  "guardian_name": null,
  "guardian_gender": null,
  "guardian_pan": null,
  "guardian_dob": null,
  "guardian_relationship": null,
  "nominee1": null,
  "nominee1_allocation_percentage": null,
  "nominee2": null,
  "nominee2_allocation_percentage": null,
  "nominee3": null,
  "nominee3_allocation_percentage": null,
  "payout_details": [
    {
      "scheme": "INF179K01XQ0",
      "scheme_code": "HMCOGT",
      "bank_account": {
        "name": null,
        "number": "SB 8132",
        "account_type": "savings",
        "ifsc": null
      }
    }
  ],
  "contact_details": [
    {
      "address": {
        "line1": "D/O LATE SHRI SUBHASH CHANDER CHHABRA",
        "line2": "PATWARIAN WALI BABA NAMDEV NAGAR",
        "line3": "ST NO-3 NR JODIYAN CHAHIYAN",
        "city": "KOTKAPURA",
        "state": "PUNJAB",
        "postal_code": "151204",
        "country_name": null,
        "country_ansi_code": null
      },
      "email": null,
      "mobile": null,
      "type": "correspondence"
    }
  ],
  "email_addresses": [
    "investoremail@gmail.com"
  ],
  "mobile_numbers": [
    "+919998886665"
  ]
}

Attribute	Type	Comments
object	string	Value is mf_folio. String representing the object type. Objects of the same type share the same value
amc	string	A unique code to identify the AMC to which this folio belongs to
number	string	Folio number
dp_id	string	Depository Participant ID of the demat account
client_id	string	Client ID of the demat account
primary_investor_pan	string	PAN of the first holder
secondary_investor_pan	string	PAN of the second holder
third_investor_pan	string	PAN of the third holder
holding_pattern	string	Holding nature of the investment account Possible values: single,joint,either_or_survivor,anyone_or_survivor,first_or_survivor
primary_investor_name	string	Name of the first holder
secondary_investor_name	string	Name of the second holder
third_investor_name	string	Name of the third holder
primary_investor_dob	string	Date of birth of the first holder
secondary_investor_dob	string	Date of birth of the second holder
third_investor_dob	string	Date of birth of the third holder
primary_investor_gender	string	Gender of the first holder
secondary_investor_gender	string	Gender of the second holder
third_investor_gender	string	Gender of the third holder
primary_investor_tax_status	string	Tax status of the first holder Possible values: individual,on_behalf_of_minor,others,nri_minor_nre,nri_minor_nro,qualified_foreign_investor_individual,qualified_foreign_investor_minors
primary_investor_occupation	string	Occupation of the first holder Possible values: business, service, professional,agriculture,retired,house_wife,student,doctor,private_sector_service,public_sector_service,forex_dealer,government_service,unknown_or_not_applicable,others
guardian_name	string	Name of the guardian. Please note that guardian details will be available only if the investor is a minor investor
guardian_gender	string	Gender of the guardian. Possible values: male,female,others
guardian_pan	string	PAN number of the guardian
guardian_dob	string	Date of birth of the guardian
guardian_relationship	string	Relationship of the guardian with primary investor
nominee1	object	Nominee 1 details
nominee1_allocation_percentage	string	Nominee 1 allocation percentage
nominee2	object	Nominee 2 details
nominee2_allocation_percentage	object	Nominee 2 allocation percentage
nominee3	string	Nominee 3 details
nominee3_allocation_percentage	string	Nominee 3 allocation percentage
payout_details	list	List of bank accounts defined at scheme level. These are the bank accounts to which dividend payouts and redemption proceeds will be deposited
email_addresses	string[]	Email addresses registered against the folio
mobile_numbers	string[]	Mobile numbers registered against the folio

Nominee Detail

Attribute	Type	Comments
name	string	Nominee name
dob	string	Date of birth of the nominee
relationship	string	Relationship of the nominee with the primary investor
guardian	string	Guardian of the nominee in cases where nominee is a minor
guardian_relationship	string	Relationship of the nominee with the guardian

Payout Detail

Attribute	Type	Comments
scheme	string	ISIN of a scheme in the folio
scheme_code	string	This is unique identifier to identify a scheme in the folio. If there are dividend payouts or redemptions against this particular scheme in the folio, amount would be deposited to the bank account configured against this particular scheme in the folio
bank_account	object	Details of the bank account configured for payout purposes

Bank Account

Attribute	Type	Comments
name	string	Account holders name
number	string	Bank account number
account_type	string	Bank account type Possible values: savings,current,nre,nro
ifsc	string	IFSC of the bank branch where the bank account is present

Deprecated Attribute	New Attributes
contact_details	email_addresses mobile_numbers annexure

Fetch all folios

GET /v2/mf_folios

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

This API is used to fetch all mf_folios.

Query Parameters

Name	Mandatory	Type	Comments
folio_number	no	string	Folio number to be filtered
mf_investment_account	no	string	Investment Account ID

Note:

The response can contain 100 latest folios at max.

JSON Response:

{
  "object": "list",
  "data": [
    {
      "object": "mf_folio",
      "amc": "103",
      "number": "61576584",
      "dp_id": null,
      "client_id": null,
      "primary_investor_pan": "EWLPS1890F",
      "secondary_investor_pan": null,
      "third_investor_pan": null,
      "holding_pattern": "single",
      "primary_investor_name": "ANANDHAN S",
      "secondary_investor_name": null,
      "third_investor_name": null,
      "primary_investor_dob": "1993-04-07",
      "secondary_investor_dob": null,
      "third_investor_dob": null,
      "primary_investor_gender": null,
      "secondary_investor_gender": null,
      "third_investor_gender": null,
      "primary_investor_tax_status": "individual",
      "primary_investor_occupation": "service",
      "guardian_name": null,
      "guardian_gender": null,
      "guardian_pan": null,
      "guardian_dob": null,
      "guardian_relationship": null,
      "nominee1": null,
      "nominee1_allocation_percentage": null,
      "nominee2": null,
      "nominee2_allocation_percentage": null,
      "nominee3": null,
      "nominee3_allocation_percentage": null,
      "payout_details": [
        {
          "scheme": "INF179K01XQ0",
          "scheme_code": "HMCOGT",
          "bank_account": {
            "name": null,
            "number": "SB 8132",
            "account_type": "savings",
            "ifsc": null
          }
        }
      ],
      "contact_details": [
        {
          "address": {
            "line1": "D/O LATE SHRI SUBHASH CHANDER CHHABRA",
            "line2": "PATWARIAN WALI BABA NAMDEV NAGAR",
            "line3": "ST NO-3 NR JODIYAN CHAHIYAN",
            "city": "KOTKAPURA",
            "state": "PUNJAB",
            "postal_code": "151204",
            "country_name": null,
            "country_ansi_code": null
          },
          "email": null,
          "mobile": null,
          "type": "correspondence"
        }
      ],
      "email_addresses": [
        "investoremail@gmail.com"
      ],
      "mobile_numbers": [
        "+919998886665"
      ]
    }
  ]
}

Testing Fetch all folios API in sandbox

The responses of fetch all folios in sandbox environment is simulated and because of this, to view folio details in sandbox you are required to provide the context of investment account in sandbox environment. If you don't provide an investment account context we will return an empty array in sandbox. Please note that this applicable only in sandbox.

To get response for the folio_number, do the following,

• Create an mf_purchases and mark the order to successful state using the simulate order api, after which an folio_number is tagged with the order created.
• Pass mf_investment_account and folio_number to get response for the mf_folios api. The data will reflect the investor attached to the mf_invesment_account

Investor Reports

Generate holdings report

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

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

JSON response

{
  "id": 12,
  "folios": [
    {
      "folio_number": "4131/34",
      "schemes": [
        {
          "isin": "INF740K01599",
          "name": "DSP BlackRock Income Opportunities Fund - Regular Plan -Growth",
          "type": "GROWTH",
          "holdings": {
            "as_on": "2018-03-12",
            "units": 83.597,
            "redeemable_units": 83.597
          },
          "market_value": {
            "as_on": "2018-03-08",
            "amount": 2368.4,
            "redeemable_amount": 2368.4
          },
          "invested_value": {
            "as_on": "2018-03-12",
            "amount": 2250
          },
          "payout": {
            "as_on": "2018-03-12",
            "amount": 0
          },
          "nav": {
            "as_on": "2018-03-08",
            "value": 28.3312
          }
        }
      ]
    },
    {
      "folio_number": "4998484493",
      "schemes": [
        {
          "isin": "INF204K01EF9",
          "name": "Reliance Medium Term Growth",
          "type": "GROWTH",
          "holdings": {
            "as_on": "2018-03-12",
            "units": 170.882,
            "redeemable_units": 170.882
          },
          "market_value": {
            "as_on": "2018-03-08",
            "amount": 6181.69,
            "redeemable_amount": 6181.69
          },
          "invested_value": {
            "as_on": "2018-03-12",
            "amount": 6000
          },
          "payout": {
            "as_on": "2018-03-12",
            "amount": 0
          },
          "nav": {
            "as_on": "2018-03-08",
            "value": 36.1752
          }
        }
      ]
    }
  ]
}

GET /api/oms/reports/holdings

Generate a holdings report for an investment account or a set of folio numbers.

Query Parameters

Name	Mandatory	Description
investment_account_id	no	ID of an investment account
folios	no	comma separated list of folio numbers
as_on	no	date till data required, in yyyy-MM-dd format

Note : Either investment_account_id or folios are mandatory.

GET api/oms/investment_accounts/:id/holdings

Generate a holdings report for an investment account

Query Parameters

Name	Mandatory	Description
folios	no	comma separated list of folio numbers
as_on	no	date till data required, in yyyy-MM-dd format

RESPONSE

Returns a list of folios with the associated holdings per scheme in each folio. An empty array is returned if no folios exist.

Capital gains report

curl -X POST "https://s.finprim.com/v2/transactions/reports/capital_gains"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{
    "mf_investment_account":"mfia_7d82c65058114062a0654e4146a38e14",
    "scheme":"INF760K01EL8",
    "folios":["62010247"]
  }'

JSON response

{
  "object": "transaction_report",
  "report": {
    "type": "standard",
    "standard": {
      "name": "capital_gains",
      "desc": "This report lists capital gains for an investment account for each redemption or switchout transaction"
    }
  },
  "data": {
    "rows": [
      [
        "62010247",
        "INF760K01EL8",
        "CANARA ROBECO EQUITY TAX SAVER FUND DIRECT GROWTH",
        "redemption",
        1200.0,
        100.0,
        "2020-01-02",
        12.0,
        1462,
        "2016-01-02",
        10.0,
        200.0,
        -5070.0,
        true,
        62.7,
        1137.8,
        62.2
      ]
    ],
    "columns": [
      "folio_number",
      "isin",
      "scheme_name",
      "type",
      "amount",
      "units",
      "traded_on",
      "traded_at",
      "source_days_held",
      "source_purchased_on",
      "source_purchased_at",
      "source_actual_gain",
      "source_taxable_gain",
      "grand_fathering",
      "grand_fathering_nav",
      "indexed_cost_of_acquisition",
      "indexed_capital_gain"
    ]
  },
  "filter_by": {
    "mf_investment_account": "mfia_7d82c65058114062a0654e4146a38e14",
    "folios": [
      "62010247"
    ],
    "scheme": "INF760K01EL8",
    "traded_on_from": null,
    "traded_on_to": null
  }
}

POST /v2/transactions/reports/capital_gains

Generate capital gains report for an investment account.

Filter Parameters

Name	Mandatory	Description
mf_investment_account	yes	Investment account id
folios	no	comma separated list of folio numbers
scheme	no	ISIN of the scheme
traded_on_from	no	date (yyyy-MM-dd) from which transactions must be filtered. If not specified, this filter will not be applied.
traded_on_to	no	date (yyyy-MM-dd) till which transactions must be filtered. If not specified, defaults to current date.

Response

Returns an array of items with capital gain/loss calculated on each eligible transaction. Empty array if no eligible transactions found.

Columns

Field	Type	Description
folio_number	string	Folio number
isin	string	Isin of the scheme involved
scheme_name	string	Scheme name as it appears in the CAS file. Note: Any scheme name which is spread across more than one line is truncated
type	string	Transaction type. Possible values - redemption, switch_out
amount	decimal	Transaction amount
units	decimal	Transaction units
traded_on	string	Transaction trade date
traded_at	decimal	NAV of the scheme at which the trade happened
source_days_held	number	Number of days the units were held before it was traded
source_purchased_on	string	The date on which the units were purchased
source_purchased_at	decimal	NAV at which the purchase was made
source_actual_gain	decimal	The actual gain
source_taxable_gain	decimal	The gain which is taxable. Grandfathering is used in calculation if applicable.
grand_fathering	boolean	Whether grandfathering is applied when calculating taxable gain
grand_fathering_nav	decimal	NAV of the scheme on 31-JAN-2028. Will be null if not eligible for grandfathering
indexed_cost_of_acquisition	decimal	Cost of acquiring the asset after considering the indexation
indexed_capital_gains	decimal	Capital gains after considering indexation

Scheme wise returns

curl -X POST "https://s.finprim.com/v2/transactions/reports/scheme_wise_returns"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{
    "mf_investment_account":"mfia_7d82c65058114062a0654e4146a38e14",
    "traded_on_to":"2022-05-01"
  }'

JSON response

{
  "object": "transaction_report",
  "report": {
    "type": "standard",
    "standard": {
      "name": "scheme_wise_returns",
      "desc": "This report lists scheme wise returns for an investment account"
    }
  },
  "data": {
    "rows": [
      [
        "INF109K01GU4",
        "ICICI Pru Credit Risk Fund (G)",
        "REGULAR",
        "GROWTH",
        "2022-05-01",
        25.2044,
        14059.24,
        6410.33,
        -7648.91,
        -54.4,
        55.2787,
        254.3336,
        0.0
      ],
      [
        "INF109KC11A4",
        "ICICI PRUDENTIAL NIFTY BANK INDEX FUND - DIRECT PLAN - GROWTH",
        "DIRECT",
        "GROWTH",
        "2022-05-01",
        10.1823,
        999.96,
        132.84,
        -867.12,
        -86.72,
        76.6487,
        13.046,
        -79.22
      ]
    ],
    "columns": [
      "isin",
      "scheme_name",
      "plan_type",
      "investment_option",
      "as_on",
      "nav",
      "invested_amount",
      "current_value ",
      "unrealized_gain",
      "absolute_return",
      "average_buying_value",
      "units",
      "xirr"
    ]
  },
  "filter_by": {
    "mf_investment_account": "mfia_7d82c65058114062a0654e4146a38e14",
    "traded_on_to": "2022-05-01"
  }
}

POST /v2/transactions/reports/scheme_wise_returns

Generate a scheme wise returns report for an investment account.

Filter Parameters

Name	Mandatory	Description
mf_investment_account	yes	Investment account id
traded_on_to	no	date till data required, in yyyy-MM-dd format

Response

Scheme level returns for each scheme under the investment account. Returns from same scheme under different folios are consolidated and reported as a single element in the array.

Columns

Field	Type	Description
isin	string	Isin of the scheme
scheme_name	string	Name of the scheme
plan_type	string	REGULAR, DIRECT.
investment_option	string	GROWTH,PAYOUT or REINVESTMENT
as_on	string	NAV date
nav	decimal	NAV
invested_amount	decimal	Amount invested in the given period
current_value	decimal	Current value of the investment
unrealized_gain	decimal	Total gain/loss from the investments made till traded_on_to
absolute_return	decimal	Absolute return percentage
average_buying_value	decimal	Average cost of each unit accrued
units	decimal	Total units accrued
xirr	decimal	Extended Internal rate of Return

Investment account wise returns

curl -X POST "https://s.finprim.com/v2/transactions/reports/investment_account_wise_returns"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{
    "mf_investment_account":"mfia_54a603fa05784036beed80ef97b24df7"
  }'

JSON Response

{
  "object": "transaction_report",
  "report": {
    "type": "standard",
    "standard": {
      "name": "investment_account_wise_returns",
      "desc": "This report lists returns for an investment account"
    }
  },
  "data": {
    "rows": [
      [
        "mfia_54a603fa05784036beed80ef97b24df7",
        159923.28,
        177278.52,
        17355.24,
        10.85,
        5.29,
        6.25
      ]
    ],
    "columns": [
      "mf_investment_account",
      "invested_amount",
      "current_value",
      "unrealized_gain",
      "absolute_return",
      "cagr",
      "xirr"
    ]
  },
  "filter_by": {
    "mf_investment_account": "mfia_54a603fa05784036beed80ef97b24df7",
    "traded_on_to": null
  }
}

POST /v2/transactions/reports/investment_account_wise_returns

Generate returns for an investment account.

Filter Parameters

Name	Mandatory	Description
mf_investment_account	yes	Investment account id
traded_on_to	no	date till data required, in yyyy-MM-dd format

Response

Consolidated returns from all the schemes for an investment acount.

Columns

Field	Type	Description
mf_investment_account	string	Investment account id
invested_amount	decimal	Amount invested in the given period
current_value	decimal	Current value of the investment
unrealized_gain	decimal	Total gain/loss from the investments made till traded_on_to
absolute_return	decimal	Absolute return percentage
cagr	decimal	Compound Annual Growth Rate1
xirr	decimal	Extended Internal rate of Return

¹Compound Annual Growth Rate is calculated as = (current_value/invested_amount)^(1/t)-1,
where t = number of years between traded_on_to and the day the first purchase was made.

Other Reports

FP Reporting framework allows users to access information in an organized tabular format. We have defined a set of standard reports all of which follow a same well defined format. Depending upon the report type, FP also allows you to apply filters on the reports to narrow down the scope of the report information.

Note:
At present, the maximum number of rows in a report API response is limited to 2000.

Report object

Attibute	Type	Comments
object	string	The value describes the category of a report. For example, transaction_report is category of reports which are primarily based on MF transactions. There might be multiple different reports under this category.
report	hash	Meta data about the report.
data	hash	Actual report data.
filter_by	hash	Filters applied while retrieving report data.

Report attributes

Attibute	Type	Description
type	string	At present, this will be standard which means that this is a standard report which has been predefined by FP for its users.
standard.name	string	Name of the standard report.
standard.desc	string	Human readable description of the standard report.

Data attributes

You can consider data attribute as an attribute whose value is a table containing the actual report data but in json format. Rows are represented by rows and coloumns are represented by columns

Attibute	Type	Description
rows	array	Each row is an array of values. The position of the value in the array determines the column to which this value belongs to. If there are multiple rows, rows attribute will contain array of such rows.
columns	array	List of column names. The details of the columns are defined the specific reports in detail.

Filter_by attributes

Please refer to specific report types for filter options.

Transaction type wise amount summary report

This report groups the transactions by their type and provides the consolidated amount against each such transaction type.

curl -X POST "https://s.finprim.com/v2/transactions/reports/transaction_type_wise_amount_summary"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
    "partner": "ARN-98783",
    "traded_on_from": "2000-01-01",
    "traded_on_to": "2021-07-07"
  }'

RESPONSE:

{
  "object": "transaction_report",
  "report": {
    "type": "standard",
    "standard": {
      "name": "transaction_type_wise_amount_summary",
      "desc": "This report exposes the sum of transaction amount per each transaction type."
    }
  },
  "data": {
    "rows": [
      [
        "redemption",
        4044374.07
      ],
      [
        "switch_out",
        6713373.75
      ],
      [
        "purchase",
        13411292.51
      ],
      [
        "transfer_in",
        42440.77
      ],
      [
        "switch_in",
        7029926.1
      ],
      [
        "dividend_payout",
        185723.7
      ],
      [
        "sip",
        2921466.03
      ]
    ],
    "columns": [
      "type",
      "value"
    ]
  },
  "filter_by": {
    "partner": "ARN-98783",
    "traded_on_from": "2000-01-01",
    "traded_on_to": "2021-07-07"
  }
}

Filter parameters

Name	Mandatory	Type	Comments
partner	No	string	ARN code or RIA code as it appears against the transaction
traded_on_from	No	string	Default value is traded_on_to - 30 days. Date must be in yyyy-mm-dd format. All transactions processed by RTAs on or after the traded_on_from would be considered for creating this report.
traded_on_to	No	string	Default value is current date. Date must be in yyyy-mm-dd format. All transactions processed by RTAs on or before the traded_on_to would be considered for creating this report.

Columns

Column	Type	Description
type	string	Represents transaction type. Transaction types are: purchase, sip, redemption, transfer_in, transfer_out, dividend_reinvestment, dividend_payout, bonus, switch_in, switch_out, demat, remat, pledging, un_pledging, demat_transfer_in, demat_transfer_out Please note that purchase amount includes all purchase transactions including sip installments.
value	decimal	Transaction amount.

Sort order

Transactions are sorted based on the trade date(i.e. the date on which these transactions were processed by RTAs) in descending order.

Fund scheme category wise AUM summary report

This report groups provides the AUM for each fund category

POST /v2/transactions/reports/fund_scheme_category_wise_aum_summary

curl -X POST "https://s.finprim.com/v2/transactions/reports/fund_scheme_category_wise_aum_summary"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
    "partner": "ARN-98783",
    "traded_on_from": "2021-06-01",
    "traded_on_to": "2021-07-07",
  }'

RESPONSE:

{
  "object": "transaction_report",
  "report": {
    "type": "standard",
    "standard": {
      "name": "fund_scheme_category_wise_aum_summary",
      "desc": "This report exposed the total AUM at fund scheme category level."
    }
  },
  "data": {
    "rows": [
      [
        "equity",
        102767.44
      ],
      [
        "debt",
        32060.2
      ]
    ],
    "columns": [
      "fund_category",
      "value"
    ]
  },
  "filter_by": {
    "partner": "ARN-98783",
    "traded_on_from": "2021-06-01",
    "traded_on_to": "2021-07-07"
  }
}

Filter parameters

Name	Mandatory	Type	Comments
partner	No	string	ARN code or RIA code as it appears against the transaction
traded_on_from	No	string	If traded_on_from is not specified, all transactions since inception are considered. Date must be in yyyy-mm-dd format. All transactions processed by RTAs on or after the traded_on_from would be considered for creating this report.
traded_on_to	No	string	Default value is current date. The date must be in yyyy-mm-dd format. All transactions processed by RTAs on or before the traded_on_to would be considered for creating this report.

Columns

Column	Type	Description
fund_category	string	Fund category. Possible values: equity debt liquid others
value	decimal	AUM for the fund_category

Sort order

Transactions are sorted based on the trade date(i.e. the date on which these transactions were processed by RTAs) in descending order.

Transaction list report

This report lists the transactions.

POST /v2/transactions/reports/transaction_list

curl -X POST "https://s.finprim.com/v2/transactions/reports/transaction_list"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
    "partner": "ARN-98783",
    "traded_on_to": "2021-08-20",
    "folio_number": "60270555"
  }'

RESPONSE:

{
  "object": "transaction_report",
  "report": {
    "type": "standard",
    "standard": {
      "name": "transaction_list",
      "desc": "List transactions matching the given filters."
    }
  },
  "data": {
    "rows": [
      [
        "60270555",
        "Sarath Sandeep",
        "INF173K01940",
        "purchase",
        3499.83,
        17.245,
        "2021-06-28",
        202.95,
        null,
        "103GFGPG",
        "GF60273155SIN825689",
        "GROWTH"
      ],
      [
        "60270555",
        "Sarath Sandeep",
        "INF173K01940",
        "purchase",
        3499.83,
        18.258,
        "2021-05-26",
        191.69,
        null,
        "103GFGPG",
        "GF60273155SIN792153",
        "GROWTH"
      ]
    ],
    "columns": [
      "folio_number",
      "primary_investor_name",
      "isin",
      "type",
      "amount",
      "units",
      "traded_on",
      "traded_at",
      "corporate_action",
      "rta_product_code",
      "rta_order_reference",
      "rta_investment_option"
    ]
  },
  "filter_by": {
    "partner": "ARN-98783",
    "traded_on_to": "2021-08-20",
    "folio_number": "60270555"
  }
}

Filter parameters

Name	Mandatory	Type	Comments
partner	No	string	ARN code or RIA code as it appears against the transaction
traded_on_from	No	string	If traded_on_from is not specified, the latest 2000 transactions are considered. The date must be in yyyy-mm-dd format. All transactions processed by RTAs on or after the traded_on_from would be considered for creating this report.
traded_on_to	No	string	Default value is current date. The date must be in yyyy-mm-dd format. All transactions processed by RTAs on or before the traded_on_to would be considered for creating this report.
primary_investor_name	No	string	Name of the primary investor. Any transactions are done by investors having names that contain primary_investor_name as a substring will be considered in this report. Name matching is case insensitive.
folio_number	No	string	Filter transactions by folio number. The folio number should match exactly as it appears against the transaction
pan_number	No	string	Pan number of the primary investor. An exact case-insensitive match must happen.

Columns

Column	Type
folio_number	string
primary_investor_name	string
isin	string
type	string
amount	decimal
units	decimal
traded_on	string
traded_at	decimal
corporate_action	string
rta_product_code	string
rta_order_reference	string
rta_investment_option	string

Sort order

Transactions are sorted based on the trade date(i.e. the date on which these transactions were processed by RTAs) in descending order.

Investor list report

This report lists the investors.

POST /v2/investors/reports/investor_list

curl -X POST "https://s.finprim.com/v2/transactions/reports/transaction_list"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
      "partner" : "ARN-00341"
  }'

RESPONSE:

{
  "object": "investor_report",
  "report": {
    "type": "standard",
    "standard": {
      "name": "investor_list",
      "desc": "List of investors matching the given filters"
    }
  },
  "data": {
    "rows": [
      [
        "veena.gos@gmail.com",
        "9822222271",
        "Veena Nandlal Goswami",
        "ABBPG3634E"
      ],
      [
        "sujaydey_new@gmail.com",
        "9876789872",
        "SUJAY SARAT DEY",
        "AMMPD2369R"
      ]
    ],
    "columns": [
      "email",
      "mobile",
      "investor_name",
      "pan_number"
    ]
  },
  "filter_by": {
    "partner": "ARN-00341"
  }
}

Filter parameters

Name	Mandatory	Type	Comments
partner	Yes	string	ARN code or RIA of the partner

Columns

Column	Type	Description
email	string	Email id of the investor.
mobile	string	Mobile number of the investor.
investor_name	string	Primary investor name
pan_number	string	Pan number of the primary investor.

Mf Purchase list report

This report lists mf_purchases.

POST /v2/mf_purchases/reports/mf_purchase_list

curl -X POST "https://s.finprim.com/v2/mf_purchases/reports/mf_purchase_list"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
      "states" : ["successful", "submitted"],
      "plan_old_ids" : ["1001"]
  }'

RESPONSE:

{
  "object": "mf_purchase_list",
  "report": {
    "type": "standard",
    "standard": {
      "name": "mf_purchase_list",
      "desc": "List mf_purchases matching the given filters."
    }
  },
  "data": {
    "rows": [
      [
        "mf_purchase",
        "mfp_ad0145004e6949bd92ae41ecfc0ec21b",
        17276,
        "mfia_4742fd0a211b414ba0cae0f2519130f9",
        "62707385",
        "successful",
        1000,
        72.565,
        999.95,
        13.78,
        "INF173K01OW0",
        "additional_purchase",
        "mfpp_c470ab238bcd466cb12c22493e7ad5f0",
        "2021-08-11"
      ],
      [
        "mf_purchase",
        "mfp_142201fcd67d4e4c821bd6dec4ae8c69",
        14153,
        "mfia_4742fd0a211b414ba0cae0f2519130f9",
        "62707385",
        "successful",
        1000,
        75.525,
        999.95,
        13.24,
        "INF173K01OW0",
        "additional_purchase",
        "mfpp_c470ab238bcd466cb12c22493e7ad5f0",
        "2021-07-12"
      ]
    ],
    "columns": [
      "object",
      "id",
      "old_id",
      "mf_investment_account",
      "folio_number",
      "state",
      "amount",
      "allotted_units",
      "purchased_amount",
      "purchased_price",
      "scheme",
      "type",
      "plan",
      "traded_on"
    ]
  },
  "filter_by": {
    "states": [
      "successful",
      "submitted"
    ],
    "plan_old_ids": [
      "1001"
    ]
  }
}

Filter parameters

Name	Mandatory	Type	Comments
ids	No	string[]	IDs of mf purchases.
states	No	string[]	Supportes states are pending, confirmed, submitted, successful, failed, cancelled, refunded and reversed.
plans	No	string[]	Id of mf purchase plans.
plan_old_ids	No	string[]	Old IDs of plans.

Columns

Column	Type	Description
object	string	See details here
id	string	See details here
old_id	integer	See details here
mf_investment_account	string	See details here
folio_number	string	See details here
state	string	See details here
amount	decimal	See details here
allotted_units	decimal	See details here
purchased_amount	decimal	See details here
purchased_price	decimal	See details here
scheme	string	See details here
type	string	See details here
plan	string	See details here
scheduled_on	string	See details here
traded_on	string	See details here

Mf Redemption list report

This report lists mf_redemptions.

POST /v2/mf_redemptions/reports/mf_redemption_list

curl -X POST "https://s.finprim.com/v2/mf_redemptions/reports/mf_redemption_list"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
      "states" : ["successful"],
    "plans" : ["mfrp_1e43165c56114f5989e94df73d28cb7d"]
  }'

RESPONSE:

{
  "object": "mf_redemption_list",
  "report": {
    "type": "standard",
    "standard": {
      "name": "mf_redemption_list",
      "desc": "List mf_redemptions matching the given filters."
    }
  },
  "data": {
    "rows": [
      [
        "mf_redemption",
        "mfr_7e5419b8797a4a3e8e2e03d7c5182c99",
        18187,
        "mfia_5b67630c5d214fcd9b22c1c9b82bf5bd",
        "55719454",
        "successful",
        1500,
        14.555,
        1500.04,
        103.06,
        "INF173K01189",
        "redemption",
        "mfrp_1e43165c56114f5989e94df73d28cb7d",
        "2021-08-20",
        "2021-08-20"
      ],
      [
        "mf_redemption",
        "mfr_afa8763b85a14d87a87a156008578daf",
        18133,
        "mfia_46c668adfb214fd59edcdba3b694a35c",
        "53736674",
        "successful",
        null,
        1276.447,
        215898.27,
        169.14,
        "INF173K01155",
        "redemption",
        "mfrp_1e43165c56114f5989e94df73d28cb7d",
        "2021-08-18",
        "2021-08-18"
      ]
    ],
    "columns": [
      "object",
      "id",
      "old_id",
      "mf_investment_account",
      "folio_number",
      "state",
      "amount",
      "redeemed_units",
      "redeemed_amount",
      "redeemed_price",
      "scheme",
      "type",
      "plan",
      "scheduled_on",
      "traded_on"
    ]
  },
  "filter_by": {
    "states": [
      "successful"
    ],
    "plans": [
      "mfrp_1e43165c56114f5989e94df73d28cb7d"
    ]
  }
}

Filter parameters

Name	Mandatory	Type	Comments
ids	No	string[]	IDs of mf redemptions.
states	No	string[]	Supportes states are pending, confirmed, submitted, successful, failed, cancelled, refunded and reversed.
plans	No	string[]	Id of mf redemption plans.
plan_old_ids	No	string[]	Old IDs of plans.

Columns

Column	Type
object	string
id	string
old_id	integer
mf_investment_account	string
folio_number	string
state	string
amount	decimal
redeemed_units	decimal
redeemed_amount	decimal
redeemed_price	decimal
scheme	string
type	string
plan	string
scheduled_on	string
traded_on	string

Schedule queries^{(Early Access)}

FP Schedule Query framework allows users to schedule queries through which they can recieve the results of the query on a daily, weekly or monthly basis. The result of the query are uploaded to our files server (.csv format) from where it can be downloaded using the files API.

Scheduling a new sql query in FP platform:

• Reach out to FP with the sql query and the schedule interval.
• We will schedule the query in our sql scheduling platform.
• Once the query is scheduled user can get the details of the query using our GET API.
• When the query gets executed in our platform, FP will create a schedule query run object which will give information about the status of the query job and the result.
• On successful executiong of the query FP will upload the result to the file server in csv format.
• Users can download the result of the query from files API by using the file ID which can be found in the scheduled query run object.
• Users can also subscribe to webhook notification as well. So, that whenever the query execution starts users can get notified about the status of the query job. We are providing three event object - schedule_query_run.created, schedule_query_run.successful & schedule_query_run.failed which can be used to get notification about the query job.

Endpoints:

GET /v2/reports/scheduled_queries
GET /v2/reports/scheduled_queries/:id
GET /v2/reports/scheduled_query_runs/
GET /v2/reports/scheduled_query_runs/:id

Note: The following apis are accessible only via auth token generated using /v2/auth apis

Schedule query object

The schedule query object will contain information about the query which is scheduled by the user. The user can decide what query they need to schedule and at what interval. As of now the query scheduling will be done manually by FP. We will be soon releasing POST apis through which users can schedule queries directly.

{
  "object": "scheduled_query",
  "id": "squery_d35b4901631547e18cd5d184c6a6b77f",
  "title": "next sip installement",
  "sql": "select * from mf_purchase_plan where state = 'active' and next_installment_date is not null and (next_installment_date = (current_date + interval '3' day) OR next_installment_date = (current_date + interval '5' day));",
  "enabled": true,
  "cron_schedule": "9 0 * * *",
  "start_date": "2023-12-11T05:30:00+05:30",
  "created_at": "2023-12-08T12:28:00+05:30"
}

Schedule query object attributes

Attribute	Type	Comments
object	string	Schedule query object
id	string	Identifier for schedule query
title	string	Title for the query which is scheduled
sql	string	SQL query which needs to be scheduled. (select queries only)
enabled	boolean	Is the query enabled or not
cron_schedule	string	Cron schedule for the query
start_date	string	Date when the schedule should start
created_at	string	Date when the object is created

List all schedule queries

curl "https://s.finprim.com/v2/reports/scheduled_queries"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON response

{
  "object": "list",
  "data": [
    {
      "object": "scheduled_query",
      "id": "squery_d9782f6cebde4c14b559449543b5bb3a",
      "title": "mf purchases report",
      "sql": "select * from mf_purchases",
      "enabled": true,
      "cron_schedule": "6 0 * * *",
      "start_date": "2023-12-12T00:00:00+05:30",
      "created_at": "2023-12-12T11:01:32+05:30"
    },
    {
      "object": "scheduled_query",
      "id": "squery_d35b4901631547e18cd5d184c6a6b77f",
      "title": "next sip installement",
      "sql": "select * from mf_purchase_plan where state = 'active' and next_installment_date is not null and (next_installment_date = (current_date + interval '3' day) OR next_installment_date = (current_date + interval '5' day));",
      "enabled": true,
      "cron_schedule": "9 0 * * *",
      "start_date": "2023-12-11T05:30:00+05:30",
      "created_at": "2023-12-08T12:28:00+05:30"
    }
  ]
}

GET /v2/reports/scheduled_queries

Returns a list of schedule queries assoicated with the user. An empty array is returned if no scheduled query exist.

Note: The response can contain 100 latest schedule queries at max.

Fetch a schedule query object

curl "https://s.finprim.com/v2/reports/scheduled_queries/:id"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON response

{
  "object": "scheduled_query",
  "id": "squery_d35b4901631547e18cd5d184c6a6b77f",
  "title": "next sip installement",
  "sql": "select * from mf_purchase_plan where state = 'active' and next_installment_date is not null and (next_installment_date = (current_date + interval '3' day) OR next_installment_date = (current_date + interval '5' day));",
  "enabled": true,
  "cron_schedule": "9 0 * * *",
  "start_date": "2023-12-11T05:30:00+05:30",
  "created_at": "2023-12-08T12:28:00+05:30"
}

GET /v2/reports/scheduled_queries/:id

Get schedule query object by identifier

Query Parameters

Name	Mandatory	Description
id	yes	Identifier for schedule query

Schedule query run object

Schedule query run object will contain information about the execution details of the schedule query job. For every schedule query obejct FP will create an associated schedule query run object based on the cron schedule of the schedule query object.
For example, if schedule query object is created with a daily schedule then FP will create a schedule query run object daily when the query gets executed in FP platform.

{
  "object": "scheduled_query_run",
  "id": "sqr_d7060ae074ef438cb7aa7d44cdbd189f",
  "scheduled_query": "squery_d72872191fba453eb150ace0f5616507",
  "file": "file_effd0931121047d4a0853ecd3086fe56",
  "state": "successful",
  "reason": null,
  "created_at": "2023-11-29T19:20:41+05:30"
}

Schedule query run object attributes

Attribute	Type	Comments
object	string	Schedule query run object
id	string	Identifier for schedule query run
scheduled_query	string	The identifier for the scheduled query for which the run happened
file	string	File ID of the result for the scheduled query run
state	string	Status of the job. Valid values: created, successful & failed
reason	string	Failure reason if any
created_at	string	Date when the object is created

List all schedule query runs

curl "https://s.finprim.com/v2/reports/scheduled_query_runs?scheduled_query=:id"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON response

{
  "object": "list",
  "data": [
    {
      "object": "scheduled_query_run",
      "id": "sqr_76124db422b54ad29d5b21fbce28cab6",
      "scheduled_query": "squery_d72872191fba453eb150ace0f5616507",
      "file": null,
      "state": "created",
      "reason": null,
      "created_at": "2023-12-12T16:16:43+05:30"
    },
    {
      "object": "scheduled_query_run",
      "id": "sqr_d7060ae074ef438cb7aa7d44cdbd189f",
      "scheduled_query": "squery_d72872191fba453eb150ace0f5616507",
      "file": "file_effd0931121047d4a0853ecd3086fe56",
      "state": "successful",
      "reason": null,
      "created_at": "2023-11-29T19:20:41+05:30"
    }
  ]
}

GET /v2/reports/scheduled_query_runs

Get list of all schedule query run object based on the identifier of the schedule query object.

Query Parameters

Name	Mandatory	Description
scheduled_query	yes	Identifier for schedule query object

Note: The response can contain 100 latest schedule queries at max.

Fetch a schedule query run object

curl "https://s.finprim.com/v2/reports/scheduled_query_runs/:id"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON response

{
  "object": "scheduled_query_run",
  "id": "sqr_d7060ae074ef438cb7aa7d44cdbd189f",
  "scheduled_query": "squery_d72872191fba453eb150ace0f5616507",
  "file": "file_effd0931121047d4a0853ecd3086fe56",
  "state": "successful",
  "reason": null,
  "created_at": "2023-11-29T19:20:41+05:30"
}

GET /v2/reports/scheduled_query_runs/:id

Get schedule query run by identifier

Query Parameters

Name	Mandatory	Description
id	yes	Identifier for schedule query

MF Investments Snapshots ^{(Early Access)}

These APIs can be used to fetch an investor's investments summary across all mutual funds

Endpoints:

POST /v2/mf_investments_snapshots
PATCH /v2/mf_investments_snapshots
GET /v2/mf_investments_snapshots/:id
GET /v2/mf_investments_snapshots

Basic workflow to fetch MF Investments Snapshot

1. Ensure an investor profile exists for an investor and at least one phone number / email address is tagged to the profile with belongs_to = self. This would be used to collect investor consent
2. Create a mf_investments_snapshot object by giving the Investor Profile ID along with either email_address or phone_number. The status would be consent_required at this stage
3. Use Update MF Investments Snapshot API to provide the OTP that the investor received. Now the status would be changed to submitted provided the OTP was successfully validated
4. In case the OTP was not provided within the valid time range, the status of such MF Investments Snapshot request would be marked as expired with failure_code as otp_expired
5. Now the MF Investments Snapshot request would be submitted to the gateway. Use Fetch MF Investments Snapshot API using the mf_investments_snapshot ID to get the updated status
6. If the gateway successfully processed the MF Investments Snapshot request, the status would be changed to successful
7. If the gateway rejected the MF Investments Snapshot request, the status would be changed to failed and a relevant failure reason would be mentioned in the failure_code attribute

MF Investments Snapshot Object

{
  "object": "mf_investments_snapshot",
  "id": "mfis_fe9348c57a4a04eaca50deb684cb502e",
  "as_on": "2024-01-22T16:34:19.739+05:30",
  "profile": "invp_904b5ba315514981bfbe4fb680ba8730",
  "phone_number": "phone_dd3c55f5c429462cad51fee7c37f81de",
  "email_address": null,
  "status": "successful",
  "failure_code": null,
  "folios": [
    {
      "folio_number": "21341231",
      "holding_pattern": "single",
      "amc_code": "hdfc",
      "schemes": [
        {
          "isin": "INF179K01LC5",
          "scheme_code": "LFIG",
          "fund_category": "equity",
          "investment_option": "growth",
          "nav": 12.2,
          "nav_on_date": "2023-11-09",
          "available_units": 1000,
          "redeemable_units": 1000,
          "available_amount": 12200,
          "redeemable_amount": 12200,
          "invested_amount": 13000,
          "gain_amount": -800,
          "gain_percentage": -6.12
        }
      ]
    }
  ],
  "source_ref_id": null,
  "consent_required_at": "2024-01-22T16:33:09.158+05:30",
  "submitted_at": "2024-01-22T16:33:19.467+05:30",
  "successful_at": "2024-01-22T16:34:19.739+05:30",
  "failed_at": null,
  "expired_at": null,
  "created_at": "2024-01-22T16:33:09.153+05:30",
  "updated_at": "2024-01-22T16:34:19.740+05:30"
}

Attribute	Type	Comments
object	string	Value is mf_investments_snapshot. String representing the object type. Objects of the same type share the same value
id	string	Unique identifier of the mf_investments_snapshot object
as_on	string	Indicates the timestamp in ISO Local Date Time yyyy-MM-ddThh:mm:ss format as on which this MF Investments Snapshot was fetched
profile	string	ID of the investor_profile. Note that ID of investor_profile_non_individual is not supported
phone_number	string	ID of the phone_number
email_address	string	ID of the email_address
status	string	Indicates the status of the mf_investments_snapshot object. Possible values are - consent_required, submitted, successful, failed and expired
failure_code	string	Indicates the reason behind failure or expiry of MF Investments Snapshot request. Possible values and descriptions are as given below - failure_at_gateway - The request could not be processed at the gateway otp_incorrect - The OTP given was incorrect and hence the MF Investments Snapshot request failed otp_expired - The mf_investments_snapshot was expecting the consent to be provided but the OTP validity elapsed and the transaction could not be further processed
folios	array	List of folios hash which belong to the investor
source_ref_id	string	An identifier that is unique across all MF Investments Snapshot. This is not generated by FP and is populated by API consumers for identification purposes (ideally an auto generated identifier / uuid to identify the MF Investments Snapshot in your application)
consent_required_at	string	The timestamp in ISO Local Date Time yyyy-MM-ddThh:mm:ss format at which MF Investments Snapshot object was created and is awaiting a consent from the investor
submitted_at	string	The timestamp in ISO Local Date Time yyyy-MM-ddThh:mm:ss format at which the MF Investments Snapshot request was submitted to the gateway for further processing
successful_at	string	The timestamp at which the MF Investments Snapshot request was successfully completed at the gateway
failed_at	string	Timestamp in ISO Local Date Time yyyy-MM-ddThh:mm:ss format when the MF Investments Snapshot request failed
expired_at	string	Timestamp in ISO Local Date Time yyyy-MM-ddThh:mm:ss format when the MF Investments Snapshot request expired
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

folios hash

Attribute	Type	Comments
folio_number	string	Folio number
holding_pattern	string	Prevalent holding pattern in the folio. Possible values are - single
amc_code	string	Code to identify which is the AMC. Refer to AMC Codes mapping for actuals
schemes	array	List of schemes present in the folio

schemes hash

Attribute	Type	Comments
isin	string	ISIN number of the scheme
scheme_code	string	Scheme code
fund_category	string	Category of the scheme. Possible values are - growth, div_payout, div_reinvestment
investment_option	string	Investment option. Possible values are - debt, equity, liquid
nav	numeric	Value of the NAV
nav_on_date	string	Date on which the above NAV was applicable. Format is yyyy-mm-dd
available_units	numeric	Total units available in this scheme
redeemable_units	numeric	Total redeemable units available in this scheme
available_amount	numeric	Total amount available in this scheme
redeemable_amount	numeric	Total redeemable amount available in this scheme
invested_amount	numeric	Total amount that was invested into this scheme
gain_amount	numeric	Total amount that was either gained / lost. + determains a gain and - determines a loss
gain_percentage	numeric	Percentage of gain / loss. + determains a gain and - determines a loss

AMC Codes mapping

AMC Code	AMC Name
IF	360 One Mutual Fund
B	Aditya Birla Sun Life Mutual Fund
G	Bandhan Mutual Fund
D	Dsp Mutual Fund
FTI	Franklin Templeton Mutual Fund
H	Hdfc Mutual Fund
O	Hsbc Mutual Fund
P	Icici Prudential Mutual Fund
K	Kotak Mutual Fund
MM	Mahindra Manulife Mutual Fund
PLF	Navi Mutual Fund
PP	Ppfas Mutual Fund
L	Sbi Mutual Fund
SH	Shriram Mutual Fund
T	Tata Mutual Fund
UK	Union Mutual Fund
Y	Whiteoak Capital Mutual Fund
128	Axis Mutual Fund
178	Baroda Bnp Paribas Mutual Fund
116	Boi Axa Mutual Fund
189	Bajaj Finserv Mutual Fund
101	Canara Robeco Mutual Fund
118	Edelweiss Mutual Fund
125	Groww Mutual Fund
120	Invesco Mutual Fund
152	Iti Mutual Fund
105	Jm Financial Mutual Fund
102	Lic Mutual Fund
117	Mirae Asset Mutual Fund
127	Motilal Oswal Mutual Fund
RMF	Nippon India Mutual Fund
187	Nj Mutual Fund
129	Pgim India Mutual Fund
166	Quant Mutual Fund
123	Quantum Mutual Fund
188	Samco Mutual Fund
176	Sundaram Mutual Fund
104	Taurus Mutual Fund
185	Trust Mutual Fund
108	Uti Mutual Fund
HLS	Helios Mutual Fund
Z	Zerodha Mutual Fund

Create MF Investments Snapshot

curl -X POST "https://s.finprim.com/v2/mf_investments_snapshots"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{json_request}'

JSON request:

{
  "profile": "invp_904b5ba315514981bfbe4fb680ba8730",
  "phone_number": "phone_dd3c55f5c429462cad51fee7c37f81de"
}

JSON response:

{
  "object": "mf_investments_snapshot",
  "id": "mfis_fe9348c57a4a04eaca50deb684cb502e",
  "as_on": null,
  "profile": "invp_904b5ba315514981bfbe4fb680ba8730",
  "phone_number": "phone_dd3c55f5c429462cad51fee7c37f81de",
  "email_address": null,
  "status": "consent_required",
  "failure_code": null,
  "folios": [

  ],
  "source_ref_id": null,
  "consent_required_at": "2024-01-22T16:33:09.158+05:30",
  "submitted_at": null,
  "successful_at": null,
  "failed_at": null,
  "expired_at": null,
  "created_at": "2024-01-22T16:33:09.153+05:30",
  "updated_at": "2024-01-22T16:34:19.740+05:30"
}

The endpoint is used to create a MF Investments Snapshot request.

HTTP Request

POST /v2/mf_investments_snapshots

Request Parameters

Name	Mandatory	Type	Comments
profile	yes	string	Investor Profile ID
phone_number	conditional	string	ID of the phone_number on which investor consent should be collected on. Ensure this is tagged to the profile that is given and also ensure belongs_to = self Mandatory if email_address is not present. Cannot co-exist with email_address
email_address	conditional	string	ID of the email_address on which investor consent should be collected on. Ensure this is tagged to the profile that is given and also ensure belongs_to = self Mandatory if phone_number is not present. Cannot co-exist with phone_number
source_ref_id	no	string	An identifier that is unique across all types of MF Investments Snapshots. This is not generated by FP and is populated by API consumers for identification purposes (ideally an auto generated identifier / uuid to identify the MF Investments Snapshot in your application)

Update MF Investments Snapshot

curl -X PATCH "https://s.finprim.com/v2/mf_investments_snapshots"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{json_request}'

JSON request:

{
  "id": "mfis_fe9348c57a4a04eaca50deb684cb502e",
  "otp": "828713"
}

JSON response:

{
  "object": "mf_investments_snapshot",
  "id": "mfis_fe9348c57a4a04eaca50deb684cb502e",
  "as_on": null,
  "profile": "invp_904b5ba315514981bfbe4fb680ba8730",
  "phone_number": "phone_dd3c55f5c429462cad51fee7c37f81de",
  "email_address": null,
  "status": "submitted",
  "failure_code": null,
  "folios": [

  ],
  "source_ref_id": null,
  "consent_required_at": "2024-01-22T16:33:09.158+05:30",
  "submitted_at": "2024-01-22T16:35:03.208+05:30",
  "successful_at": null,
  "failed_at": null,
  "expired_at": null,
  "created_at": "2024-01-22T16:33:09.153+05:30",
  "updated_at": "2024-01-22T16:35:03.212+05:30"
}

The endpoint is used to collect the consent for an MF Investments Snapshot request.

HTTP Request

PATCH /v2/mf_investments_snapshots

Request Parameters

Name	Mandatory	Type	Comments
id	yes	string	ID of the mf_investments_snapshots
otp	yes	string	OTP as received on the phone number

Fetch MF Investments Snapshot

curl -X GET "https://s.finprim.com/v2/mf_investments_snapshots/mfis_fe9348c57a4a04eaca50deb684cb502e"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON response:

{
  "object": "mf_investments_snapshot",
  "id": "mfis_fe9348c57a4a04eaca50deb684cb502e",
  "as_on": "2024-01-22T16:34:19.739+05:30",
  "profile": "invp_904b5ba315514981bfbe4fb680ba8730",
  "phone_number": "phone_dd3c55f5c429462cad51fee7c37f81de",
  "email_address": null,
  "status": "successful",
  "failure_code": null,
  "folios": [
    {
      "folio_number": "21341231",
      "holding_pattern": "single",
      "amc_code": "hdfc",
      "schemes": [
        {
          "isin": "INF179K01LC5",
          "scheme_code": "LFIG",
          "fund_category": "equity",
          "investment_option": "growth",
          "nav": 12.2,
          "nav_on_date": "2023-11-09",
          "available_units": 1000,
          "redeemable_units": 1000,
          "available_amount": 12200,
          "redeemable_amount": 12200,
          "invested_amount": 13000,
          "gain_amount": -800,
          "gain_percentage": -6.12
        }
      ]
    }
  ],
  "source_ref_id": null,
  "consent_required_at": "2024-01-22T16:33:09.158+05:30",
  "submitted_at": "2024-01-22T16:33:19.467+05:30",
  "successful_at": "2024-01-22T16:34:19.739+05:30",
  "failed_at": null,
  "expired_at": null,
  "created_at": "2024-01-22T16:33:09.153+05:30",
  "updated_at": "2024-01-22T16:34:19.740+05:30"
}

The endpoint is used to fetch the details of an MF Investments Snapshot request.

HTTP Request

GET /v2/mf_investments_snapshots/:id

Query Parameters

Name	Mandatory	Type	Comments
id	yes	string	ID of the mf_investments_snapshot object

List all MF Investments Snapshots

curl -X GET "https://s.finprim.com/v2/mf_investments_snapshots?profile=invp_904b5ba315514981bfbe4fb680ba8730"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON response:

{
  "object": "list",
  "data": [
    {
      "object": "mf_investments_snapshot",
      "id": "mfis_fe9348c57a4a04eaca50deb684cb502e",
      "as_on": "2024-01-22T16:34:19.739+05:30",
      "profile": "invp_904b5ba315514981bfbe4fb680ba8730",
      "phone_number": "phone_dd3c55f5c429462cad51fee7c37f81de",
      "email_address": null,
      "status": "successful",
      "failure_code": null,
      "folios": [
        {
          "folio_number": "21341231",
          "holding_pattern": "single",
          "amc_code": "hdfc",
          "schemes": [
            {
              "isin": "INF179K01LC5",
              "scheme_code": "LFIG",
              "fund_category": "equity",
              "investment_option": "growth",
              "nav": 12.2,
              "nav_on_date": "2023-11-09",
              "available_units": 1000,
              "redeemable_units": 1000,
              "available_amount": 12200,
              "redeemable_amount": 12200,
              "invested_amount": 13000,
              "gain_amount": -800,
              "gain_percentage": -6.12
            }
          ]
        }
      ],
      "source_ref_id": null,
      "consent_required_at": "2024-01-22T16:33:09.158+05:30",
      "submitted_at": "2024-01-22T16:33:19.467+05:30",
      "successful_at": "2024-01-22T16:34:19.739+05:30",
      "failed_at": null,
      "expired_at": null,
      "created_at": "2024-01-22T16:33:09.153+05:30",
      "updated_at": "2024-01-22T16:34:19.740+05:30"
    }
  ]
}

The endpoint is used to fetch the details of all MF Investments Snapshot requests against a profile.

HTTP Request

GET /v2/mf_investments_snapshots

Query Parameters

Name	Mandatory	Type	Comments
profile	yes	string	ID of the investor_profile

Simulation

All simulation apis are available only in the sandbox environment

Order Simulation

curl "https://s.finprim.com/api/oms/simulate/orders/{amc_order_id} "
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWTTOKEN"
  -d '{json_request}'

JSON request:

{
  "status": "SUBMITTED"
}

JSON response:

{
  "message": "order updated successfully"
}

This endpoint is used to simulate order statuses which are not available through public API. All simulation endpoints are only available in staging server.

HTTP Request

POST https://s.finprim.com/api/oms/simulate/orders/{amc_order_id}

Simulate Order Request Params

Name	Mandatory	Type	Comments
amc_order_id	yes	integer	valid order id . You can use any of the id from the order object(old_id or id)
status	yes	string	PAYMENT_CONFIRMED, SUBMITTED, SUCCESSFUL, FAILED and REVERSED are only allowed

SIP Simulation ^(Deprecated)

curl "https://s.finprim.com/api/oms/simulate/sips/{sip_id}/generate_next_installment"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWTTOKEN"

JSON response:

{
  "message": "installment with order id 421 created. please use order simulation api for further simulation"
}

This endpoint is used to generate order for the given sip id, the order date will be of next installment.

All simulation endpoints are only available in staging server.

Example: If you have created sip with sip day 1 and created in march, first time it will create order for april , second time it will create order for may.

HTTP Request

POST https://s.finprim.com/api/oms/simulate/sips/{sip_id}/generate_next_installment

Simulate SIP Request Params

Name	Mandatory	Type	Comments
sip_id	yes	integer	valid sip id

Payment Simulation

curl "https://s.finprim.com/api/pg/simulate/payments/{payment_id} "
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWTTOKEN"
  -d '{json_request}'

JSON request:

{
  "status": "SUBMITTED"
}

JSON response:

{
  "message": "payment updated to status SUBMITTED"
}

This endpoint is used to simulate payment statuses which are not available through public API.

All simulation endpoints are only available in staging server.

Note : To mark payment as APPROVED or SUCCESS mandate status must be APPROVED.

HTTP Request

POST https://s.finprim.com/api/pg/simulate/payments/{payment_id}

Simulate Payment Request Params

Name	Mandatory	Type	Comments
payment_id	yes	integer	valid payment id
status	yes	string	SUBMITTED, APPROVED, REJECTED, INITIATED, PENDING, TIMEDOUT, SUCCESS and FAILED are only allowed

Mandate Simulation

curl "https://s.finprim.com/api/pg/simulate/mandates/{mandate_id}"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWTTOKEN"
  -d '{json_request}'

JSON request:

{
  "status": "SUBMITTED"
}

JSON response:

{
  "message": "mandate updated to status SUBMITTED"
}

This endpoint is used to simulate mandate statuses which are not available through public API.

All simulation endpoints are only available in staging server.

HTTP Request

POST https://s.finprim.com/api/pg/simulate/mandates/{mandate_id}

Simulate Mandate Request Params

Name	Mandatory	Type	Comments
mandate_id	yes	integer	valid mandate id
status	yes	string	CREATED, SUBMITTED, APPROVED, RECEIVED and REJECTED are only allowed

Transaction Simulation (^{Early Access})

To test the functionality of reports, users need to generate dummy transactions similar to the ones generated from RTA post-order processed reports. File operation apis can be used to simulate these transactions in sandbox. To ease the process, we accept a list of transactions in a simplified csv file format described below. A sample copy of the csv file is attached here.

Simulation file format

Field Name	Type	Description
folio_number	string	Folio Number. This can be a new or existing one.
isin	string	ISIN of the scheme. Must be a valid ISIN in sandbox.
reference_no	string	Reference number of the transaction. If the combination of the reference_no and folio_number of a transaction already exists, the system will update the existing transaction, else it will create a new transaction.
license_code	string	Distributor/Advisor license code
amount	decimal	Trade amount
units	decimal	Units traded
bucket	string	Type of transaction. Supported values are PURCHASE, REDEMPTION, TRANSFER_IN, TRANSFER_OUT, SWITCH_IN, SWITCH_OUT, DIVIDEND_REINVESTMENT, DIVIDEND_PAYOUT
trade_date	string	Date (yyyy-MM-dd) at which transaction was processed
mf_investment_account	string	V2 investment account id

Transactions

Representation of transactions populated and processed from the RTA reverse feeds which have been uploaded. More information on transaction processing and data points can be found on Technical documentation

Endpoints:

GET /transactions

Transaction Object

{
  "object": "transaction",
  "folio_number": "1562150537200",
  "isin": "INF760K01100",
  "type": "redemption",
  "amount": 2250,
  "units": 150,
  "traded_on": "2019-01-07",
  "traded_at": 15,
  "order": null,
  "corporate_action": null,
  "related_transaction_id": null,
  "rta_order_reference": "1562150537207",
  "rta_product_code": "101ETGP",
  "rta_investment_option": "GROWTH",
  "rta_scheme_name": "Test Canara Robeco Equity Tax Saver Fund - Regular Growth",
  "sources": [
    {
      "days_held": 7,
      "units": 100,
      "purchased_on": "2019-01-01",
      "purchased_at": 10,
      "gain": 500
    },
    {
      "days_held": 6,
      "units": 50,
      "purchased_on": "2019-01-02",
      "purchased_at": 12,
      "gain": 150
    }
  ]
}

Attribute	Type	Comments
object	string	Value is transaction. String representing the object type. Objects of the same type share the same value.
folio_number	string	Folio number
isin	string	ISIN of the scheme. This can be used to fetch more details about the scheme from Fund schemes end point.
type	string	Transaction type : purchase, redemption, switch_in, switch_out, transfer_in, transfer_out, dividend_payout, dividend_reinvestment, bonus
amount	decimal	Transaction amount
units	decimal	Number of units
traded_on	string	Date on which this transaction happened (yyyy-MM-dd)
traded_at	decimal	NAV at which the trade happened
order	string	This will be null if the order has not been processed through the fintech primitives platform. Else, the value will be the order id.
corporate_action	string	This field will specify the corporate action due to which the transaction happened. If the transaction was user initiated, the value for this attribute will be null. Supported Corporate actions : scheme_merger
related_transaction_id	string	If a transaction is related to another transaction, the id of such transaction will be present here. For example, for a purchase rejection, a related transaction would be the original purchase transaction.
rta_order_reference	string	Order reference number as obtained from the RTA reverse feed.
rta_product_code	string	Scheme product code as obtained from the RTA reverse feed.
rta_investment_option	string	Investment option as obtained from the RTA reverse feed.
rta_scheme_name	string	Scheme name as obtained from the RTA reverse feed.
sources	List	This will be populated in cases of redemption,switch_out or transfer_out transaction types. This attribute will give the information of the purchases from which the redeemed units were sourced from. We follow FIFO logic to populate the source. For example:Let T1 = Purchase of 100 units at NAV=10Rs. T2 = Purchase of 100 units at NAV=15Rs. T3 = Redemption of 150 units at NAV=20Rs. If T3 is concerned, out of the 150 units that were sold, 100 units came from T1 and 50 units came from T2. So, the source of T3 are T1 and T2.

Sources

Attribute	Type	Comments
days_held	Integer	Number of days for which the units were held before being redeemed
units	decimal	Number of units
purchased_on	string	Date of purchase of units (yyyy-MM-dd)
purchased_at	decimal	NAV per unit at which the units were purchased.
gain	decimal	The resulting Gain/Loss because of the redemption. The value will be positive, if there is a gain. If there is a loss, the value will be negative.

List all transactions

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

JSON Response

{
  "object": "list",
  "data": [
    {
      "object": "transaction",
      "folio_number": "1562150537200",
      "isin": "INF760K01100",
      "type": "redemption",
      "amount": 2250,
      "units": 150,
      "traded_on": "2019-01-07",
      "traded_at": 15,
      "order": null,
      "corporate_action": null,
      "related_transaction_id": null,
      "rta_order_reference": "1562150537207",
      "rta_product_code": "101ETGP",
      "rta_investment_option": "GROWTH",
      "rta_scheme_name": "Test Canara Robeco Equity Tax Saver Fund - Regular Growth",
      "sources": [
        {
          "days_held": 7,
          "units": 100,
          "purchased_on": "2019-01-01",
          "purchased_at": 10,
          "gain": 500
        },
        {
          "days_held": 6,
          "units": 50,
          "purchased_on": "2019-01-02",
          "purchased_at": 12,
          "gain": 150
        }
      ]
    },
    {
      "object": "transaction",
      "folio_number": "1562150537200",
      "isin": "INF760K01100",
      "type": "purchase",
      "amount": 1200,
      "units": 100,
      "traded_on": "2019-01-02",
      "traded_at": 12,
      "order": null,
      "corporate_action": null,
      "related_transaction_id": null,
      "rta_order_reference": "1562150537202",
      "rta_product_code": "101ETGP",
      "rta_investment_option": "GROWTH",
      "rta_scheme_name": "Test Canara Robeco Equity Tax Saver Fund - Regular Growth",
      "sources": [

      ]
    },
    {
      "object": "transaction",
      "folio_number": "1562150537200",
      "isin": "INF760K01100",
      "type": "purchase",
      "amount": 1000,
      "units": 100,
      "traded_on": "2019-01-01",
      "traded_at": 10,
      "order": null,
      "corporate_action": null,
      "related_transaction_id": null,
      "rta_order_reference": "1562150537201",
      "rta_product_code": "101ETGP",
      "rta_investment_option": "GROWTH",
      "rta_scheme_name": "Test Canara Robeco Equity Tax Saver Fund - Regular Growth",
      "sources": [

      ]
    }
  ]
}

GET /transactions

Returns a list of transactions associated with the given folio(s). The transactions are returned, and sorted by transaction date, with the most recent transactions appearing first.

ARGUMENTS

Name	Mandatory	Type	Comments
folios	yes	list	multiple folio_numbers separated by a comma
types	no	list	valid transaction types separated by a comma
from	no	string	from date in yyyy-MM-dd
to	no	string	to date in yyyy-MM-dd

Note:

Following table describes the behavior of API depending on the values of from and to date.

from	to	Behavior
Null	Null	All transactions of the given folio(s) for the current financial year are returned.
Null	Not Null	Transactions starting from an year before to date till to date are returned.
Not Null	Null	All transactions starting from from date till from+1 year are displayed. Note : If from+1 year is greater than current date transactions from from to current date are displayed.
Not Null	Not Null	All transactions in the date range from to to date are displayed. Note : If the date range specified by from and to is greater than an year, it will result in an error.

RESPONSE

A list of transactions sorted by transaction date, with the most recent transactions appearing first.

File Operations

Represents a file operation. File operations are those operations which are performed on a file. A typical file operation workflow starts with a file being uploaded using Create File api. Once a file is uploaded a file operation can be created for this file using the file id obtained after creating a file.

At present transaction_processing file operation type is supported. More Info

Endpoints:

POST /file_operations GET /file_operations/:id

File Operation Object

{
  "object": "file_operation",
  "id": "53307e81-f417-4428-93ad-a855c7c0d962",
  "file": "bf8253b0-c302-4715-974b-87a8d7a9efc3",
  "type": "transaction_processing",
  "status": "processed",
  "processed": 15,
  "failed": 3,
  "succeeded": 12
}

Attribute	Type	Comments
object	string	Value is file_operation. String representing the object type. Objects of the same type share the same value.
id	string	Unique identifier for the file_operation object created
file	string	File id created using create file api.
type	string	Processing will differ based on the type of the file operation. Supported types : transaction_processing transaction_simulation(sandbox only) (early access)
status	string	Status of the file_operation created. Possible status: pending, processed, failed
processed	integer	Number of processed records inside the file object.
failed	integer	Number of records for which processing failed inside the file object.
succeeded	integer	Number of records successfully processed.

Create a file operation

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

JSON Request

{
  "type": "transaction_processing",
  "file": "bf8253b0-c302-4715-974b-87a8d7a9efc3"
}

JSON Response

{
  "object": "file_operation",
  "id": "53307e81-f417-4428-93ad-a855c7c0d962",
  "file": "bf8253b0-c302-4715-974b-87a8d7a9efc3",
  "type": "transaction_processing",
  "status": "pending",
  "processed": null,
  "failed": null,
  "succeeded": null
}

POST /file_operations

Returns a file_operation object holding details of the file operation along with the processed information. Initially once the request to file_operation is submitted, the status will be pending. Eventually the file will be processed in the background. Use the GET api to get further details.

Attributes

Attribute	Mandatory	Type	Comments
type	yes	string	Supported types : transaction_processing transaction_simulation(sandbox only) (early access)
file	yes	string	File id obtained using the Create File api.

RESPONSE

Return the file_operation id along with other data in the object defined.

Fetch a file operation

curl -X GET "https://s.finprim.com/file_operations/53307e81-f417-4428-93ad-a855c7c0d962"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "file_operation",
  "id": "53307e81-f417-4428-93ad-a855c7c0d962",
  "file": "bf8253b0-c302-4715-974b-87a8d7a9efc3",
  "type": "transaction_processing",
  "status": "processed",
  "processed": 15,
  "failed": 3,
  "succeeded": 12
}

GET /file_operations/:id

Returns a file_operation object holding details of the file operation along with the processed information.

ARGUMENTS

Name	Mandatory	Type	Comments
id	yes	string	file_operation id

RESPONSE

Single file_operation object holding details of the status of the file_operation along with details of records processed.

Events

Event object lets you understand which events have occured on other objects and get an insight into their lifecycle.

Endpoints:

GET /v2/events
GET /v2/events/:id

Note: The following apis are accessible only via auth token generated using /v2/auth apis

Event Object

Events give you information on what events have occured on objects, along with a snapshot of the that object at that point of time.

{
  "id": "evt_aa8e8431594c4223a701ed09773ebb5c",
  "object": "event",
  "type": "kyc_request.esign_required",
  "data": {
    "object": {
      "id": "kycr_0c6f8d6a43ba402a9f87386c11fc3899",
      "status": "esign_required"
    },
    "previous_attributes": null
  },
  "time": "2023-02-16T05:37:22.123+0000"
}

Event Object Attributes

Attribute	Type	Comments
object	string	Value is event. String representing the object type. Objects of the same type share the same value
id	string	Unique identifier of the event object
type	string	String which identifies which type of event has occured
data	hash	Details of the object on which event has occured
time	string	ISO String Format DateTime when event has occured

Event Object Type

Object	Types
kyc_request	kyc_request.esign_required, kyc_request.submitted, kyc_request.successful, kyc_request.rejected, kyc_request.expired
mf_purchase	mf_purchase.created, mf_purchase.confirmed, mf_purchase.submitted, mf_purchase.successful, mf_purchase.failed, mf_purchase.cancelled, mf_purchase.reversed
mf_redemption	mf_redemption.created, mf_redemption.confirmed, mf_redemption.submitted, mf_redemption.successful, mf_redemption.failed, mf_redemption.cancelled, mf_redemption.reversed
mf_switch	mf_switch.created, mf_switch.confirmed, mf_switch.submitted, mf_switch.successful, mf_switch.failed, mf_switch.cancelled, mf_switch.reversed
mf_purchase_plan	mf_purchase_plan.created,mf_purchase_plan.activated,mf_purchase_plan.cancelled,mf_purchase_plan.failed,mf_purchase_plan.completed
mf_redemption_plan	mf_redemption_plan.created,mf_redemption_plan.activated,mf_redemption_plan.cancelled,mf_redemption_plan.failed,mf_redemption_plan.completed
mf_switch_plan	mf_switch_plan.created,mf_switch_plan.activated,mf_switch_plan.cancelled,mf_switch_plan.failed,mf_switch_plan.completed
mandate	mandate.created, mandate.received, mandate.submitted, mandate.approved, mandate.rejected, mandate.cancelled
payment	payment.pending,payment.success, payment.failed, payment.submitted, payment.initiated, payment.approved, payment.rejected

Event Data Hash

This hash will contain the details the object

Name	Type	Remarks
object	hash	The structure of this object is same as the respective object structure.
previous_attributes	hash	This is optional attribute, and it might be null. It contains the list of attributes whose values got changed and their previous values. This is available for events with type <object>.updated

Fetch an event

curl -X GET "https://s.finprim.com/v2/events/evt_b01632991bd9411c98709f1d573ee4f2"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "id": "evt_aa8e8431594c4223a701ed09773ebb5c",
  "object": "event",
  "type": "kyc_request.esign_required",
  "data": {
    "object": {
      "id": "kycr_0c6f8d6a43ba402a9f87386c11fc3899",
      "status": "esign_required"
    },
    "previous_attributes": null
  },
  "time": "2023-02-16T05:37:22.123+0000"
}

GET /v2/events/:id

Returns a event object holding details of the event

ARGUMENTS

Name	Mandatory	Type	Comments
id	yes	string	ID of an event

RESPONSE

Single event object

(The example response contains event of kyc_request object, though in actual response you will get the complete object of kyc_request, we have excluded most of the kyc_request object attributes for sake of brevity)

List all Events

curl -X GET "https://s.finprim.com/v2/events"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "list",
  "data": [
    {
      "id": "evt_b01632991bd9411c98709f1d573ee4f2",
      "object": "event",
      "type": "kyc_request.esign_required",
      "data": {
        "object": {
          "id": "kycr_fb5d9ba920bd4adda7f4ab0cd2583c18",
          "status": "esign_required"
        },
        "previous_attributes": null
      },
      "time": "2023-02-15T14:21:27.455+0000"
    },
    {
      "id": "evt_aa8e8431594c4223a701ed09773ebb5c",
      "object": "event",
      "type": "kyc_request.esign_required",
      "data": {
        "object": {
          "id": "kycr_0c6f8d6a43ba402a9f87386c11fc3899",
          "status": "esign_required"
        },
        "previous_attributes": null
      },
      "time": "2023-02-16T05:37:22.123+0000"
    }
  ]
}

GET /v2/events

This API can be used to fetch all the events.

Query parameters

Name	Mandatory	Type	Comments
type	no	string	Type of the event. Valid values: kyc_request.pending, kyc_request.esign_required, kyc_request.submitted, kyc_request.successful, kyc_request.rejected, kyc_request.expired mf_purchase.created, mf_purchase.confirmed, mf_purchase.submitted, mf_purchase.successful, mf_purchase.failed, mf_purchase.cancelled, mf_purchase.reversed mf_redemption.created, mf_redemption.confirmed, mf_redemption.submitted, mf_redemption.successful, mf_redemption.failed, mf_redemption.cancelled, mf_redemption.reversed mf_switch.created, mf_switch.confirmed, mf_switch.submitted, mf_switch.successful, mf_switch.failed, mf_switch.cancelled, mf_switch.reversed mf_purchase_plan.created,mf_purchase_plan.activated,mf_purchase_plan.cancelled,mf_purchase_plan.failed,mf_purchase_plan.completed mf_redemption_plan.created,mf_redemption_plan.activated,mf_redemption_plan.cancelled,mf_redemption_plan.failed,mf_redemption_plan.completed mf_switch_plan.created,mf_switch_plan.activated,mf_switch_plan.cancelled,mf_switch_plan.failed,mf_switch_plan.completed mandate.created, mandate.received, mandate.submitted, mandate.approved, mandate.rejected, mandate.cancelled payment.pending,payment.success, payment.failed, payment.submitted, payment.initiated, payment.approved, payment.rejected

RESPONSE

List of event objects

Note: The number of objects returned is limited to 100, and they are sorted by time in descending order

(The example response contains event of kyc_request object, though in actual response you will get the complete object of kyc_request, we have excluded most of the kyc_request object attributes for sake of brevity)

Webhook Notifications

Webhook Notification Object enables you to create a webhook notification for the events. You can subscribe to an event of an object according to your requirements. Check out the available FP events

Endpoints:

POST /v2/notification_webhooks
GET /v2/notification_webhooks
GET /v2/notification_webhooks/:id
PUT /v2/notification_webhooks/:id

Note: The following apis are accessible only via auth token generated using /v2/auth apis

Webhook Notification Object

Webhook Notification object will give you information on which URL is configured to receive a subscribed event. You can enable/disable a webhook notification.

{
  "object": "notification_webhook",
  "id": "ntwh_1ba0cef477784cc98385a80a6fc862de",
  "event": "kyc_request.expired",
  "url": "https://webhook.site/04c978f3-ecc7-4a17-add2-dafc41b0e039",
  "status": "enabled"
}

Webhook Notification object attributes

Attribute	Type	Comments
object	string	Value is notification_webhook. String representing the object type. Objects of the same type share the same value
id	string	Unique identifier of the notification_webhook object
event	string	String which identifies which type of event has occured. Valid values: Refer to Event Object-> "type" for valid values
url	string	A valid HTTP url where the event object would be posted
status	string	String which identified if webhook is enabled or not. Valid values: enabled, disabled

Create a notification webhook

curl -X POST "https://s.finprim.com/v2/notification_webhooks"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{json_request}'

JSON request:

{
  "status": "enabled",
  "event": "kyc_request.expired",
  "url": "https://webhook.site/04c978f3-ecc7-4a17-add2-dafc41b0e039"
}

JSON response:

{
  "object": "notification_webhook",
  "id": "ntwh_1ba0cef477784cc98385a80a6fc862de",
  "event": "kyc_request.expired",
  "url": "https://webhook.site/04c978f3-ecc7-4a17-add2-dafc41b0e039",
  "status": "enabled"
}

The endpoint is used to create webhook notification.

HTTP Request

POST /v2/notification_webhooks

Query Parameters

Name	Mandatory	Type	Comments
url	yes	string	Valid HTTP url to which we can POST
event	yes	string	Valid values: Refer to Event Object-> "type" for valid values
status	yes	string	Valid values: enabled, disabled

List all Notification Webhooks

curl -X GET "https://s.finprim.com/v2/notification_webhooks"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "list",
  "data": [
    {
      "object": "notification_webhook",
      "id": "ntwh_1ba0cef477784cc98385a80a6fc862de",
      "event": "kyc_request.expired",
      "url": "https://webhook.site/04c978f3-ecc7-4a17-add2-dafc41b0e039",
      "status": "enabled"
    },
    {
      "object": "notification_webhook",
      "id": "ntwh_788b70e440354ea48ffb7385f3f774c2",
      "event": "kyc_request.submitted",
      "url": "https://webhook.site/04c978f3-ecc7-4a17-add2-dafc41b0e039",
      "status": "enabled"
    }
  ]
}

GET /v2/notification_webhooks

This API can be used to fetch all the notification webhooks configured for your account.

Query parameters

Name	Mandatory	Type	Comments
event	no	string	Type of the event. Refer to Event Object-> "type" for valid values`

RESPONSE

List of notification_webhook objects

Fetch a notification webhook

curl -X GET "https://s.finprim.com/v2/notification_webhooks/ntwh_1ba0cef477784cc98385a80a6fc862de"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "object": "notification_webhook",
  "id": "ntwh_1ba0cef477784cc98385a80a6fc862de",
  "event": "kyc_request.expired",
  "url": "https://webhook.site/04c978f3-ecc7-4a17-add2-dafc41b0e039",
  "status": "enabled"
}

GET v2/notification_webhooks/:id

Returns a notification_webhook object

ARGUMENTS

Name	Mandatory	Type	Comments
id	yes	string	ID of an notification_webhook

RESPONSE

Single notification_webhook object

Update a notification webhook

curl -X PUT "https://s.finprim.com/v2/notification_webhooks/ntwh_1ba0cef477784cc98385a80a6fc862de"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{json_request}'

JSON request:

{
  "status": "enabled",
  "url": "https://webhook.site/04c978f3-ecc7-4a17-add2-dafc41b0e039"
}

JSON response:

{
  "object": "notification_webhook",
  "id": "ntwh_1ba0cef477784cc98385a80a6fc862de",
  "event": "kyc_request.expired",
  "url": "https://webhook.site/04c978f3-ecc7-4a17-add2-dafc41b0e039",
  "status": "enabled"
}

The endpoint is used to update webhook notification.

HTTP Request

PUT /v2/notification_webhooks/:id

Query Parameters

Name	Mandatory	Type	Comments
url	yes	string	Valid HTTP url to which we can POST
status	yes	string	Valid values: enabled, disabled

Errors

Validation Error:

{
  "error": {
    "status": 400,
    "code": null,
    "message": "some description message",
    "errors": [
      {
        "field": "name",
        "message": "validation / error message"
      }
    ]
  }
}

Json Parse Error:

{
  "error": {
    "status": 400,
    "code": null,
    "message": "JSON parse error",
    "errors": null
  }
}

Errors are returned using standard HTTP status codes, as well as a JSON error response object.

Attribute	Type	Comments
status	integer	same as HTTP status code
code	string	this indicates what error occured
message	string	descriptive message on the error
errors	array of objects	list of errors on each field, if applicable

HTTP status codes

The following table lists and describes the HTTP status codes that can be returned.

Status Code	Status Message	Description
400	Bad Request	Cannot process the request because it is malformed or incorrect.
401	Unauthorized	Required authentication information is either missing or not valid for the resource.
403	Forbidden	Access is denied to the requested resource. The user might not have enough permission.
404	Not Found	The requested resource does not exist.
405	Method Not Allowed	The target resource doesnot support this method.
500	Internal Server Error	There was an internal server error while processing the request.
503	Service Unavailable	The service is temporarily unavailable for maintenance or is overloaded. You may repeat the request after a delay.

Rate Limits

To ensure system stability and mitigate excessive incoming traffic, the FP API employs a rate limiter that restricts the number of requests it can handle within a given second. Users who submit multiple requests in rapid succession might receive error responses, typically indicated by the status code 429.

• General API Rate Limits: In the production mode, most FP APIs allow up to 100 read operations and 100 write operations per second. In the sandbox mode, the limit is set at 25 operations per second for both read and write operations.

• Files API Rate Limits: For the Files API, FP allows a maximum of 20 read operations and 20 write operations per second, separately for both production and sandbox modes.

• List/Search API's Rate Limits: The List/Search APIs maintain a limit of 20 read operations per second for all list/search endpoints, applicable in both production and sandbox modes.

We may adjust these limits as needed to prevent misuse or accommodate high-traffic applications. If you require an increase in the rate limit, please do not hesitate to contact our support team at fpsupport@cybrilla.com. For substantial rate limit increases, we recommend reaching out to us at least 6 weeks before the anticipated requirement.

Investors ^(Deprecated)

The investor object holds the personal, demographic and financial information about your customer. The API allows you to create, update an investor and also list investors.

Endpoints:

POST /api/onb/investors
POST /api/onb/investors/:id
GET /api/onb/investors/:id
GET /api/onb/investors
GET /api/onb/investors/search

Create an investor

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

JSON Request

{
  "display_name": "tony",
  "perm_addr_is_corres_addr": true,
  "ip_address": "192.168.29.100",
  "bank_accounts": [
    {
      "account_holder_name": "tony",
      "number": "00000001234455",
      "primary_account": true,
      "type": "SAVINGS",
      "ifsc_code": "ICIC0000611",
      "cancelled_cheque": "3867a9c6-8a7c-4605-a31d-98367e8972b4"
    }
  ],
  "contact_detail": {
    "email": "mfp@cybrilla.com",
    "isd_code": "91",
    "mobile": "9008580644"
  },
  "fatca_detail": {
    "country_of_birth_ansi_code": "IN",
    "no_other_tax_residences": true,
    "source_of_wealth": "business",
    "gross_annual_income": 100000
  },
  "nomination": {
    "skip_nomination": false,
    "nominee1": {
      "allocation_percentage": 100,
      "date_of_birth": "1990-10-10",
      "name": "nandam",
      "relationship": "spouse"
    }
  },
  "kyc_identity_detail": {
    "pan_number": "AFZPN3001P",
    "country_of_citizenship_ansi_code": "IN",
    "date_of_birth": "1980-10-10",
    "father_or_spouse_name": "tonys wife",
    "kyc_relation": "spouse",
    "gender": "female",
    "marital_status": "single",
    "name": "tony Soprano ms",
    "occupation": "BUSINESS",
    "residential_status": "resident_individual",
    "pep_exposed": false,
    "pep_related": false,
    "signature": "beed6916-cec6-4f4f-bcc8-ed4d93b55660"
  },
  "correspondence_address": {
    "line1": "1082 harlur road",
    "pincode": "560102"
  }
}

JSON Reponse

{
  "id": 1,
  "display_name": "tony",
  "perm_addr_is_corres_addr": true,
  "ip_address": "192.168.1.1",
  "created_at": "2018-05-22T10:14:19.072Z",
  "updated_at": "2018-05-22T10:14:19.072Z",
  "meta": null,
  "nomination": {
    "skip_nomination": false,
    "nominee1": {
      "date_of_birth": "1990-10-10",
      "name": "Tony Stark",
      "pan": null,
      "relationship": "nandam",
      "guardian_name": null,
      "guardian_pan": null,
      "guardian_relationship": null,
      "allocation_percentage": 100
    },
    "nominee2": null,
    "nominee3": null
  },
  "contact_detail": {
    "email": "mfp@cybrilla.com",
    "isd_code": 91,
    "mobile": "9008580644",
    "office_telephone_no": null,
    "residence_telephone_no": null
  },
  "fatca_detail": {
    "country_of_birth_ansi_code": "IN",
    "source_of_wealth": "BUSINESS",
    "first_trc_ansi_code": null,
    "first_trc_taxid_type": null,
    "first_trc_taxid_number": null,
    "second_trc_ansi_code": null,
    "second_trc_taxid_type": null,
    "second_trc_taxid_number": null,
    "third_trc_ansi_code": null,
    "third_trc_taxid_type": null,
    "third_trc_taxid_number": null,
    "gross_annual_income": 1000000,
    "no_other_tax_residences": true
  },
  "kyc_identity_detail": {
    "name": "tony Soprano ms",
    "father_or_spouse_name": "tonys wife",
    "mothers_name": null,
    "ckyc_number": null,
    "kyc_relation": "spouse",
    "date_of_birth": "1980-10-10",
    "marital_status": "MARRIED",
    "pan_number": "AFZPN3001P",
    "gender": "female",
    "occupation": "BUSINESS",
    "residential_status": "RESIDENT_INDIVIDUAL",
    "country_of_citizenship_ansi_code": "IN",
    "pan_exempt": false,
    "pep_exposed": false,
    "pep_related": false,
    "guardian_relationship": null,
    "guardian_name": null,
    "guardian_date_of_birth": null,
    "guardian_pan_number": null,
    "signature": "beed6916-cec6-4f4f-bcc8-ed4d93b55660"
  },
  "bank_accounts": [
    {
      "id": 1,
      "account_holder_name": "tony",
      "type": "SAVINGS",
      "primary_account": true,
      "number": "00000001214415",
      "created_at": "2019-05-22T10:14:19.082Z",
      "updated_at": "2019-05-22T10:14:19.082Z",
      "branch": {
        "ifsc_code": "ICIC0000611",
        "micr_code": null,
        "branch_name": "GUDIVADA",
        "bank_name": "ICICI BANK LIMITED",
        "branch_address": "ICICI BANK LTD , D NO11218, NENIPLAZA, ELURU ROAD, GUDIVADA 521301",
        "contact": null,
        "city": "GUDIVADA",
        "district": "KRISHNA",
        "state": "ANDHRA PRADESH"
      },
      "cancelled_cheque": "3867a9c6-8a7c-4605-a31d-98367e8972b4"
    }
  ],
  "correspondence_address": {
    "line1": "1082 road",
    "line2": null,
    "line3": null,
    "type": "CORRESPONDENCE",
    "zipcode": "560112",
    "city": "Bengaluru",
    "state": "KARNATAKA",
    "country_ansi_code": "IN"
  },
  "_links": [
    {
      "href": "https://s.finprim.com/onb/investors/229",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://s.finprim.com/onb/investors/229",
      "rel": "update",
      "method": "POST"
    }
  ]
}

POST /api/onb/investors

Create a new investor so you can allow him to make investments and see reports. The information from the investor object is used while creating a new folio.

Parameters

Name	Mandatory	type	Comments
display_name	no	string
perm_addr_is_corres_addr	yes	boolean	flag to determine if permanent_address is same as correspondence_address
bank_accounts	yes	array of objects	this is a list of bank accounts that can be added for the investor. You can mark only one account as Primary. For more details please refer bank account parameters.
contact_detail	yes	object	contact details of the investor
fatca_detail	yes	object	FATCA details of the investor
nomination	yes	object	nominee details of the investor
kyc_identity_detail	yes	object	identity details of the investor for KYC and Registration with AMCs
correspondence_address	yes	object
permanent_address	no	object	mandatory if perm_addr_is_corres_addr is false
overseas_address	no	object	mandatory for NRI investor
ip_address	no	string	192.099.10.10

BankAccount params

Name	Mandatory	type	Comments
account_holder_name	yes	string	name of the bank account holder
number	yes	string	bank account number
primary_account	yes	boolean	whether the bank_account is primary or not
type	yes	enum	select one from - "SAVINGS", "CURRENT", "NRE", "NRO"
ifsc_code	yes		select one of the ifsc code from ifsc codes api
cancelled_cheque	no	string	File Id of uploaded cancelled cheque image using files api. Mandatory to create Investment Account when order gateway provider is BSE and residential_status=NON_RESIDENT_INDIVIDUAL

ContactDetail params

Name	Mandatory	type	Comments
email	yes	string	email ID of the investor to be reported to AMC
isd_code	yes	integer	ISD code of the mobile / telephone number
mobile	yes	string	mobile number of the investor
office_telephone_no	no	string
residence_telephone_no	no	string

FatcaDetail params

Name	Mandatory	type	Comments
country_of_birth_ansi_code	yes	string	ANSI code of the country, eg ANSI code of India is IN
no_other_tax_residences	yes	boolean	flag to determine if the investor is a tax-resident in countries other than India. If set to false, atleast one tax residency details are mandatory.
source_of_wealth	yes	enum	values permitted: SALARY, BUSINESS, GIFT, ANCESTRAL_PROPERTY, RENTAL_INCOME, PRIZE_MONEY, ROYALTY, OTHERS
gross_annual_income	yes	integer	should be greater than zero
first_trc_ansi_code	no	string	ANSI code of the tax residency country. Mandatory if no_other_tax_residences is false
first_trc_taxid_type	no	string	type of tax identification (SSN Card etc..). Mandatory if first_trc_ansi_code is given
first_trc_taxid_number	no	string	number of the tax identification (SSN etc..). Mandatory if first_trc_ansi_code is given
second_trc_ansi_code	no	string	ansi code of the tax residency country
second_trc_taxid_type	no	string	type of tax identification (SSN Card etc..). Mandatory if second_trc_ansi_code is given
second_trc_taxid_number	no	string	number of the tax identification (SSN etc..). Mandatory if second_trc_ansi_code is given
third_trc_ansi_code	no	string	ansi code of the tax residency country
third_trc_taxid_type	no	string	type of tax identification (SSN Card etc..). Mandatory if third_trc_ansi_code is given
third_trc_taxid_number	no	string	number of the tax identification (SSN etc..). Mandatory if third_trc_ansi_code is given

Nomination params

Name	Mandatory	type	Comments
skip_nomination	yes	boolean	Flag to determine if the investor wants to declare nominee
nominee1	no	object	mandatory if skip_nomination is false
nominee2	no	object	mandatory if allocation percentage of nominee1 is less than 100%
nominee3	no	object	mandatory if total allocation percentage of nominee1 & nominee2 is less than 100%

Nominee params

Name	Mandatory	type	Comments
name	yes	string	name of the nominee
pan	no	string	PAN of the nominee
date_of_birth	yes	string	date formatted as "YYYY-MM-DD"
relationship	yes	string	can be any relationship like (spouse/father/mother etc..)
allocation_percentage	yes	integer	should be from 0-100
guardian_name	no	string	mandatory if nominee is a minor
guardian_pan	no	string	PAN of the guardian, applicable only if the nominee is a minor
guardian_relationship	no	string	relationship of a nominee with the guardian. Mandatory if a nominee is a minor

KYC IdentityDetail params

Name	Mandatory	type	Comments
name	yes	string	name of the investor as printed in the identity_proof
father_or_spouse_name	no	string
mothers_name	no	string
kyc_relation	no	enum	relationship of the investor with person mentioned in father_or_spouse_name field. Values permitted: FATHER, SPOUSE
country_of_citizenship_ansi_code	yes	string	ANSI code of the country of citizenship of the investor
date_of_birth	yes	string	date of birth of the investor in "YYYY-MM-DD" format
gender	yes	enum	gender of the investor. Values permitted: MALE, FEMALE, OTHERS
marital_status	yes	enum	marital status of the investor. Values permitted: MARRIED, SINGLE, OTHERS
residential_status	yes	enum	residential status of the investor. Values permitted: RESIDENT_INDIVIDUAL, NON_RESIDENT_INDIVIDUAL
occupation	yes	enum	occupation of the investor. Values permitted: AGRICULTURE, BUSINESS, DOCTOR, FOREX_DEALER, GOVERNMENT_SERVICE, HOUSE_WIFE, OTHERS, PRIVATE_SECTOR_SERVICE, PROFESSIONAL, PUBLIC_SECTOR_SERVICE, RETIRED, SERVICE, STUDENT.
pan_number	no	string	should be valid pan_number and mandatory if pan_exempt is false
pan_exempt	no	boolean	default to be false
pep_exposed	yes	boolean	flag to determine if the person is politically exposed
pep_related	yes	boolean	flag to determine if the person is related to a politically exposed person
guardian_name	no	string	mandatory if investor is minor
guardian_relationship	no	string	mandatory if investor is minor
guardian_date_of_birth	no	string	mandatory if investor is minor. Date of birth in format "YYYY-MM-DD".
guardian_pan_number	no	string	mandatory if investor is minor. The PAN number of the guardian should be a valid PAN number.
signature	no	string	File Id of uploaded signature image using files api. Mandatory to create Investment Account when order gateway provider is BSE

Address _params

Name	Mandatory	type	Comments
line1	yes	string
line2	no	string
line3	no	string
city	no	string	mandatory if zipcode is given
state	no	string	mandatory if zipcode is given
pincode	no	string	mandatory if zipcode is not given
zipcode	no	string	mandatory if pincode is not given
country_ansi_code	no	string	mandatory if zipcode is given

A note on BSE order gateway

Mandatory fields validation for BSE

Field	Mandatory	Remarks
perm_addr_is_corres_addr	yes
kyc_identity_detail.name	yes
kyc_identity_detail.date_of_birth	yes
bank_accounts	yes	At least one bank account. For each bank account type, number and ifsc_code are mandatory
correspondence_address.line1	yes
correspondence_address.city	yes
correspondence_address.state	yes
correspondence_address.pincode	yes
correspondence_address.country_ansi_code	yes
contact_detail.email	yes
contact_detail.mobile	yes

Tax status specific validations for BSE

Tax Status	4th character of PAN	Bank Account Type	Guardian Name	Guardian PAN	Gender
Individual	P	SAVINGS/CURRENT/NRE/NRO			mandatory
On behalf of minor	P	SAVINGS/CURRENT	mandatory	mandatory	mandatory

Maximum length validations for BSE

Field	Maximum length
kyc_identity_detail.name	70
kyc_identity_detail.guardian_name	35
kyc_identity_detail.date_of_birth	10
nominee.name	35
nominee.relationship	20
bank_account.number	16
bank_account.ifsc	11
address.line1	40
address.line2	40
address.line3	40
address.city	35
contact_detail.office_telephone_no	15
contact_detail.residence_telephone_no	15
contact_detail.email	50
contact_detail.mobile	10

Update an investor

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

JSON Request

Same parameters as the request for create investor endpoint

JSON Reponse

{
  "id": 1,
  "display_name": "tony",
  "perm_addr_is_corres_addr": true,
  "ip_address": "192.168.1.1",
  "created_at": "2018-05-22T10:14:19.072Z",
  "updated_at": "2018-05-22T10:14:19.072Z",
  "meta": null,
  "nomination": {
    "skip_nomination": false,
    "nominee1": {
      "date_of_birth": "1990-10-10",
      "name": "Tony Stark",
      "pan": null,
      "relationship": "nandam",
      "guardian_name": null,
      "guardian_pan": null,
      "guardian_relationship": null,
      "allocation_percentage": 100
    },
    "nominee2": null,
    "nominee3": null
  },
  "contact_detail": {
    "email": "mfp@cybrilla.com",
    "isd_code": 91,
    "mobile": "9008580644",
    "office_telephone_no": null,
    "residence_telephone_no": null
  },
  "fatca_detail": {
    "country_of_birth_ansi_code": "IN",
    "source_of_wealth": "BUSINESS",
    "first_trc_ansi_code": null,
    "first_trc_taxid_type": null,
    "first_trc_taxid_number": null,
    "second_trc_ansi_code": null,
    "second_trc_taxid_type": null,
    "second_trc_taxid_number": null,
    "third_trc_ansi_code": null,
    "third_trc_taxid_type": null,
    "third_trc_taxid_number": null,
    "gross_annual_income": 1000000,
    "no_other_tax_residences": true
  },
  "kyc_identity_detail": {
    "name": "tony Soprano ms",
    "father_or_spouse_name": "tonys wife",
    "mothers_name": null,
    "ckyc_number": null,
    "kyc_relation": "spouse",
    "date_of_birth": "1980-10-10",
    "marital_status": "MARRIED",
    "pan_number": "AFZPN3001P",
    "gender": "female",
    "occupation": "BUSINESS",
    "residential_status": "RESIDENT_INDIVIDUAL",
    "country_of_citizenship_ansi_code": "IN",
    "pan_exempt": false,
    "pep_exposed": false,
    "pep_related": false,
    "guardian_relationship": null,
    "guardian_name": null,
    "guardian_date_of_birth": null,
    "guardian_pan_number": null,
    "signature": "beed6916-cec6-4f4f-bcc8-ed4d93b55660"
  },
  "bank_accounts": [
    {
      "id": 1,
      "account_holder_name": "tony",
      "type": "SAVINGS",
      "primary_account": true,
      "number": "00000001214415",
      "created_at": "2019-05-22T10:14:19.082Z",
      "updated_at": "2019-05-22T10:14:19.082Z",
      "branch": {
        "ifsc_code": "ICIC0000611",
        "micr_code": null,
        "branch_name": "GUDIVADA",
        "bank_name": "ICICI BANK LIMITED",
        "branch_address": "ICICI BANK LTD , D NO11218, NENIPLAZA, ELURU ROAD, GUDIVADA 521301",
        "contact": null,
        "city": "GUDIVADA",
        "district": "KRISHNA",
        "state": "ANDHRA PRADESH"
      },
      "cancelled_cheque": "3867a9c6-8a7c-4605-a31d-98367e8972b4"
    }
  ],
  "correspondence_address": {
    "line1": "1082 road",
    "line2": null,
    "line3": null,
    "type": "CORRESPONDENCE",
    "zipcode": "560112",
    "city": "Bengaluru",
    "state": "KARNATAKA",
    "country_ansi_code": "IN"
  },
  "_links": [
    {
      "href": "https://s.finprim.com/onb/investors/229",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://s.finprim.com/onb/investors/229",
      "rel": "update",
      "method": "POST"
    }
  ]
}

POST /api/onb/investors/:id

Update an existing investor's details. Existing folios for this investor don't get affected by this change.. Any new folios created after the update will contain the updated investor's details.

Parameters

All query parameters are same as create investor. Refer to create investor documentation

In bank_accounts array, the id of each bank account needs to be sent to update the existing bank account. Otherwise, a new bank account will be added to the investor.

Note:

When you update the details of an investor at FP, investor demographic information is only updated at FP. The investor demographic information wouldn't change at
a) Existing folios for the investor
b) Existing investor information stored at BSE(For BSE customers)

Fetch an investor

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

JSON Reponse

{
  "id": 1,
  "display_name": "tony",
  "perm_addr_is_corres_addr": true,
  "ip_address": "192.168.1.1",
  "created_at": "2018-05-22T10:14:19.072Z",
  "updated_at": "2018-05-22T10:14:19.072Z",
  "meta": null,
  "nomination": {
    "skip_nomination": false,
    "nominee1": {
      "date_of_birth": "1990-10-10",
      "name": "Tony Stark",
      "pan": null,
      "relationship": "nandam",
      "guardian_name": null,
      "guardian_pan": null,
      "guardian_relationship": null,
      "allocation_percentage": 100
    },
    "nominee2": null,
    "nominee3": null
  },
  "contact_detail": {
    "email": "mfp@cybrilla.com",
    "isd_code": 91,
    "mobile": "9008580644",
    "office_telephone_no": null,
    "residence_telephone_no": null
  },
  "fatca_detail": {
    "country_of_birth_ansi_code": "IN",
    "source_of_wealth": "BUSINESS",
    "first_trc_ansi_code": null,
    "first_trc_taxid_type": null,
    "first_trc_taxid_number": null,
    "second_trc_ansi_code": null,
    "second_trc_taxid_type": null,
    "second_trc_taxid_number": null,
    "third_trc_ansi_code": null,
    "third_trc_taxid_type": null,
    "third_trc_taxid_number": null,
    "gross_annual_income": 1000000,
    "no_other_tax_residences": true
  },
  "kyc_identity_detail": {
    "name": "tony Soprano ms",
    "father_or_spouse_name": "tonys wife",
    "mothers_name": null,
    "ckyc_number": null,
    "kyc_relation": "spouse",
    "date_of_birth": "1980-10-10",
    "marital_status": "MARRIED",
    "pan_number": "AFZPN3001P",
    "gender": "female",
    "occupation": "BUSINESS",
    "residential_status": "RESIDENT_INDIVIDUAL",
    "country_of_citizenship_ansi_code": "IN",
    "pan_exempt": false,
    "pep_exposed": false,
    "pep_related": false,
    "guardian_relationship": null,
    "guardian_name": null,
    "guardian_date_of_birth": null,
    "guardian_pan_number": null,
    "signature": "beed6916-cec6-4f4f-bcc8-ed4d93b55660"
  },
  "bank_accounts": [
    {
      "id": 1,
      "account_holder_name": "tony",
      "type": "SAVINGS",
      "primary_account": true,
      "number": "00000001214415",
      "created_at": "2019-05-22T10:14:19.082Z",
      "updated_at": "2019-05-22T10:14:19.082Z",
      "branch": {
        "ifsc_code": "ICIC0000611",
        "micr_code": null,
        "branch_name": "GUDIVADA",
        "bank_name": "ICICI BANK LIMITED",
        "branch_address": "ICICI BANK LTD , D NO11218, NENIPLAZA, ELURU ROAD, GUDIVADA 521301",
        "contact": null,
        "city": "GUDIVADA",
        "district": "KRISHNA",
        "state": "ANDHRA PRADESH"
      },
      "cancelled_cheque": "3867a9c6-8a7c-4605-a31d-98367e8972b4"
    }
  ],
  "correspondence_address": {
    "line1": "1082 road",
    "line2": null,
    "line3": null,
    "type": "CORRESPONDENCE",
    "zipcode": "560112",
    "city": "Bengaluru",
    "state": "KARNATAKA",
    "country_ansi_code": "IN"
  },
  "_links": [
    {
      "href": "https://s.finprim.com/onb/investors/229",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://s.finprim.com/onb/investors/229",
      "rel": "update",
      "method": "POST"
    }
  ]
}

GET /api/onb/investors/:id

Retrieve an investor with the investor id

List all investors

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

JSON Response

{
  "last": false,
  "first": false,
  "total_pages": 5,
  "number": 2,
  "size": 10,
  "total_elements": 41,
  "investors": [
    {
      "id": 1,
      "display_name": "tony",
      "perm_addr_is_corres_addr": true,
      "ip_address": "192.168.1.1",
      "created_at": "2018-05-22T10:14:19.072Z",
      "updated_at": "2018-05-22T10:14:19.072Z",
      "meta": null,
      "nomination": {
        "skip_nomination": false,
        "nominee1": {
          "date_of_birth": "1990-10-10",
          "name": "Tony Stark",
          "pan": null,
          "relationship": "nandam",
          "guardian_name": null,
          "guardian_pan": null,
          "guardian_relationship": null,
          "allocation_percentage": 100
        },
        "nominee2": null,
        "nominee3": null
      },
      "contact_detail": {
        "email": "mfp@cybrilla.com",
        "isd_code": 91,
        "mobile": "9008580644",
        "office_telephone_no": null,
        "residence_telephone_no": null
      },
      "fatca_detail": {
        "country_of_birth_ansi_code": "IN",
        "source_of_wealth": "BUSINESS",
        "first_trc_ansi_code": null,
        "first_trc_taxid_type": null,
        "first_trc_taxid_number": null,
        "second_trc_ansi_code": null,
        "second_trc_taxid_type": null,
        "second_trc_taxid_number": null,
        "third_trc_ansi_code": null,
        "third_trc_taxid_type": null,
        "third_trc_taxid_number": null,
        "gross_annual_income": 1000000,
        "no_other_tax_residences": true
      },
      "kyc_identity_detail": {
        "name": "tony Soprano ms",
        "father_or_spouse_name": "tonys wife",
        "mothers_name": null,
        "ckyc_number": null,
        "kyc_relation": "spouse",
        "date_of_birth": "1980-10-10",
        "marital_status": "MARRIED",
        "pan_number": "AFZPN3001P",
        "gender": "female",
        "occupation": "BUSINESS",
        "residential_status": "RESIDENT_INDIVIDUAL",
        "country_of_citizenship_ansi_code": "IN",
        "pan_exempt": false,
        "pep_exposed": false,
        "pep_related": false,
        "guardian_relationship": null,
        "guardian_name": null,
        "guardian_date_of_birth": null,
        "guardian_pan_number": null,
        "signature": "beed6916-cec6-4f4f-bcc8-ed4d93b55660"
      },
      "bank_accounts": [
        {
          "id": 1,
          "account_holder_name": "tony",
          "type": "SAVINGS",
          "primary_account": true,
          "number": "00000001214415",
          "created_at": "2019-05-22T10:14:19.082Z",
          "updated_at": "2019-05-22T10:14:19.082Z",
          "branch": {
            "ifsc_code": "ICIC0000611",
            "micr_code": null,
            "branch_name": "GUDIVADA",
            "bank_name": "ICICI BANK LIMITED",
            "branch_address": "ICICI BANK LTD , D NO11218, NENIPLAZA, ELURU ROAD, GUDIVADA 521301",
            "contact": null,
            "city": "GUDIVADA",
            "district": "KRISHNA",
            "state": "ANDHRA PRADESH"
          },
          "cancelled_cheque": "3867a9c6-8a7c-4605-a31d-98367e8972b4"
        }
      ],
      "correspondence_address": {
        "line1": "1082 road",
        "line2": null,
        "line3": null,
        "type": "CORRESPONDENCE",
        "zipcode": "560112",
        "city": "Bengaluru",
        "state": "KARNATAKA",
        "country_ansi_code": "IN"
      },
      "_links": [
        {
          "href": "https://s.finprim.com/onb/investors/229",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://s.finprim.com/onb/investors/229",
          "rel": "update",
          "method": "POST"
        }
      ]
    }
  ]
}

GET /api/onb/investors

Retrieve all the investors

Query Parameters

Parameter	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

Search Investors

GET /api/onb/investors/search

curl "https://s.finprim.com/api/onb/investors/search?query=user@cybrilla.com&bank_account_ids=1,22"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "last": false,
  "first": false,
  "total_pages": 5,
  "number": 2,
  "size": 10,
  "total_elements": 41,
  "investors": [
    {
      "id": 1,
      "display_name": "tony",
      "perm_addr_is_corres_addr": true,
      "ip_address": "192.168.1.1",
      "created_at": "2018-05-22T10:14:19.072Z",
      "updated_at": "2018-05-22T10:14:19.072Z",
      "meta": null,
      "nomination": {
        "skip_nomination": false,
        "nominee1": {
          "date_of_birth": "1990-10-10",
          "name": "Tony Stark",
          "pan": null,
          "relationship": "nandam",
          "guardian_name": null,
          "guardian_pan": null,
          "guardian_relationship": null,
          "allocation_percentage": 100
        },
        "nominee2": null,
        "nominee3": null
      },
      "contact_detail": {
        "email": "mfp@cybrilla.com",
        "isd_code": 91,
        "mobile": "9008580644",
        "office_telephone_no": null,
        "residence_telephone_no": null
      },
      "fatca_detail": {
        "country_of_birth_ansi_code": "IN",
        "source_of_wealth": "BUSINESS",
        "first_trc_ansi_code": null,
        "first_trc_taxid_type": null,
        "first_trc_taxid_number": null,
        "second_trc_ansi_code": null,
        "second_trc_taxid_type": null,
        "second_trc_taxid_number": null,
        "third_trc_ansi_code": null,
        "third_trc_taxid_type": null,
        "third_trc_taxid_number": null,
        "gross_annual_income": 1000000,
        "no_other_tax_residences": true
      },
      "kyc_identity_detail": {
        "name": "tony Soprano ms",
        "father_or_spouse_name": "tonys wife",
        "mothers_name": null,
        "ckyc_number": null,
        "kyc_relation": "spouse",
        "date_of_birth": "1980-10-10",
        "marital_status": "MARRIED",
        "pan_number": "AFZPN3001P",
        "gender": "female",
        "occupation": "BUSINESS",
        "residential_status": "RESIDENT_INDIVIDUAL",
        "country_of_citizenship_ansi_code": "IN",
        "pan_exempt": false,
        "pep_exposed": false,
        "pep_related": false,
        "guardian_relationship": null,
        "guardian_name": null,
        "guardian_date_of_birth": null,
        "guardian_pan_number": null,
        "signature": "beed6916-cec6-4f4f-bcc8-ed4d93b55660"
      },
      "bank_accounts": [
        {
          "id": 1,
          "account_holder_name": "tony",
          "type": "SAVINGS",
          "primary_account": true,
          "number": "00000001214415",
          "created_at": "2019-05-22T10:14:19.082Z",
          "updated_at": "2019-05-22T10:14:19.082Z",
          "branch": {
            "ifsc_code": "ICIC0000611",
            "micr_code": null,
            "branch_name": "GUDIVADA",
            "bank_name": "ICICI BANK LIMITED",
            "branch_address": "ICICI BANK LTD , D NO11218, NENIPLAZA, ELURU ROAD, GUDIVADA 521301",
            "contact": null,
            "city": "GUDIVADA",
            "district": "KRISHNA",
            "state": "ANDHRA PRADESH"
          },
          "cancelled_cheque": "3867a9c6-8a7c-4605-a31d-98367e8972b4"
        }
      ],
      "correspondence_address": {
        "line1": "1082 road",
        "line2": null,
        "line3": null,
        "type": "CORRESPONDENCE",
        "zipcode": "560112",
        "city": "Bengaluru",
        "state": "KARNATAKA",
        "country_ansi_code": "IN"
      },
      "_links": [
        {
          "href": "https://s.finprim.com/onb/investors/229",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://s.finprim.com/onb/investors/229",
          "rel": "update",
          "method": "POST"
        }
      ]
    }
  ]
}

Retrieve a list of investors by applying certain filters

Query Parameters

Parameter	Mandatory	Default	Description
query	no	-	it can be name, email or PAN number
bank_account_ids	no	-	multiple bank account IDs separated by a comma
ids	no	-	multiple investors IDs separated by a comma
guardian_pan_numbers	no	-	Guardian Pan numbers
page	no	0	page number of the result set
size	no	20	number of results per page, size should not be greater than 100

SIPs ^(Deprecated)

Plan represents the recurring investment orders scheduled on a monthly basis (monthly SIPs). The API allows you to create, update and cancel the SIPs for an investment account.

Endpoints:

POST /api/oms/investment_accounts/:id/orders/sips
PATCH /api/oms/investment_accounts/:id/orders/sips/:id
GET /api/oms/investment_accounts/:id/orders/sips/:id
GET /api/oms/investment_accounts/:id/orders/sips/:id/installments
GET /api/oms/investment_accounts/:id/orders/sips

Create a SIP

curl -X POST "https://s.finprim.com/api/oms/investment_accounts/123/orders/sips"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON request

{
  "orders": [
    {
      "isin": "INF204KA1B64",
      "amount": 10000,
      "start_day": "2",
      "frequency": "MONTHLY",
      "installments": 20,
      "mandate_id": 23,
      "source_ref_id": "0876789",
      "user_ip": "192.168.2.92",
      "server_ip": "192.168.2.95",
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd_code": "91",
        "mobile": "9008580644"
      }
    }
  ]
}

JSON response

{
  "orders": [
    {
      "id": 99,
      "isin": "INF204KA1B64",
      "isin_no": "INF204KA1B64",
      "source_ref_id": "0876789",
      "user_ip": "192.168.2.92",
      "server_ip": "192.168.2.95"
    }
  ]
}

POST /api/oms/investment_accounts/:id/orders/sips

Create a monthly systematic investment plan (SIP). SIP is allowed only for certain schemes (refer sip_allowed attribute in the fund scheme api)

Note : The fund parameters mentioned in the comments below are availabe in Single Fund Schemes Detail API response

Parameters

Name	Mandatory	Type	Comments
isin	yes	string	fund ISIN number
amount	yes	integer	amount should be in multiple of sip_multiples and between min_sip_amount and max_sip_amount
start_day	yes	string	start_day should be one of the values received in sip_frequency_data
frequency	yes	string	currently only "MONTHLY" frequency is supported
installments	yes	integer	installments should be between min_sip_installments and 1200 inclusive
folio_number	no	string	mandatory if you need to place an additional sip in the given folio number
mandate_id	yes	integer	mandate ID returns in Create Mandate API response
generate_first_installment_now	no	boolean	By default, the value of this flag is false. If this flag is true, the first installment is generated immediately after SIP creation and the first installment will be in PENDING state
source_ref_id	no	string	this is a source reference ID which will unique across system for a sip (ideally an auto generate identifier / uuid to identify a SIP in the tenant's application)
user_ip	no	string	IP address of user
server_ip	no	string	IP address of server
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	Yes	hash	Consent from investor for confirming the SIP registration. Once set, this cannot be modified.

SIP Consent Details

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

1. Before order is sent to RTAs, investor consent must be obtained by sending a One-Time Password to the investor at his/her email/phone number -
   • In case of order placed against an existing folio the consent should be taken from the email/mobile registered against the existing folio.
   • In case of an order placed placed without a folio, the consent should be taken from the email/mobile available in the V1 investor object or V2 investor profile.
2. Before order is sent to BSE, investor consent must be obtained by sending a One-Time Password to the investor at his/her email and phone number -
   • In case of order placed against an existing folio the consent should be taken from the email and mobile registered against the existing folio.
   • In case of order placed without folio the consent should be taken from the email and mobile registered against the UCC.

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

Accepting payment for first installment on the day of SIP creation

To accept the payment for the first installment of the SIP immediately after the SIP creation, the SIP must be created with generate_first_installment_now=true. If this flag is set, FP will generate the first installment immediately after the SIP is created and the first installment will be in PENDING state. This installment can then be fetched using Fetch_Installments_API. After the installment is fetched you can use Create a Payment API or Create a Nach Payment API to create a payment. Please note that even if the mandate is APPROVED during SIP creation, no payment will be created for the first installment that is generated because of generate_first_installment_now=true flag.

Examples (when generate_first_installment_now = true)

SIP Creation day	Start day	First installment date	Second installment date
August 11,2021	10	August 11,2021	October 10,2021
August 11,2021	11	August 11,2021	Septemeber 11,2021
August 11,2021	12	August 11,2021	Septemeber 12,2021
August 11,2021	28	August 11,2021	Septemeber 28,2021

Modify a SIP

curl -X PATCH "https://s.finprim.com/api/oms/investment_accounts/123/orders/sips/345"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON request

{
  "operation": "update",
  "data": {
    "mandate_id": "DQ12"
  }
}

JSON response

For update operation

{
  "message": "successfully updated the sip"
}

For deactivate operation

{
  "sip_id": 102,
  "v2_id": "mfpp_ef29a79a21c54f7fb0112156727af0e1",
  "active": false,
  "amount": 5000.0,
  "frequency": "MONTHLY",
  "start_date": "2024-02-02",
  "installments": 12,
  "folio_number": null,
  "mandate_id": "26",
  "isin": "INF846K018E9",
  "source_ref_id": null,
  "created_at": "2024-01-04T11:16:55+05:30",
  "initiated_by": null,
  "initiated_via": null,
  "cancellation_code": "amount_not_available"
}

For cancel_next_installment operation

{
  "id": 797,
  "type": "PURCHASE",
  "status": "CANCELLED",
  "amount": 5000.0,
  "units": null,
  "reverse_amount": null,
  "reverse_units": null,
  "price": null,
  "switch_in_price": null,
  "switch_in_units": null,
  "trade_date": null,
  "investment_date": "2024-02-02",
  "folio_number": null,
  "bank_account_id": null,
  "source_ref_id": null,
  "sip_id": 102,
  "redemption_mode": null,
  "redemption_bank_account_number": null,
  "redemption_bank_account_ifsc_code": null,
  "confirmed_at": null,
  "submitted_at": null,
  "succeeded_at": null,
  "reversed_at": null,
  "failed_at": null,
  "created_at": "2024-01-04T11:17:01+05:30",
  "fund_scheme": {
    "id": 26472,
    "name": "AXIS MULTICAP FUND REGULAR IDCW REINVESTMENT",
    "isin": "INF846K018E9",
    "scheme_code": "MTDP"
  },
  "switch_in_fund_scheme": null,
  "annotations": null,
  "initiated_by": null,
  "initiated_via": null
}

PATCH /api/oms/investment_accounts/:id/orders/sips/:id

Update the payment mandate for a SIP, cancel the next installment or all the future installments of a SIP

Parameters

Name	Mandatory	Type	Comments
operation	yes	string	Allowed values for RTA Gateway: update, deactivate, cancel_next_installment Allowed values for BSE Gatweay: deactivate
mandate_id	conditional	string	ID of the mandate object. Required if the operation is update
cancellation_code	conditional	string	Required if the operation is deactivate.

Allowed cancellation codes to deactivate

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 SIP

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
monthly	3

Note: FP will mark the SIP as cancelled automatically if the number of consecutive failed\cancelled instalments is more than the limit suggested by SEBI. SIP will also have a cancellation_code attribute with value as consecutive_failed_installment_limit_exceeded. Read more

BSE SIP Deactivation Note :

• Production : During deactivation of SIP, if the next installment date is found to be within 7 working days from the deactivation date, then the next installment will go through and subsequent installments will be canceled. This means that only after the immediate installment is processed, SIP will be marked as active=false. However, if the next installment date is found to be farther than 7 working days from the cancellation date, the SIP cancellation request is placed to BSE immediately and asynchronously and after some time, the SIP state changes to active=false.
• Sandbox : The SIP deactivation behavior is simulated and upon receipt of the request to deactivate SIP, the SIP will get deactivated after 1 minute. This allows developers to mimic the behavior in production where SIPs are marked active=false after some time..

Fetch a SIP

curl -X GET "https://s.finprim.com/api/oms/investment_accounts/123/orders/sips/434
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON response

{
  "sip_id": 434,
  "v2_id": "mfpp_8b9d798f6bfc4196934583f29182035c",
  "active": true,
  "amount": 5000.0,
  "frequency": "MONTHLY",
  "start_date": "2024-02-02",
  "installments": 12,
  "folio_number": "ETADUEVNR5S4N",
  "mandate_id": "26",
  "isin": "INF846K018E9",
  "source_ref_id": null,
  "created_at": "2024-01-03T17:26:04+05:30",
  "initiated_by": null,
  "initiated_via": null,
  "cancellation_code": null
}

GET /api/oms/investment_accounts/:id/orders/sips/:id

Fetch the details of a particular SIP

Fetch installments of a SIP

curl -X GET "https://s.finprim.com/api/oms/investment_accounts/123/orders/sips/345/installments"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON response

[
  {
    "id": 793,
    "type": "ADDITIONAL_PURCHASE",
    "status": "PENDING",
    "amount": 5000.0,
    "units": null,
    "reverse_amount": null,
    "reverse_units": null,
    "price": null,
    "switch_in_price": null,
    "switch_in_units": null,
    "trade_date": null,
    "investment_date": "2024-01-04",
    "folio_number": "ETADUEVNR5S4N",
    "bank_account_id": null,
    "source_ref_id": null,
    "sip_id": 99,
    "redemption_mode": null,
    "redemption_bank_account_number": null,
    "redemption_bank_account_ifsc_code": null,
    "confirmed_at": null,
    "submitted_at": null,
    "succeeded_at": null,
    "reversed_at": null,
    "failed_at": null,
    "created_at": "2024-01-03T17:26:04+05:30",
    "fund_scheme": {
      "id": 26472,
      "name": "AXIS MULTICAP FUND REGULAR IDCW REINVESTMENT",
      "isin": "INF846K018E9",
      "scheme_code": "MTDP"
    },
    "switch_in_fund_scheme": null,
    "annotations": null,
    "initiated_by": null,
    "initiated_via": null
  }
]

Retrieve all the installments of a particular SIP

HTTP Request

GET /api/oms/investment_accounts/:id/orders/sips/:id/installments

List all SIPs

curl -X GET "https://s.finprim.com/api/oms/investment_accounts/123/orders/sips"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON response

{
  "sip_orders": [
    {
      "sip_id": 98,
      "v2_id": "mfpp_7f26643f40ab45a39ff4ac3fbbdc872a",
      "active": false,
      "amount": 5000.0,
      "frequency": "MONTHLY",
      "start_date": "2024-02-02",
      "installments": 12,
      "folio_number": null,
      "mandate_id": "26",
      "isin": "INF846K018E9",
      "source_ref_id": null,
      "created_at": "2024-01-03T13:42:08+05:30",
      "initiated_by": null,
      "initiated_via": null,
      "cancellation_code": "amount_not_available"
    },
    {
      "sip_id": 99,
      "v2_id": "mfpp_8b9d798f6bfc4196934583f29182035c",
      "active": true,
      "amount": 5000.0,
      "frequency": "MONTHLY",
      "start_date": "2024-02-02",
      "installments": 12,
      "folio_number": "ETADUEVNR5S4N",
      "mandate_id": "26",
      "isin": "INF846K018E9",
      "source_ref_id": null,
      "created_at": "2024-01-03T17:26:04+05:30",
      "initiated_by": null,
      "initiated_via": null,
      "cancellation_code": null
    }
  ],
  "last": false,
  "total_pages": 3,
  "total_elements": 6,
  "size": 2,
  "number": 0,
  "first": true,
  "number_of_elements": 2,
  "_links": {
    "self": {
      "href": "https://s.finprim.com/api/oms/investment_accounts/69/orders/sips"
    }
  }
}

GET /api/oms/investment_accounts/:id/orders/sips

Retreive all the SIPs for an investment account

Query Parameters

Parameter	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