NAV Navbar
shell

Introduction

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

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

MasterData

Pincode

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

The above command returns JSON structured like this:

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

This endpoint retrieves details of the given pincode

HTTP Request

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

Response Object

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

States

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

Response Object

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

Countries

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

The above command returns JSON structured like this:

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

This endpoint retrieves the list of countries updated in the system

HTTP Request

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

Response Object

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

IFSC

curl "https://s.finprim.com/api/onb/ifsc_codes/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 - V2

This API must be used to fetch information about a mutual fund scheme supported by a particular gateway by providing an isin. At present, only scheme information of cybrillapoa gateway can be fetched.

curl "https://s.finprim.com/v2/mf_scheme_plans/cybrillapoa/INF179KA1JD2?expand=mf_scheme,mf_fund "
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns JSON structured like this:

{
  "object": "mf_scheme_plan",
  "gateway": "cybrillapoa",
  "mf_scheme": {
    "name": "UTI - LIQUID FUND"
  },
  "mf_fund": {
    "name": "UTI MUTUAL FUND"
  },
  "isin": "INF789F1AF85",
  "type": "regular",
  "option": "growth",
  "idcw_option": null,
  "active": true,
  "thresholds": [
    {
      "type": "lumpsum",
      "amount_min": 100.0,
      "additional_amount_min": 100.0,
      "amount_max": 999999999.0,
      "additional_amount_max": 999999999.0,
      "amount_multiples": 1.0,
      "additional_amount_multiples": 1.0
    },
    {
      "type": "withdrawal",
      "amount_min": 1.0,
      "amount_max": 999999999.0,
      "amount_multiples": 1.0,
      "units_min": 0.001,
      "units_max": 999999999.0,
      "units_multiples": 0.001
    },
    {
      "type": "instant_withdrawal",
      "amount_min": 1.0,
      "amount_multiples": 1.0
    },
    {
      "type": "switch_in",
      "amount_min": 100.0,
      "amount_max": 999999999.0,
      "amount_multiples": 1.0
    },
    {
      "type": "switch_out",
      "amount_min": 1.0,
      "amount_max": 999999999.0,
      "amount_multiples": 1.0,
      "units_min": 0.001,
      "units_max": 999999999.0,
      "units_multiples": 0.001
    },
    {
      "type": "sip",
      "frequency": "monthly",
      "amount_min": 100.0,
      "amount_max": 999999999.0,
      "amount_multiples": 1.0,
      "installments_min": 6,
      "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
      ]
    },
    {
      "type": "swp",
      "frequency": "monthly",
      "amount_min": 500.0,
      "amount_max": 999999999.0,
      "amount_multiples": 1.0,
      "installments_min": 3,
      "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
      ]
    },
    {
      "type": "stp_in",
      "frequency": "monthly",
      "amount_min": 1000.0,
      "amount_max": 999999999.0,
      "amount_multiples": 1.0,
      "installments_min": 6,
      "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
      ]
    },
    {
      "type": "stp_out",
      "frequency": "monthly",
      "amount_min": 1000.0,
      "amount_max": 999999999.0,
      "amount_multiples": 1.0,
      "installments_min": 6,
      "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
      ]
    }
  ]
}

HTTP Request

GET /v2/mf_scheme_plans/:gateway/:isin?expand=mf_scheme,mf_fund

Request Parameters

Path Parameters:

Name Mandatory Type Comments
gateway yes string The identifier for the order gateway. Example: cybrillapoa
isin yes string The ISIN code for the scheme plan. Example: INF789F1AF85

Query Parameters:

Name Mandatory Type Comments
expand yes string Mandatory Supported values: mf_scheme, mf_fund

Response Object

Fund Scheme Plan Response Object

Attribute Type Description
object string Type of the object returned (value : mf_scheme_plan)
gateway string Allowed order gateways. Value supported : cybrillapoa
mf_scheme.name string Name of the mutual fund
mf_fund.name string Parent mutual fund name
isin string ISIN of the scheme
type string Plan type of the scheme. Possible values: regular, direct
option string Option of the scheme. Possible values: growth,bonus,idcw,idcw_daily,idcw_weekly,idcw_monthly,idcw_fortnightly,idcw_quarterly,idcw_half_yearly,idcw_annual,idcw_flexi
idcw_option string IDCW option of the scheme. Value will be null if option is growth. Possible values:reinvestment, payout
active boolean If the scheme is active, value is 'true' else, value is 'false'
thresholds array Array defining limits for different transaction types

Thresholds params

Attribute Type Description
type string Type of transaction. Possible values:lumpsum, withdrawal, instant_withdrawal, switch_in, switch_out, sip, swp, stp_in, stp_out
frequency string Frequency of transaction. Possible values: daily, calendar_day_daily, monthly
amount_min decimal Minimum allowed amount
additional_amount_min decimal Minimum additional amount
amount_max decimal Maximum allowed amount
additional_amount_max decimal Maximum additional amount
amount_multiples decimal Amount must be a multiple of this value
additional_amount_multiples decimal Additional amount must be multiple of this value
installments_min integer Minimum number of installments
units_min decimal Minimum number of units
units_max decimal Maximum number of units
unit_multiples decimal Units must be a multiple of this value
dates array Installment dates for SIP, SWP, STP_IN, STP_OUT transactions

AMCs

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

The above command returns JSON structured like this:

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

This endpoint retrieves all the AMCs.

HTTP Request

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

Response Object

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

Authentication

Overview

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

Types of authentication

Endpoints for authentication:

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

Token Object

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

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

Tenant Authentication

Getting Started

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

Getting tenant token

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

POST /v2/auth/{tenant_name}/token 

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

Success response:

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

Headers

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

Request Parameters

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

Using token to make API call

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

Authorization: Bearer ACCESS_TOKEN

Efficient Usage of JWT Tokens

Overview

To ensure security and optimize performance, it's crucial to avoid excessive creation of JWT tokens. Instead, clients should rely on the token's expiry attribute and use the same token for multiple requests until it expires.

** Best Practices for Clients**

Reuse Tokens Until Expiry

Minimize Unnecessary Authentication Calls

Implement Token Caching

Common Mistakes to Avoid

❌ Requesting a new token on every API call.

❌ Ignoring the expiry attribute and assuming the token is always invalid.

❌ Storing tokens insecurely, leading to security risks.

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

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.

Bank Accounts

Endpoints:

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

Bank Account Object

Bank Account Object

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

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

Bank Account Object attributes

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

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

Create a Bank Account

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

JSON Request

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

JSON Response

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

POST /v2/bank_accounts

This API can be used to create a bank_account object.

Request Parameters

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

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

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

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

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

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

Modify a Bank Account

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

JSON Request

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

JSON Response

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

PATCH /v2/bank_accounts

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

Body parameters

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


NOTE:

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


Fetch a Bank Account

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

JSON Response

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

GET /v2/bank_accounts/:id

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

Query parameters

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

List all Bank Accounts

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

JSON Response

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

GET /v2/bank_accounts

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

Query parameters

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

Addresses

Endpoints:

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

Address Object

Address Object

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

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

Address object attributes

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

Create an Address

POST /v2/addresses

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

JSON Request

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

JSON Response

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

This API can be used to create an address object.

Request Parameters

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

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

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

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

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

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

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

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

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


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

Modify an Address

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

JSON Request

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

JSON Response

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

PATCH /v2/addresses

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

Body parameters

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

Other input parameters are same as Create an Address API

Fetch an Address

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

JSON Response

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

GET /v2/addresses/:id

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

Query parameters

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

List all Addresses

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

JSON Response

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

GET /v2/addresses

This API can be used to fetch all the addresses.

Query parameters

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

Phone Numbers

Endpoints:

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

Phone Number Object

Phone Number Object

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

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

Phone Number object attributes

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

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

Create a Phone Number

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

JSON Request

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

JSON Response

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

POST /v2/phone_numbers

This API can be used to create a phone_number object.

Request Parameters

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

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

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

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

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

Modify a Phone Number

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

JSON Request

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

JSON Response

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

PATCH /v2/phone_numbers

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

Body parameters

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

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

Fetch a Phone Number

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

JSON Response

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

GET /v2/phone_numbers/:id

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

Query parameters

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

List all Phone Numbers

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

JSON Response

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

GET /v2/phone_numbers

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

Query parameters

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

Email Addresses

Endpoints:

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

Email Address Object

Email Address Object

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

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

Email Address object attributes

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

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

Create an Email Address

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

JSON Request

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

JSON Response

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

POST /v2/email_addresses

This API can be used to create a email_address object.

Request Parameters

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

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

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

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

Modify an Email Address

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

JSON Request

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

JSON Response

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

PATCH /v2/email_addresses

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

Body parameters

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

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

Fetch an Email Address

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

JSON Response

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

GET /v2/email_addresses/:id

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

Query parameters

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

List all Email Addresses

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

JSON Response

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

GET /v2/email_addresses

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

Query parameters

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

Related Parties

Endpoints:

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

JSON Response

{
  "object": "related_party",
  "id": "relp_3c1f0c0b0f15474e90baf9f32692c6eb",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "name": "Ram Sharma",
  "relationship": "son",
  "date_of_birth": "2002-02-29",
  "pan": "ASFPJ2398R",
  "guardian_name": null,
  "guardian_pan": null,
  "created_at": "2022-12-06T12:26:41+05:30",
  "aadhaar_number": null,
  "passport_number": null,
  "driving_licence_number": null,
  "email_address": "ram@gmail.com",
  "phone_number": {
    "isd": "+91",
    "number": "9092390923"
  },
  "address": {
    "line1": "213, 1st cross, JP Nagar",
    "line2": null,
    "line3": null,
    "city": "Bengaluru",
    "state": "Karnataka",
    "postal_code": "560102",
    "country": "in"
  },
  "guardian_aadhaar_number": null,
  "guardian_passport_number": null,
  "guardian_driving_licence_number": null,
  "guardian_email_address": null,
  "guardian_phone_number": null,
  "guardian_address": null
}

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

Name Type Comments
object string Value is related_party. String representing the object type. Objects of the same type share the same value
id string Unique identifier of the related_party object
profile string ID of the Investor profile to which this party is related to
name string Name of the related party
relationship string Relation of this party with the investor. Allowed values are father, mother, court_appointed_legal_guardian, aunt, brother_in_law,brother, daughter, daughter_in_law, father_in_law, grand_daughter, grand_father, grand_mother, grand_son, mother_in_law, nephew, niece, sister, sister_in_law, son, son_in_law, spouse, uncle, others
date_of_birth date Date of birth of the related party
pan string PAN of the related party
guardian_name string Name of the Guardian if the related party is a minor
This should not be same as Name in Investor profile object
guardian_pan string PAN of the Guardian if the related party is a minor
This should not be same as PAN in Investor profile object
created_at string Creation timestamp
aadhaar_number string Last 4 digits of related party's Aadhaar number
passport_number string Passport number of the related party
driving_licence_number string Driving Licence number of the related party
email_address string Email address of the related party
phone_number hash Phone number of the related party
address hash Address of the related party
guardian_aadhaar_number string Last 4 digits of guardian's Aadhaar number if the related party is a minor
guardian_passport_number string Passport number of the guardian if the related party is a minor
guardian_driving_licence_number string Driving Licence number of the guardian if the related party is a minor
guardian_email_address string Email address of the guardian if the related party is a minor
guardian_phone_number hash Phone number of the guardian if the related party is a minor
guardian_address hash Address of the guardian if the related party is a minor 
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": "Ram Sharma",
  "date_of_birth": "2002-02-29",
  "relationship": "son"
}

JSON Response

{
  "object": "related_party",
  "id": "relp_3c1f0c0b0f15474e90baf9f32692c6eb",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "name": "Ram Sharma",
  "relationship": "son",
  "date_of_birth": "2002-02-29",
  "pan": null,
  "guardian_name": null,
  "guardian_pan": null,
  "created_at": "2022-12-06T12:26:41+05:30",
  "aadhaar_number": null,
  "passport_number": null,
  "driving_licence_number": null,
  "email_address": null,
  "phone_number": null,
  "address": null,
  "guardian_aadhaar_number": null,
  "guardian_passport_number": null,
  "guardian_driving_licence_number": null,
  "guardian_email_address": null,
  "guardian_phone_number": null,
  "guardian_address": null
}

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.
relationship yes enum Relation of this party with the investor. Allowed values are father, mother, court_appointed_legal_guardian, aunt, brother_in_law,brother, daughter, daughter_in_law, father_in_law, grand_daughter, grand_father, grand_mother, grand_son, mother_in_law, nephew, niece, sister, sister_in_law, son, son_in_law, spouse, uncle, others

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.
pan no string PAN of the related party. Can be given only if related party age > 18 years

Once set, this cannot be modified.
guardian_name no string Name of the related party's guardian. Can be given only if related party age < 18 years. 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. Can be given only if related party age < 18 years.

Once set, this cannot be modified.
aadhaar_number no string Last 4 digits of related party's Aadhaar number. Can be given only if relatedparty age > 18 years

Once set, this cannot be modified.
passport_number no string Passport number of the related party. Can be given only if related party age > 18 years

Once set, this cannot be modified.
driving_licence_number no string Driving Licence number of the related party. Can be given only if related party age > 18 years

Once set, this cannot be modified.
email_address no string Email address of the related party. Can be given only if related party age > 18 years

Once set, this cannot be modified.
phone_number no hash Phone number of the related party. Can be given only if related party age > 18 years

Once set, this cannot be modified.
address no hash Address of the related party. Can be given only if related party age > 18 years

Once set, this cannot be modified.
guardian_aadhaar_number no string Last 4 digits of guardian's Aadhaar number. Can be given only if related party age < 18 years.

Once set, this cannot be modified.
guardian_passport_number no string Passport number of the Guardian. Can be given only if related party age < 18 years.

Once set, this cannot be modified.
guardian_driving_licence_number no string Driving Licence number of the Guardian. Can be given only if related party age < 18 years.

Once set, this cannot be modified.
guardian_email_address no string Email address of the Guardian. Can be given only if related party age < 18 years.

Once set, this cannot be modified.
guardian_phone_number no hash Phone number of the Guardian. Can be given only if related party age < 18 years.

Once set, this cannot be modified.
guardian_address no hash Address of the Guardian. Can be given only if related party age < 18 years.

Once set, this cannot be modified.

Phone Number / Guardian Phone Number hash attributes

Name Mandatory Type Comments
isd yes string ISD code of the phone number. Only integers are allowed, also + can be added at the start
number yes string Phone number. Only integers and - are allowed

Address / Guardian Address hash attributes

Name Mandatory Type Comments
line1 yes string Address line 1. Mandatory
line2 no string Address line 2
line3 no string Address line 3
city no string City
state no string State
postal_code yes string Pincode. Mandatory
country yes string Country ANSI Code. Mandatory

NOTE: Any one among the supported identity proofs should be collected for a related party (or guardian in case of minor related party) before attempting a new folio creation request. 

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",
  "_comment": "Upcoming attributes listed below",
  "email_address": "ram@gmail.com",
  "phone_number": {
    "isd": "+91",
    "number": "9092390923"
  },
  "address": {
    "line1": "213, 1st cross, JP Nagar",
    "postal_code": "560102",
    "country": "in"
  }
}

JSON Response

{
  "object": "related_party",
  "id": "relp_3c1f0c0b0f15474e90baf9f32692c6eb",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "name": "Ram Sharma",
  "relationship": "son",
  "date_of_birth": "2002-02-29",
  "pan": "ASFPJ2398R",
  "guardian_name": null,
  "guardian_pan": null,
  "created_at": "2022-12-06T12:26:41+05:30",
  "aadhaar_number": null,
  "passport_number": null,
  "driving_licence_number": null,
  "email_address": "ram@gmail.com",
  "phone_number": {
    "isd": "+91",
    "number": "9092390923"
  },
  "address": {
    "line1": "213, 1st cross, JP Nagar",
    "line2": null,
    "line3": null,
    "city": "Bengaluru",
    "state": "Karnataka",
    "postal_code": "560102",
    "country": "in"
  },
  "guardian_aadhaar_number": null,
  "guardian_passport_number": null,
  "guardian_driving_licence_number": null,
  "guardian_email_address": null,
  "guardian_phone_number": null,
  "guardian_address": null
}

PATCH /v2/related_parties

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

Body parameters

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

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

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

JSON Response

{
  "object": "related_party",
  "id": "relp_3c1f0c0b0f15474e90baf9f32692c6eb",
  "profile": "invp_9abd706565144b83947f4b498bc95e98",
  "name": "Ram Sharma",
  "relationship": "son",
  "date_of_birth": "2002-02-29",
  "pan": "ASFPJ2398R",
  "guardian_name": null,
  "guardian_pan": null,
  "created_at": "2022-12-06T12:26:41+05:30",
  "aadhaar_number": null,
  "passport_number": null,
  "driving_licence_number": null,
  "email_address": "ram@gmail.com",
  "phone_number": {
    "isd": "+91",
    "number": "9092390923"
  },
  "address": {
    "line1": "213, 1st cross, JP Nagar",
    "line2": null,
    "line3": null,
    "city": "Bengaluru",
    "state": "Karnataka",
    "postal_code": "560102",
    "country": "in"
  },
  "guardian_aadhaar_number": null,
  "guardian_passport_number": null,
  "guardian_driving_licence_number": null,
  "guardian_email_address": null,
  "guardian_phone_number": null,
  "guardian_address": null
}

GET /v2/related_parties/:id

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

Query parameters

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

JSON Response

{
  "object": "list",
  "data": [
    {
      "object": "related_party",
      "id": "relp_3c1f0c0b0f15474e90baf9f32692c6eb",
      "profile": "invp_9abd706565144b83947f4b498bc95e98",
      "name": "Ram Sharma",
      "relationship": "son",
      "date_of_birth": "2002-02-29",
      "pan": null,
      "guardian_name": null,
      "guardian_pan": null,
      "created_at": "2022-12-06T12:26:41+05:30",
      "aadhaar_number": null,
      "passport_number": null,
      "driving_licence_number": null,
      "email_address": null,
      "phone_number": null,
      "address": null,
      "guardian_aadhaar_number": null,
      "guardian_passport_number": null,
      "guardian_driving_licence_number": null,
      "guardian_email_address": null,
      "guardian_phone_number": null,
      "guardian_address": null
    }
  ]
}

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

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",
    "nominee1_identity_proof_type": "pan",
    "nominee1_guardian_identity_proof_type": null,
    "nominee2_identity_proof_type": null,
    "nominee2_guardian_identity_proof_type": null,
    "nominee3_identity_proof_type": null,
    "nominee3_guardian_identity_proof_type": null,
    "nominations_info_visibility": "show_all_nominee_names"
  },
  "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
nominee1_identity_proof_type enum Mandatory if the nominee is not a minor. Allowed values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
nominee1_guardian_identity_proof_type enum Mandatory if the nominee is a minor. Supported values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
nominee2_identity_proof_type enum Mandatory if the nominee is not a minor. Allowed values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
nominee2_guardian_identity_proof_type enum Mandatory if the nominee is a minor. Supported values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
nominee3_identity_proof_type enum Mandatory if the nominee is not a minor. Allowed values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
nominee3_guardian_identity_proof_type enum Mandatory if the nominee is a minor. Supported values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
nominations_info_visibility enum Declaration on whether the investor wants to display nomination status or all nominees' names on the statement of accounts.Allowed values are - show_all_nominee_names, show_nomination_status

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,
    "nominee1_identity_proof_type": null,
    "nominee1_guardian_identity_proof_type": null,
    "nominee2_identity_proof_type": null,
    "nominee2_guardian_identity_proof_type": null,
    "nominee3_identity_proof_type": null,
    "nominee3_guardian_identity_proof_type": null,
    "nominations_info_visibility": null
  },
  "created_at": "2020-04-06T15:32:52+05:30"
}

Request Parameters

Name Mandatory Type Comments
primary_investor yes string Investor profile ID of the first holder.
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
nominee1_identity_proof_type no enum Mandatory if the nominee is not a minor. Allowed values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
nominee1_guardian_identity_proof_type no enum Mandatory if the nominee is a minor. Supported values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
nominee2_identity_proof_type no enum Mandatory if the nominee is not a minor. Allowed values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
nominee2_guardian_identity_proof_type no enum Mandatory if the nominee is a minor. Supported values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
nominee3_identity_proof_type no enum Mandatory if the nominee is not a minor. Allowed values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
nominee3_guardian_identity_proof_type no enum Mandatory if the nominee is a minor. Supported values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
nominations_info_visibility no enum Declaration on whether the investor wants to display nomination status or all nominees' names on the statement of accounts. Allowed values are - show_all_nominee_names, show_nomination_status

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",
    "_comment": "Upcoming attributes listed below",
    "nominee1_identity_proof_type": null,
    "nominations_info_visibility": "show_all_nominee_names"
  }
}

    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",
    "nominee1_identity_proof_type": "pan",
    "nominee1_guardian_identity_proof_type": null,
    "nominee2_identity_proof_type": null,
    "nominee2_guardian_identity_proof_type": null,
    "nominee3_identity_proof_type": null,
    "nominee3_guardian_identity_proof_type": null,
    "nominations_info_visibility": "show_all_nominee_names"
  },
  "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 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.
    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
    nominee1_identity_proof_type no enum Mandatory if the nominee is not a minor. Allowed values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
    nominee1_guardian_identity_proof_type no enum Mandatory if the nominee is a minor. Supported values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
    nominee2_identity_proof_type no enum Mandatory if the nominee is not a minor. Allowed values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
    nominee2_guardian_identity_proof_type no enum Mandatory if the nominee is a minor. Supported values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
    nominee3_identity_proof_type no enum Mandatory if the nominee is not a minor. Allowed values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
    nominee3_guardian_identity_proof_type no enum Mandatory if the nominee is a minor. Supported values are pan / aadhaar / driving_licence / passport. The respective proof number should be specified in the mentioned related_party for the proof type given here
    nominations_info_visibility no enum Declaration on whether the investor wants to display nomination status or all nominees' names on the statement of accounts. Allowed values are - show_all_nominee_names, show_nomination_status

    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",
    "nominee1_identity_proof_type": "pan",
    "nominee1_guardian_identity_proof_type": null,
    "nominee2_identity_proof_type": null,
    "nominee2_guardian_identity_proof_type": null,
    "nominee3_identity_proof_type": null,
    "nominee3_guardian_identity_proof_type": null,
    "nominations_info_visibility": "show_all_nominee_names"
  },
  "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",
        "nominee1_identity_proof_type": "pan",
        "nominee1_guardian_identity_proof_type": null,
        "nominee2_identity_proof_type": null,
        "nominee2_guardian_identity_proof_type": null,
        "nominee3_identity_proof_type": null,
        "nominee3_guardian_identity_proof_type": null,
        "nominations_info_visibility": "show_all_nominee_names"
      },
      "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,
        "nominee1_identity_proof_type": null,
        "nominee1_guardian_identity_proof_type": null,
        "nominee2_identity_proof_type": null,
        "nominee2_guardian_identity_proof_type": null,
        "nominee3_identity_proof_type": null,
        "nominee3_guardian_identity_proof_type": null,
        "nominations_info_visibility": null
      },
      "created_at": "2020-04-06T15:32:52+05:30"
    }
  ]
}

    Query Parameters

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

    Note:

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

    Introduction to MF Orders

    Orders Overview

    FP supports 3 types of mutual fund orders -

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

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

    Note

    Order States

    State Remarks
    under_review The order is created and sent to the ondc gateway for review
    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": "ondc",
  "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: under_review, 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
    mf_folio_input_detail string This is the ID of the folio input detail object. This is required for folio created outside FP-ONDC
    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: ondc
    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 the end user who has initiated the transaction. This should be in IPv4 format. Eg., n.n.n.n where n can have a value between 0 - 255
    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. Note: Sub-broker transactions are yet to be suported via ondc gateway.
    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

    1. When you create an order using Create MF Purchase API, the order will be in under_review state. The gateway will asynchronously review the order details in the background. If this review passes, the order is marked as pending and mf_purchase.review_completed event is delivered. Else, the order is marked as failed.
    2. Once the order is pending state, consent can be obtained from the investor and updated against mf_purchase.
    3. Post consent updation, payment can be created against the order.
    4. Post payment creation, order should be marked as confirmed
    5. When the order is confirmed, it will be submitted to the gateway and upon successful submission, the order is marked as submitted
    6. Once the order is submitted, you can redirect the investor to collect payment against the purchase order.

    Order expiry

    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,
  "gateway": "ondc"
}

    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": "ondc",
  "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 yes 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
    gateway no string See Details Here

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

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

    Create batch purchase orders

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

    JSON Request:

    {
  "mf_purchases": [
    {
      "amount": 1000,
      "mf_investment_account": "mfia_3cb50e9b04484e6f898e3d12a0c30926",
      "scheme": "INF109K01RT3",
      "gateway": "ondc"
    }
  ]
}

    JSON Response:

    {
  "object": "list",
  "data": [
    {
      "object": "mf_purchase",
      "id": "mfp_9d20c1a9308b4e50a82e271402290766",
      "old_id": 1571,
      "mf_investment_account": "mfia_3cb50e9b04484e6f898e3d12a0c30926",
      "folio_number": null,
      "state": "under_review",
      "amount": 1000.0,
      "gateway": "ondc",
      "traded_on": null,
      "scheduled_on": "2025-02-25",
      "created_at": "2025-02-25T10:21:03+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "confirmed_at": null,
      "retried_at": null,
      "cancelled_at": null,
      "source_ref_id": null,
      "user_ip": null,
      "server_ip": "127.0.0.1",
      "plan": null,
      "initiated_by": null,
      "initiated_via": null,
      "euin": "E457992",
      "partner": null,
      "failure_code": null,
      "order_reference": null,
      "type": "purchase",
      "scheme": "INF109K01RT3",
      "allotted_units": null,
      "purchased_amount": null,
      "purchased_price": null
    }
  ]
}

    POST v2/mf_purchases/batch

    If you intend to create multiple purchase orders against a given investment account and route it via ondc order gateway and collect single payment against these orders, you must use this API.

    Request Parameters

    Name Mandatory Type Comments
    mf_purchases yes List Provide a list of mf_purchases to be created. Please refer to Create MF Purchase documentation to understand the structure of each mf_purchase request.
    Maximum of 10 orders can be created

    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": "ondc",
  "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 for ondc gateway

    1. The purchase order needs to be first updated with consent only.
    2. Post the consent updation, payment must be created against the order and then the order should be marked as confirmed.
    3. When the order is marked as confirmed, the order will be submitted to the gateway and upon successful submission, the order is marked as submitted
    4. Currently, only folios created via the ONDC gateway are accepted. Folios created outside ONDC cannot be used.
    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": "ondc",
  "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.
    consent Conditional hash Consent from investor for confirming the purchase order.
    Once set, this cannot be modified.

    Note: For ondc order gateway purchase orders, you cannot update state and consent simulatenously.

    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, 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 batch purchase orders

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

    JSON Request:

    {
  "mf_purchases": [
    {
      "id": "mfp_177177219f634373b01072986d2eea7d",
      "state": "confirmed"
    },
    {
      "id": "mfp_276179219f634373b01072986d2eea9a",
      "state": "confirmed"
    }
  ]
}

    JSON Response:

    {
  "object": "list",
  "data": [
    {
      "object": "mf_purchase",
      "id": "mfp_177177219f634373b01072986d2eea7d",
      "old_id": 1571,
      "mf_investment_account": "mfia_3cb50e9b04484e6f898e3d12a0c30926",
      "folio_number": null,
      "state": "confirmed",
      "amount": 1000.0,
      "gateway": "ondc",
      "traded_on": null,
      "scheduled_on": "2025-02-25",
      "created_at": "2025-02-25T10:21:03+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "confirmed_at": "2025-02-25T11:21:03+05:30",
      "retried_at": null,
      "cancelled_at": null,
      "source_ref_id": null,
      "user_ip": null,
      "server_ip": "127.0.0.1",
      "plan": null,
      "initiated_by": null,
      "initiated_via": null,
      "euin": "E457992",
      "partner": null,
      "failure_code": null,
      "order_reference": null,
      "type": "purchase",
      "scheme": "INF109K01RT3",
      "allotted_units": null,
      "purchased_amount": null,
      "purchased_price": null
    },
    {
      "object": "mf_purchase",
      "id": "mfp_276179219f634373b01072986d2eea9a",
      "old_id": 1571,
      "mf_investment_account": "mfia_3cb50e9b04484e6f898e3d12a0c30926",
      "folio_number": null,
      "state": "confirmed",
      "amount": 1000.0,
      "gateway": "ondc",
      "traded_on": null,
      "scheduled_on": "2025-02-25",
      "created_at": "2025-02-25T10:21:03+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "confirmed_at": "2025-02-25T11:21:03+05:30",
      "retried_at": null,
      "cancelled_at": null,
      "source_ref_id": null,
      "user_ip": null,
      "server_ip": "127.0.0.1",
      "plan": null,
      "initiated_by": null,
      "initiated_via": null,
      "euin": "E457992",
      "partner": null,
      "failure_code": null,
      "order_reference": null,
      "type": "purchase",
      "scheme": "INF109K01RT3",
      "allotted_units": null,
      "purchased_amount": null,
      "purchased_price": null
    }
  ]
}

    PATCH v2/mf_purchases/batch

    You can utilise this API to update the batch order created using Batch purchase order API to confirmed state.

    Request Parameters

    Name Mandatory Type Comments
    mf_purchases yes List Provide a list of mf_purchases to be confirmed. Please refer to Update a MF Purchase documentation to understand the structure of each mf_purchase request

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

    MF Redemptions

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

    1. A lump sum redemption order

    Endpoints:

    POST /v2/mf_redemptions
    PATCH /v2/mf_redemptions
    GET /v2/mf_redemptions/:id
    GET /v2/mf_redemptions
    POST /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": "ondc",
  "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,under_review, 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 redemption 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: 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: ondc.
    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 the end user who has initiated the transaction. This should be in IPv4 format. Eg., n.n.n.n where n can have a value between 0 - 255
    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. Note: Ability to capture sub-broker code for redemptions via ondc gateway is not yet supported.
    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 for ondc gateway

    1. When you create an order using Create MF Redemption API, the order will be in under_review state. The gateway will asynchronously review the order details in the background. If this review passes, the order is marked as pending and mf_redemption.review_completed event is delivered. Else, the order is marked as failed.
    2. Once the order is pending state, consent can be obtained from the investor and mark mf_redemption as confirmed by use Update a MF Redemption API.
    3. When the order is confirmed, it will be submitted to the gateway and upon successful submission, the order is marked as submitted
    4. For the ondc gateway, redemption orders can only be placed for folios that are created using ONDC gateway.

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

    Note on Instant Redemptions for UTI AMC:

    1. When redemption_mode is set as instant for a UTI AMC scheme, consent must be collected as part of the mf_redemption create request only.
    2. For UTI AMC instant redemptions, for consent collection purposes please ensure that authentication only happens by verifying the OTP sent to mobile number registered against folio only. Authentication via Email-OTP is not supported.
    3. The distributor is responsible for:
      • Successfully authenticating investor via Mobile-OTP according to SEBI 2FA guidelines, and
      • Including the verified OTP used for authentication during consent collection in the mf_redemption create request.

    Note on Instant Redemptions for Nippon AMC:

    1. When redemption_mode is set as instant for a Nippon AMC scheme, consent must be collected as part of the mf_redemption create request only.
    2. For Nippon AMC instant redemptions, for consent collection purposes please ensure that authentication only happens by verifying the OTP sent to mobile number registered against folio only. Authentication via Email-OTP is not supported.
    3. The distributor is responsible for:
      • Successfully authenticating investor via Mobile-OTP according to SEBI 2FA guidelines, and
      • Including the verified OTP used for authentication during consent collection in the mf_redemption create request.
    4. There is a 30-minute restriction between consecutive instant redemption orders for the same PAN + Folio + Scheme combination. If a new order is initiated within 30 minutes of the previous order, it will be marked as failed with the failure_code: duplicate_instant_redemption_request
    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": "ondc",
  "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 yes string IP address of the end user who has initiated the transaction. This should be in IPv4 format. Eg., n.n.n.n where n can have a value between 0 - 255
    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
    gateway no string See Details Here

    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",
    "otp": "123321"
  }
}

    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": "ondc",
  "initiated_by": "investor",
  "initiated_via": "web",
  "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1"
}

    Request Parameters

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

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

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

    Only integers and - are allowed
    Min and Max character length is 7 and 20
    otp conditional string Mandatory if redemption_mode is instant.
    The value must be one used for consent.

    Only integers are allowed
    Min and Max character length is 4 and 20

    Fetch a MF Redemption

    GET /v2/mf_redemptions/:id

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

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

    Query Parameters

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

    JSON Response:

    {
  "object": "mf_redemption",
  "id": "mfr_15f8d86bae614801bab5accaed131abc",
  "old_id": 6597,
  "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
  "folio_number": "15075102",
  "state": "pending",
  "amount": 10000.0,
  "scheme": "INF173K01FQ0",
  "redemption_mode": "normal",
  "traded_on": null,
  "failed_at": null,
  "plan": null,
  "euin": null,
  "partner": "ptnr_20751c37c0a548c3baf12a18bc72187b",
  "failure_code": null,
  "units": null,
  "redeemed_price": null,
  "redeemed_units": null,
  "redeemed_amount": null,
  "redemption_bank_account_number": null,
  "redemption_bank_account_ifsc_code": null,
  "scheduled_on": "2020-04-07",
  "created_at": "2020-04-07T14:50:23+05:30",
  "confirmed_at": null,
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "cancelled_at": null,
  "gateway": "ondc",
  "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_plan",
      "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "active",
      "installment_type": "systematic_withdrawal_installment",
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "transaction_day": 1,
      "start_date": "2021-04-01",
      "end_date": "2021-11-01",
      "number_of_installments": 7,
      "next_installment_date": "2021-06-01",
      "previous_installment_date": "2021-05-01",
      "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",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "gateway": "ondc",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null
    },
    {
      "object": "mf_redemption_plan",
      "id": "mfrp_1ba5b25b534c48329dbfbeff70c846f0",
      "state": "active",
      "installment_type": "systematic_withdrawal_installment",
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "5234567890",
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "transaction_day": 1,
      "start_date": "2021-04-01",
      "end_date": "2021-11-01",
      "number_of_installments": 7,
      "next_installment_date": "2021-06-01",
      "previous_installment_date": "2021-05-01",
      "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",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "gateway": "ondc",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null
    }
  ]
}

    Query Parameters

    Name Mandatory Type Comments
    mf_investment_account no string The investment account against which the redemptions are made.
    states no string Comma separated values of redemption states

    Note:

    The response can contain 100 latest orders at max.

    Pre redemption summary

    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,
      "min_instant_redemption_amount": 100
    }
  ]
}

    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
    min_instant_redemption_amount numeric Minimum permissible amount available for instant redemption today for the given investment account

    List Pre redemption summary

    POST /v2/mf_redemptions/summary

    curl -X POST "https://s.finprim.com/v2/mf_redemptions/summary"
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{
    "mf_investment_account": "mfia_fe9348c57a4a04eaca50deb684cb502",
    "folio": "15075102",
    "scheme": "INF209K01RU9",
    "gateway": "ondc",
    "mobile": "<mobile number>"
  }'

    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,
      "min_instant_redemption_amount": 100
    }
  ]
}

    Request 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
    gateway conditional string Required for UTI and Nippon AMC schemes, this value must be set to ondc.
    mobile conditional string Required for UTI and Nippon AMC schemes, the value must be the mobile number registered against the folio.

    List Pre redemption summary (To be Deprecated)

    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,
      "min_instant_redemption_amount": 100
    }
  ]
}

    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
    gateway conditional string Required for UTI and Nippon AMC schemes, this value must be set to ondc.
    mobile conditional string Required for UTI and Nippon AMC schemes, the value must be the mobile number registered against the folio.

    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": "ondc",
  "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": "10.0.128.12",
  "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: ondc
    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 the end user who has initiated the transaction. This should be in IPv4 format. Eg., n.n.n.n where n can have a value between 0 - 255
    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": "ondc",
  "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": "10.0.128.12",
  "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 yes string IP address of the end user who has initiated the transaction. This should be in IPv4 format. Eg., n.n.n.n where n can have a value between 0 - 255
    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": "ondc",
  "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": "10.0.128.12",
  "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": "ondc",
  "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": "10.0.128.12",
  "server_ip": null,
  "initiated_by": "investor",
  "initiated_via": "web",
  "euin": null,
  "partner": null,
  "failure_code": null
}

    Request Parameters

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

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

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

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

    Fetch a MF Switch

    GET /v2/mf_switches/:id

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

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

    Query Parameters

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

    JSON Response:

    {
  "object": "mf_switch",
  "id": "mfs_b1aba06d52184619151d3b82efa65de6",
  "old_id": 16586,
  "mf_investment_account": "mfia_167a75826694614a539c0f82b196027",
  "folio_number": "39171511",
  "state": "pending",
  "amount": 1000.0,
  "units": null,
  "switch_out_scheme": "INF173K01FE6",
  "switch_in_scheme": "INF173K02FE5",
  "plan": null,
  "switched_out_units": null,
  "switched_out_amount": null,
  "switched_out_price": null,
  "switched_in_units": null,
  "switched_in_amount": null,
  "switched_in_price": null,
  "gateway": "ondc",
  "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": "10.0.128.12",
  "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": "ondc",
      "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": "10.0.128.12",
      "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.

    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_a2d956440b354dcfaceadb8ac25e5d60",
  "mf_investment_account": "mfia_d8c1b501c10d4835947a5c77fc031789",
  "folio_number": null,
  "scheme": "INF109K01TP7",
  "amount": 21.0,
  "systematic": true,
  "frequency": "daily",
  "installment_day": null,
  "requested_activation_date": null,
  "number_of_installments": 6,
  "start_date": null,
  "end_date": null,
  "next_installment_date": null,
  "previous_installment_date": null,
  "remaining_installments": 6,
  "state": "review_completed",
  "auto_generate_installments": true,
  "payment_method": "mandate",
  "payment_source": "3",
  "purpose": null,
  "source_ref_id": null,
  "partner": null,
  "gateway": "ondc",
  "euin": "E609422",
  "user_ip": "10.0.128.12",
  "server_ip": null,
  "initiated_by": "investor",
  "initiated_via": "mobile_app",
  "created_at": "2025-05-23T14:00:15+05:30",
  "activated_at": null,
  "cancelled_at": null,
  "cancellation_scheduled_on": null,
  "cancellation_code": null,
  "auto_cancelled": null,
  "failed_at": null,
  "completed_at": null,
  "reason": null,
  "consent": {
    "email": null,
    "isd_code": null,
    "mobile": null,
    "otp": null
  }
}
    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
    mf_folio_input_detail string Yes This is the ID of the folio input detail object. This is required for folio created outside FP-ONDC
    partner string No See details here
    gateway string No See details here
    euin string Yes See details here
    user_ip string No 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
    consent hash No Consent from investor for confirming the order.
    Once set, this cannot be modified.

    Create a purchase plan

    POST /v2/mf_purchase_plans

    Note for ondc gateway

    1. For ondc gateway, Purchase plan has additional states of review_completed, confirmed and submitted along with the Transaction plans states
    2. When you create an Purchase Plan using Create MF Purchase Plan API, the plan will be in created state.
    3. The gateway will asynchronously review the order details in the background. If this review passes, the purchase plan is marked as review_completed and mf_purchase.review_completed event is delivered. Else, the plan is marked as failed.
    4. Consent can be obtained from the investor in parallel while waiting for the plan to be marked as review_completed.
    5. Once the Purchase Plan is in review_completed state, consent must updated against mf_purchase_plan and the plan state should be marked as confirmed using the Update MF Purchase Plan API.
    6. Please ensure that an APPROVED mandate is added as payment_source to the Plan before it is confirmed.
    7. When the Purchase Plan is confirmed, it will be submitted to the gateway and upon successful submission, the plan is marked as submitted and then moved to active state automatically.
    8. Currently the following frequencies are supported- daily, calendar_day_daily and monthly
    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_d8c1b501c10d4835947a5c77fc031789",
  "scheme": "INF109K01TP7",
  "frequency": "daily",
  "amount": 21,
  "number_of_installments": 6,
  "systematic": true,
  "payment_method": "mandate",
  "payment_source": "3",
  "auto_generate_installments": true,
  "initiated_by": "investor",
  "initiated_via": "mobile_app",
  "gateway": "ondc",
  "user_ip": "10.0.128.12"
}

    JSON Response:

    {
  "object": "mf_purchase_plan",
  "id": "mfpp_a2d956440b354dcfaceadb8ac25e5d60",
  "mf_investment_account": "mfia_d8c1b501c10d4835947a5c77fc031789",
  "folio_number": null,
  "scheme": "INF109K01TP7",
  "amount": 21.0,
  "systematic": true,
  "frequency": "daily",
  "installment_day": null,
  "requested_activation_date": null,
  "number_of_installments": 6,
  "start_date": null,
  "end_date": null,
  "next_installment_date": null,
  "previous_installment_date": null,
  "remaining_installments": 6,
  "state": "review_completed",
  "auto_generate_installments": true,
  "payment_method": "mandate",
  "payment_source": "3",
  "purpose": null,
  "source_ref_id": null,
  "partner": null,
  "gateway": "ondc",
  "euin": "E609422",
  "user_ip": "10.0.128.12",
  "server_ip": null,
  "initiated_by": "investor",
  "initiated_via": "mobile_app",
  "created_at": "2025-05-23T14:00:15+05:30",
  "activated_at": null,
  "cancelled_at": null,
  "cancellation_scheduled_on": null,
  "cancellation_code": null,
  "auto_cancelled": null,
  "failed_at": null,
  "completed_at": null,
  "reason": null,
  "consent": {
    "email": null,
    "isd_code": null,
    "mobile": null,
    "otp": null
  }
}

    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
    initiated_by No string See details here
    initiated_via No string See details here
    euin No string See details here
    user_ip Yes 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.

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

    Create batch purchase plans (Early access)

    Note: This facility is only available when order gateway is ondc

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

    JSON Request:

    {
  "mf_purchase_plans": [
    {
      "scheme": "INF109K01RT3",
      "mf_investment_account": "mfia_3e19430a7b07459b80e63ff3b8d37c76",
      "frequency": "daily",
      "amount": 1000,
      "systematic": "true",
      "generate_first_installment_now": true,
      "auto_generate_installments": true,
      "number_of_installments": 6,
      "payment_method": "mandate",
      "payment_source": "465",
      "user_ip": "192.168.1.1"
    },
    {
      "scheme": "INF109K01TP7",
      "mf_investment_account": "mfia_3e19430a7b07459b80e63ff3b8d37c76",
      "frequency": "daily",
      "amount": 1000,
      "systematic": "true",
      "generate_first_installment_now": true,
      "auto_generate_installments": true,
      "number_of_installments": 6,
      "payment_method": "mandate",
      "payment_source": "465",
      "user_ip": "192.168.1.1"
    }
  ]
}

    JSON Response:

    {
  "object": "list",
  "data": [
    {
      "object": "mf_purchase_plan",
      "id": "mfpp_ff7efd6e63504955b9a0af2119f1a0bc",
      "mf_investment_account": "mfia_3e19430a7b07459b80e63ff3b8d37c76",
      "folio_number": null,
      "scheme": "INF109K01RT3",
      "amount": 1000.0,
      "systematic": true,
      "frequency": "daily",
      "installment_day": null,
      "requested_activation_date": null,
      "number_of_installments": 6,
      "start_date": null,
      "end_date": null,
      "next_installment_date": null,
      "previous_installment_date": null,
      "remaining_installments": null,
      "state": "created",
      "auto_generate_installments": true,
      "payment_method": "mandate",
      "payment_source": "465",
      "purpose": null,
      "source_ref_id": null,
      "partner": null,
      "gateway": "ondc",
      "euin": "E957999",
      "user_ip": "192.168.1.1",
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null,
      "created_at": "2025-08-05T16:01:59+05:30",
      "activated_at": null,
      "cancelled_at": null,
      "cancellation_scheduled_on": null,
      "cancellation_code": null,
      "auto_cancelled": null,
      "failed_at": null,
      "completed_at": null,
      "reason": null,
      "consent": {
        "email": null,
        "isd_code": null,
        "mobile": null,
        "otp": null
      },
      "sub_partner_license_code": null
    },
    {
      "object": "mf_purchase_plan",
      "id": "mfpp_1f8f33630c9341a9864eaa942dc8beaa",
      "mf_investment_account": "mfia_3e19430a7b07459b80e63ff3b8d37c76",
      "folio_number": null,
      "scheme": "INF109K01TP7",
      "amount": 1000.0,
      "systematic": true,
      "frequency": "daily",
      "installment_day": null,
      "requested_activation_date": null,
      "number_of_installments": 6,
      "start_date": null,
      "end_date": null,
      "next_installment_date": null,
      "previous_installment_date": null,
      "remaining_installments": null,
      "state": "created",
      "auto_generate_installments": true,
      "payment_method": "mandate",
      "payment_source": "443",
      "purpose": null,
      "source_ref_id": null,
      "partner": null,
      "gateway": "ondc",
      "euin": "E957999",
      "user_ip": "192.168.1.1",
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null,
      "created_at": "2025-08-05T16:01:59+05:30",
      "activated_at": null,
      "cancelled_at": null,
      "cancellation_scheduled_on": null,
      "cancellation_code": null,
      "auto_cancelled": null,
      "failed_at": null,
      "completed_at": null,
      "reason": null,
      "consent": {
        "email": null,
        "isd_code": null,
        "mobile": null,
        "otp": null
      },
      "sub_partner_license_code": null
    }
  ]
}

    POST /v2/mf_purchase_plans/batch

    If you intend to create multiple purchase plans against single or multiple investment account and route it via ondc order gateway and collect single payment against these orders, you must use this API.

    Request Parameters

    Name Mandatory Type Comments
    mf_purchase_plans yes List Provide a list of mf_purchase_plans to be created. Please refer to Create MF Purchase Plan documentation to understand the structure of each mf_purchase_plan request.

    Update a purchase plan

    PATCH /v2/mf_purchase_plans

    Note for ondc gateway (Early access)

    1. The purchase plan must to be updated with consent and the state must be updated to confirmed after the plan state is moved to review_completed.
    2. Please ensure that an APPROVED mandate is added as payment_source to the Plan before it is confirmed.
    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_a2d956440b354dcfaceadb8ac25e5d60",
  "state": "confirmed",
  "consent": {
    "email": "sridhar.acharya@abc.com",
    "isd_code": "91",
    "mobile": "9480000001"
  }
}

    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": "ondc",
  "user_ip": "10.0.128.12",
  "server_ip": null,
  "initiated_by": "investor",
  "initiated_via": "mobile_app",
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd_code": "91",
    "mobile": "9008580644"
  }
}

    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.
    state No string Applicable only for ondc gateway. Possible values: confirmed
    consent No hash Consent from investor for confirming the order
    Once set, this cannot be modified.

    Update batch purchase plans (Early access)

    Note: This facility is only available when order gateway is ondc

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

    JSON Request:

    {
  "mf_purchase_plans": [
    {
      "id": "mfpp_ff7efd6e63504955b9a0af2119f1a0bc",
      "state": "confirmed",
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd_code": "91",
        "mobile": "9008580644"
      }
    },
    {
      "id": "mfpp_1f8f33630c9341a9864eaa942dc8beaa",
      "state": "confirmed",
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd_code": "91",
        "mobile": "9008580644"
      }
    }
  ]
}

    JSON Response:

    {
  "object": "list",
  "data": [
    {
      "object": "mf_purchase_plan",
      "id": "mfpp_ff7efd6e63504955b9a0af2119f1a0bc",
      "mf_investment_account": "mfia_3e19430a7b07459b80e63ff3b8d37c76",
      "folio_number": null,
      "scheme": "INF109K01RT3",
      "amount": 1000.0,
      "systematic": true,
      "frequency": "daily",
      "installment_day": null,
      "requested_activation_date": null,
      "number_of_installments": 6,
      "start_date": "2025-08-06",
      "end_date": null,
      "next_installment_date": null,
      "previous_installment_date": null,
      "remaining_installments": 6,
      "state": "confirmed",
      "auto_generate_installments": true,
      "payment_method": "mandate",
      "payment_source": "465",
      "purpose": null,
      "source_ref_id": null,
      "partner": null,
      "gateway": "ondc",
      "euin": "E957999",
      "user_ip": "192.168.1.1",
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null,
      "created_at": "2025-08-05T09:49:33+05:30",
      "activated_at": null,
      "cancelled_at": null,
      "cancellation_scheduled_on": null,
      "cancellation_code": null,
      "auto_cancelled": null,
      "failed_at": null,
      "completed_at": null,
      "reason": null,
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd_code": "91",
        "mobile": "9008580644",
        "otp": null
      },
      "sub_partner_license_code": null
    },
    {
      "object": "mf_purchase_plan",
      "id": "mfpp_1f8f33630c9341a9864eaa942dc8beaa",
      "mf_investment_account": "mfia_3e19430a7b07459b80e63ff3b8d37c76",
      "folio_number": null,
      "scheme": "INF109K01TP7",
      "amount": 1000.0,
      "systematic": true,
      "frequency": "daily",
      "installment_day": null,
      "requested_activation_date": null,
      "number_of_installments": 6,
      "start_date": "2025-08-06",
      "end_date": null,
      "next_installment_date": null,
      "previous_installment_date": null,
      "remaining_installments": 6,
      "state": "confirmed",
      "auto_generate_installments": true,
      "payment_method": "mandate",
      "payment_source": "465",
      "purpose": null,
      "source_ref_id": null,
      "partner": null,
      "gateway": "ondc",
      "euin": "E957999",
      "user_ip": "192.168.1.1",
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null,
      "created_at": "2025-08-05T09:49:33+05:30",
      "activated_at": null,
      "cancelled_at": null,
      "cancellation_scheduled_on": null,
      "cancellation_code": null,
      "auto_cancelled": null,
      "failed_at": null,
      "completed_at": null,
      "reason": null,
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd_code": "91",
        "mobile": "9008580644",
        "otp": null
      },
      "sub_partner_license_code": null
    }
  ]
}

    PATCH /v2/mf_purchase_plans/batch

    Note for ondc gateway (Early access)

    1. You can utilise this API to update the batch order created using Batch purchase plans API to confirmed state.
    2. Please ensure that an APPROVED mandate is added as payment_source to the Plan before it is confirmed.

    Request Parameters

    Name Mandatory Type Comments
    mf_purchase_plans yes List Provide a list of mf_purchase_plans to be confirmed. Please refer to Update a Purchase Plan documentation to understand the structure of each mf_purchase_plan request

    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_a2d956440b354dcfaceadb8ac25e5d60",
  "mf_investment_account": "mfia_d8c1b501c10d4835947a5c77fc031789",
  "folio_number": null,
  "scheme": "INF109K01TP7",
  "amount": 21.0,
  "systematic": true,
  "frequency": "daily",
  "installment_day": null,
  "requested_activation_date": null,
  "number_of_installments": 6,
  "start_date": null,
  "end_date": null,
  "next_installment_date": null,
  "previous_installment_date": null,
  "remaining_installments": 6,
  "state": "review_completed",
  "auto_generate_installments": true,
  "payment_method": "mandate",
  "payment_source": "3",
  "purpose": null,
  "source_ref_id": null,
  "partner": null,
  "gateway": "ondc",
  "euin": "E609422",
  "user_ip": "10.0.128.12",
  "server_ip": null,
  "initiated_by": "investor",
  "initiated_via": "mobile_app",
  "created_at": "2025-05-23T14:00:15+05:30",
  "activated_at": null,
  "cancelled_at": null,
  "cancellation_scheduled_on": null,
  "cancellation_code": null,
  "auto_cancelled": null,
  "failed_at": null,
  "completed_at": null,
  "reason": null,
  "consent": {
    "email": null,
    "isd_code": null,
    "mobile": null,
    "otp": null
  }
}

    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_a2d956440b354dcfaceadb8ac25e5d60",
      "mf_investment_account": "mfia_d8c1b501c10d4835947a5c77fc031789",
      "folio_number": null,
      "scheme": "INF109K01TP7",
      "amount": 21.0,
      "systematic": true,
      "frequency": "daily",
      "installment_day": null,
      "requested_activation_date": null,
      "number_of_installments": 6,
      "start_date": null,
      "end_date": null,
      "next_installment_date": null,
      "previous_installment_date": null,
      "remaining_installments": 6,
      "state": "review_completed",
      "auto_generate_installments": true,
      "payment_method": "mandate",
      "payment_source": "3",
      "purpose": null,
      "source_ref_id": null,
      "partner": null,
      "gateway": "ondc",
      "euin": "E609422",
      "user_ip": "10.0.128.12",
      "server_ip": null,
      "initiated_by": "investor",
      "initiated_via": "mobile_app",
      "created_at": "2025-05-23T14:00:15+05:30",
      "activated_at": null,
      "cancelled_at": null,
      "cancellation_scheduled_on": null,
      "cancellation_code": null,
      "auto_cancelled": null,
      "failed_at": null,
      "completed_at": null,
      "reason": null,
      "consent": {
        "email": null,
        "isd_code": null,
        "mobile": null,
        "otp": null
      }
    },
    {
      "object": "mf_purchase_plan",
      "id": "mfpp_a2d956440b354dcfaceadb8ac25e5d60",
      "mf_investment_account": "mfia_d8c1b501c10d4835947a5c77fc031789",
      "folio_number": null,
      "scheme": "INF109K01TP7",
      "amount": 21.0,
      "systematic": true,
      "frequency": "daily",
      "installment_day": null,
      "requested_activation_date": null,
      "number_of_installments": 6,
      "start_date": "2025-05-26",
      "end_date": "2025-06-02",
      "next_installment_date": "2025-05-26",
      "previous_installment_date": null,
      "remaining_installments": 6,
      "state": "active",
      "auto_generate_installments": true,
      "payment_method": "mandate",
      "payment_source": "3",
      "purpose": null,
      "source_ref_id": null,
      "partner": null,
      "gateway": "ondc",
      "euin": "E609422",
      "user_ip": "10.0.128.12",
      "server_ip": null,
      "initiated_by": "investor",
      "initiated_via": "mobile_app",
      "created_at": "2025-05-23T14:00:15+05:30",
      "activated_at": "2025-05-23T14:22:59+05:30",
      "cancelled_at": null,
      "cancellation_scheduled_on": null,
      "cancellation_code": null,
      "auto_cancelled": null,
      "failed_at": null,
      "completed_at": null,
      "reason": null,
      "consent": {
        "email": "sridhar.acharya@abc.com",
        "isd_code": "91",
        "mobile": "9480000001",
        "otp": 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": "ondc",
  "user_ip": "10.0.128.12",
  "server_ip": null,
  "initiated_by": "investor",
  "initiated_via": "mobile_app",
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd_code": "91",
    "mobile": "9008580644"
  }
}

    Request Parameters

    Name Mandatory Type Comments
    id Yes string V2 plan ID
    cancellation_code Yes string Mandatory
    cancellation_reason Conditional String Provide custom cancellation reason. Should be accepted only when canellation_code is "custom_reason"

    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
    custom_reason Any reason other than above mentioned cancellation reasons

    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.

    Skip Installments via Skip Instructions(Upcoming)

    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 No The date till which the installments must be skipped
    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 Yes 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

    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": "ondc",
  "user_ip": "10.0.128.12",
  "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 No See details here
    server_ip string Yes See details here
    initiated_by string Yes See details here
    initiated_via string Yes See details here
    created_at timestamp No See details here
    activated_at timestamp Yes See details here
    cancelled_at timestamp Yes See details here
    cancellation_scheduled_on date Yes See details here
    failed_at timestamp Yes See details here
    completed_at timestamp Yes See details here
    reason string Yes See details here
    consent object No Consent from investor for confirming the redemption

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

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

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

    Create a redemption plan

    POST /v2/mf_redemption_plans

    Note for ondc gateway

    1. For ondc gateway, Redemption plan has additional states of review_completed, confirmed and submitted along with the Transaction plans states
    2. When you create an Redemption Plan using Create MF Redemption Plan API, the plan will be in created state.
    3. The gateway will asynchronously review the plan details in the background. If this review passes, the redemption plan is marked as review_completed. Else, the plan is marked as failed.
    4. Consent can be obtained from the investor in parallel while waiting for the plan to be marked as review_completed.
    5. Once the Redemption Plan is in review_completed state, consent must be updated against mf_redemption_plan and the plan state should be marked as confirmed using the Update MF Redemption Plan API.
    6. When the Redemption Plan is confirmed, it will be submitted to the gateway and upon successful submission, the plan is marked as submitted and then moved to active state automatically.
    7. Currently only monthly frequency is supported. Note: generate_installment_now=true option is not available for MF Redemption Plan.
    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": "10.0.128.12",
  "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": "ondc",
  "user_ip": "10.0.128.12",
  "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 Yes 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 for ondc gateway

    The redemption plan must to be updated with consent and the state must be updated to confirmed after the plan state is moved to review_completed. 

    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",
  "state": "confirmed",
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd_code": "91",
    "mobile": "9008580644"
  }
}

    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": "ondc",
  "user_ip": "10.0.128.12",
  "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 V2 plan ID
    state No string Applicable only for ondc gateway. Possible values: confirmed
    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": "ondc",
  "user_ip": "10.0.128.12",
  "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": "ondc",
      "user_ip": "10.0.128.12",
      "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": "ondc",
      "user_ip": "10.0.128.12",
      "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": "ondc",
  "user_ip": "10.0.128.12",
  "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": "ondc",
  "user_ip": "10.0.128.12",
  "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 No 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

    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

    Note for ondc gateway

    1. For ondc gateway, Switch plan has additional states of review_completed, confirmed and submitted along with the Transaction plans states
    2. When you create an Switch Plan using Create MF Switch Plan API, the plan will be in created state.
    3. The gateway will asynchronously review the plan details in the background. If this review passes, the switch plan is marked as review_completed. Else, the plan is marked as failed.
    4. Consent can be obtained from the investor in parallel while waiting for the plan to be marked as review_completed.
    5. Once the Switch Plan is in review_completed state, consent must be updated against mf_switch_plan and the plan state should be marked as confirmed using the Update MF Switch Plan API.
    6. When the Switch Plan is confirmed, it will be submitted to the gateway and upon successful submission, the plan is marked as submitted and then moved to active state automatically.
    7. Currently only monthly frequency is supported. Note: generate_installment_now=true option is not available for MF Switch Plan.
    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": "10.0.128.12",
  "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": "ondc",
  "user_ip": "10.0.128.12",
  "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 Yes 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 for ondc gateway

    The switch plan must to be updated with consent and the state must be updated to confirmed after the plan state is moved to review_completed. 

    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",
  "state": "confirmed",
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd_code": "91",
    "mobile": "9008580644"
  }
}

    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": "ondc",
  "user_ip": "10.0.128.12",
  "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 V2 plan ID
    state No string Applicable only for ondc gateway. Possible values: confirmed
    consent No hash Consent from investor for confirming the switch
    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": "ondc",
  "user_ip": "10.0.128.12",
  "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": "ondc",
      "user_ip": "10.0.128.12",
      "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": "ondc",
      "user_ip": "10.0.128.12",
      "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": "ondc",
  "user_ip": "10.0.128.12",
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null,
  "reason": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd_code": "91",
    "mobile": "9008580644"
  }
}

    MF Plan Modification Instructions

    MF Plan Modification Instructions can be used to modify active plans — SIP, SWP, and STP. They also support changing the mandate linked to an active SIP, as long as the mandate amount is greater than or equal to the SIP amount and the mandate is in an approved state.

    A single modification instruction performs either an amount change or a mandate change, not both. For an amount change, the amount object is populated and payment_method/payment_source are null. For a mandate change, payment_method is mandate, payment_source carries the old and new mandate references, and amount is null.

    Note- A mandate can be changed only once per plan.

    Plan Modification Instruction Object Structure

    {
  "object": "mf_plan_modification_instruction",
  "id": "mpmi_1591afb7435c45d5bffb19682ad778a8",
  "plan": "mfpp_3bc6eec0dc2c45f3a39cc646d8df111a",
  "state": "created",
  "amount": {
    "to": "40.00",
    "from": "20.00"
  },
  "payment_method": null,
  "payment_source": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd_code": "91",
    "mobile": "9008580644"
  },
  "created_at": "2025-07-01T21:11:45+05:30",
  "completed_at": null,
  "failed_at": null,
  "failure_reason": null
}
    Attribute Data type Can be null? Remarks
    object string No Object type identifier (Will always be mf_plan_modification_instruction)
    id string No Unique identifier for the modification instruction
    plan string No Reference to the associated plan ID
    state string No Current state of the modification. Possible values:
    - created: The modification instruction is created and will be processed internally.
    - completed: Plan modification completed.
    - failed: Plan modification did not happen.
    amount hash Yes Object showing amount change. Null for a mandate change instruction.
    payment_method string Yes Possible values: mandate. Null for an amount change instruction.
    payment_source hash Yes Object showing the mandate change. Null for an amount change instruction.
    consent hash No Consent from investor for confirming the plan modifications
    created_at string No Timestamp when instruction was created
    completed_at string Yes Timestamp when instruction was completed
    failed_at string Yes Timestamp when instruction failed
    failure_reason string Yes Reason for failure, if applicable

    Plan Amount / Mandate Change Details

    Every modification instruction records what the plan was changed from and what it was changed to. Depending on the type of instruction, this is captured under either amount (for an amount change) or payment_source (for a mandate change).

    Amount change — captured under amount

    Name Mandatory Type Comments
    amount.to yes decimal The revised amount that was requested to be applied to future installments of the plan through this modification instruction. If the instruction is successfully completed, this becomes the new installment amount. This change does not affect any past or already scheduled installments.
    amount.from yes decimal The installment amount that was active in the plan before this modification instruction was created. This value is recorded to provide context for the requested change and remains unchanged regardless of whether the instruction succeeds or fails.

    Mandate change — captured under payment_source

    Name Mandatory Type Comments
    payment_source.to yes integer The new mandate requested. Once the instruction completes, this mandate is used for all future installments. This change does not affect any past or already scheduled installments.
    payment_source.from yes integer The mandate that was linked to the plan before this change. This value is recorded to provide context for the requested change and remains unchanged regardless of whether the instruction succeeds or fails.

    Create a modification instruction

    POST /v2/mf_plan_modification_instructions

    curl --location 'https://s.finprim.com/v2/mf_plan_modification_instructions'
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
-- data '{
    "plan": "mfpp_3bc6eec0dc2c45f3a39cc646d8df111a",
     "amount":40,
    "consent": {
       "email": "mfp@cybrilla.com",
       "isd_code": "91",
       "mobile": "9008580644"
  }
}'

    JSON Response:

    {
  "object": "mf_plan_modification_instruction",
  "id": "mpmi_1591afb7435c45d5bffb19682ad778a8",
  "plan": "mfpp_3bc6eec0dc2c45f3a39cc646d8df111a",
  "state": "created",
  "amount": {
    "to": "40.00",
    "from": "20.00"
  },
  "payment_method": null,
  "payment_source": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd_code": "91",
    "mobile": "9008580644"
  },
  "created_at": "2025-07-01T21:11:45+05:30",
  "completed_at": null,
  "failed_at": null,
  "failure_reason": null
}

    Request Parameters

    Name Mandatory Type Comments
    plan Yes string V2 plan ID
    amount Conditional decimal The revised amount to be applied to future installments of the plan through this modification instruction. Mandatory for an amount change instruction.
    payment_method Conditional string Set as mandate for a mandate change instruction. Mandatory for a mandate change instruction.
    payment_source Conditional integer Reference to the new mandate to be linked to the plan. Mandatory for a mandate change instruction.
    consent Yes hash Consent from investor for confirming the plan modification instruction
    Once set, this cannot be modified.

    While modifying for a plan, 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 modification instruction

    GET /v2/mf_plan_modification_instructions/:id

    This API can be used to fetch a modification instruction by its ID.

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

    JSON Response:

    {
  "object": "mf_plan_modification_instruction",
  "id": "mpmi_1591afb7435c45d5bffb19682ad778a8",
  "plan": "mfpp_3bc6eec0dc2c45f3a39cc646d8df111a",
  "state": "created",
  "amount": {
    "to": "40.00",
    "from": "20.00"
  },
  "payment_method": null,
  "payment_source": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd_code": "91",
    "mobile": "9008580644"
  },
  "created_at": "2025-07-01T21:11:45+05:30",
  "completed_at": null,
  "failed_at": null,
  "failure_reason": null
}

    MF Folio Input Details

    MF Folio Input Details is required to place order against an external folios - folios created outside FP-ONDC, regardless of which distributor created them.
    If a folio has not been created via Cybrilla OPAT and such a folio has not been migrated on FP (i.e. no corresponding MF Folio object post migration), and if you still want to transact against such a folio, the details of such a folio can captured via mf_folio_input_details and used while placing mf_purchases / mf_purchase_plans against such a folio.

    Typical flow : Create Folio Input Details using mf_investment_account → Place Purchase Order/Purchase Plan with mf_folio_input_detail

    Note- MF Folio Input details is only available for: mf_purchases mf_purchase_plans

    MF Folio Input Detail Object Structure

    {
  "object": "mf_folio_input_detail",
  "id": "mffid_17287f789b484aea9f6a5afa437378b7",
  "mf_investment_account": "mfia_e1e8d5b60f944cd4a5d0a8e6dc2d21ed",
  "dp_id": null,
  "client_id": null,
  "primary_investor_name": "Tony Soprano",
  "tax_status": "resident_individual",
  "date_of_birth": "2002-01-30",
  "created_at": "2026-07-01T07:51:45+05:30",
  "updated_at": "2026-07-01T07:51:45+05:30"
}
    Attribute Data type Can be null? Remarks
    object string No Object type identifier (Will always be mf_folio_input_detail)
    id string No Unique identifier for the folio input detail
    mf_investment_account string No Reference to the associated MF investment account ID
    primary_investor_name string No Name of the primary investor for the folio
    tax_status string No Tax status of the primary investor. e.g. resident_individual
    date_of_birth string No Date of birth of the primary investor. e.g. 2002-01-30
    dp_id string Yes Depository participant ID
    client_id string Yes Client ID
    created_at string No Timestamp when the folio input detail was created
    updated_at string No Timestamp when the folio input detail was updated

    Create a MF Folio Input Detail

    POST /v2/mf_folio_input_details

    curl --location 'https://s.finprim.com/v2/mf_folio_input_details'
  -H "x-tenant-id: <tenant name>"
  -H "Authorization: Bearer ACCESS_TOKEN"
  --data '{
    "mf_investment_account": "mfia_e1e8d5b60f944cd4a5d0a8e6dc2d21ed",
    "primary_investor_name": "Tony Soprano",
    "tax_status": "resident_individual",
    "date_of_birth": "2002-01-30"
}'

    JSON Response:

    {
  "object": "mf_folio_input_detail",
  "id": "mffid_17287f789b484aea9f6a5afa437378b7",
  "mf_investment_account": "mfia_e1e8d5b60f944cd4a5d0a8e6dc2d21ed",
  "dp_id": null,
  "client_id": null,
  "primary_investor_name": "Tony Soprano",
  "tax_status": "resident_individual",
  "date_of_birth": "2002-01-30",
  "created_at": "2026-07-01T07:51:45+05:30",
  "updated_at": "2026-07-01T07:51:45+05:30"
}

    Request Parameters

    Name Mandatory Type Comments
    mf_investment_account Yes string Reference to the MF investment account against which the folio input detail is created
    primary_investor_name Yes string Name of the primary investor for the folio
    tax_status Yes string Tax status of the primary investor. e.g. resident_individual
    date_of_birth No string Date of birth of the primary investor. e.g. 2002-01-30
    dp_id No string Depository participant ID
    client_id No string Client ID

    Note - dp_id and client_id to be only provided in case of demat folios. Currently, demat folios are not supported over FP-ONDC

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

    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 value is CYBRILLAPOA

    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,
  "provider_name": "CYBRILLAPOA"
}
  '

    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 ₹1 min.
    limits are for per day.
    provider_name yes String Possible values is CYBRILLAPOA
    valid_from no String valid_from in yyyy-mm-dd format.
    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.
    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).

    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": "CYBRILLAPOA"
}

    GET /api/pg/mandates/:id

    This endpoint retrieves mandate info based on the mandate ID

    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": "CYBRILLAPOA"
    },
    {
      "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": "CYBRILLAPOA"
    }
  ]
}

    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

    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 value: ONDC
    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
  ],
  "bank_account_id": "1",
  "method": "UPI"
}
  '

    JSON Response

    {
  "id": 1,
  "token_url": "https://cybrilla.s.finprim.com/api/pg/payments/netbanking/ondc?txnId=2aa1b6f1-80f8-4034-8cee-4e1085fc15fb&identifier=pay_571dd2e5dd3d4f84add0103aaf3d9194"
}

    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 yes String NETBANKING or UPI
    bank_account_id yes Integer FP bank account old_id generated using Create Bank Account API. TPV is done based on these bank account details.
    payment_postback_url no String Application url where the investor will be redirected back after payment operation (http://example.com/payment_confirmation)
    provider_name no String Possible value ONDC

    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.

    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": "SUCCESS",
  "amount": 10008.0,
  "debit_date": "2026-01-22",
  "amc_order_ids": [
    1
  ],
  "failed_reason": null,
  "method": "UPI",
  "created_at": "2026-01-22T12:33:37+05:30",
  "submitted_at": null,
  "debit_confirmed_at": "2026-01-22T12:34:23+05:30",
  "failed_at": null,
  "transfer_initiated_at": null,
  "settled_at": null,
  "rejected_at": null,
  "from_bank_account_id": 1,
  "provider_name": "ONDC",
  "failure_code": null,
  "late_auth": false,
  "refund_reference": null,
  "refund_reason": null,
  "refund_status": null,
  "refund_created_at": null,
  "upi": {
    "type": null,
    "vpa": null,
    "uri": null
  },
  "digital_rupee": {
    "type": null,
    "uri": null
  },
  "token_url": null,
  "payment_reference": "pay_c3859b7fd15b435e84e0b5137afdd0e1",
  "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": false,
  "total_pages": 1,
  "total_elements": 2,
  "size": 100,
  "number": 0,
  "first": true,
  "number_of_elements": 2,
  "payments": [
    {
      "payment_type": "NETBANKING",
      "status": "SUCCESS",
      "amount": 10008.0,
      "debit_date": "2026-01-22",
      "amc_order_ids": [
        7616
      ],
      "failed_reason": null,
      "method": "UPI",
      "created_at": "2026-01-22T12:33:37+05:30",
      "submitted_at": null,
      "debit_confirmed_at": "2026-01-22T12:34:23+05:30",
      "failed_at": null,
      "transfer_initiated_at": null,
      "settled_at": null,
      "rejected_at": null,
      "from_bank_account_id": 1103,
      "provider_name": "ONDC",
      "failure_code": null,
      "late_auth": false,
      "refund_reference": null,
      "refund_reason": null,
      "refund_status": null,
      "refund_created_at": null,
      "upi": {
        "type": null,
        "vpa": null,
        "uri": null
      },
      "digital_rupee": {
        "type": null,
        "uri": null
      },
      "token_url": null,
      "payment_reference": "pay_c3859b7fd15b435e84e0b5137afdd0e1",
      "id": 5315
    },
    {
      "payment_type": "NACH",
      "status": "SUCCESS",
      "amount": 1000.0,
      "debit_date": null,
      "amc_order_ids": [
        7611
      ],
      "failed_reason": null,
      "method": "EMANDATE",
      "created_at": "2026-01-22T04:12:12+05:30",
      "submitted_at": null,
      "debit_confirmed_at": "2026-01-22T06:08:00+05:30",
      "failed_at": null,
      "transfer_initiated_at": null,
      "settled_at": null,
      "rejected_at": null,
      "from_bank_account_id": 1094,
      "provider_name": "CYBRILLAPOA",
      "failure_code": null,
      "late_auth": false,
      "refund_reference": null,
      "refund_reason": null,
      "refund_status": null,
      "refund_created_at": null,
      "upi": {
        "type": null,
        "vpa": null,
        "uri": null
      },
      "digital_rupee": {
        "type": null,
        "uri": null
      },
      "token_url": null,
      "payment_reference": "pay_3aa7e93dc32c4b6a9062391675a2dca5",
      "id": 5313
    }
  ]
}

    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 UPI, NETBANKING, 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,

    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

    1Compound 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:

    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

    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.

    Note for ondc gateway (Early access)

    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

    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

    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.

    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
    mf_plan_modification_instruction mf_plan_modification_instruction.created,mf_plan_modification_instruction.completed,mf_plan_modification_instruction.failed
    mandate mandate.created, mandate.received, mandate.submitted, mandate.approved, mandate.rejected, mandate.cancelled
    payment payment.pending,payment.updated, 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.

    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.

    shell