You can use the Stakeholders APIs to add a stakeholder for an account. Each stakeholder will have their KYC.

Handy Tip
A stakeholder can be a signatory or an owner of the business.

You can create, fetch and update stakeholders using these APIs.

You can try out our APIs on the Razorpay Postman Public Workspace.

Stakeholders Entity🔗

The Stakeholders entity consists of the following fields. You can find the JSON sample entity on the right side.

id

string The unique identifier of a stakeholder generated by Razorpay, used to fetch or update a stakeholder. For example, sth_GLGgm8fFCKc92m. Maximum length supported is 18 characters.

entity

string Here it is stakeholder.

percentage_ownership

float The stakeholder's ownership of the business in percentage. Only two decimal places are allowed. For example, 87.55. The maximum length is 100 characters.

name

string The stakeholder's name as per the PAN card. The maximum length is 255 characters.

email

string The stakeholder's email address. The maximum length is:

local part (before @): 64 characters.
domain part (after @): 68 characters.
The total character length supported is 132.

relationship

object The stakeholder's relationship with the account’s business. The default value is false.

director: This attribute is set to true if the stakeholder is a director of the account's legal entity. By default, it is set to false.
executive: This attribute is set to true if the stakeholder is an executive of the account's legal entity. By default, it is set to false.

phone

object The stakeholder's phone number.

primary: integer The primary contact number of the stakeholder. The minimum length is 8 characters and the maximum length is 11.
secondary: integer The secondary contact number of the stakeholder. The minimum length is 8 characters and the maximum length is 11.

addresses

object Details of stakeholder's address.

residential

string Details of the stakeholder's residential address.

street: string The stakeholder's street address. The minimum length is 10 characters and maximum length is 255.
city: string The city. The minimum length is 2 and maximum length is 32.
state: string The state. The minimum length is 2 and maximum length is 32.
postal_code: string The postal code. The minimum length is 2 and maximum length is 10.
country: string The country. The minimum length is 2 and maximum length is 64.

kyc

object The type of document required to establish the stakeholder's identity.

pan

string The PAN number of the stakeholder.

This is a 10-digit alphanumeric code. For example, AVOPB1111K.
Regex for Stakeholder PAN: /^[a-zA-z]{5}\d{4}[a-zA-Z]{1}$/
Validation for Stakeholder PAN: The 4th digit should be 'P'.
Handy Tip
To complete the KYC process, this API parameter might be required, but it is optional for this API.

notes

object Contains user-defined fields stored by the partner for reference purposes. It can hold a maximum of 15 key-value pairs, 512 characters (maximum) each. For example, "note_key": "Beam me up Scotty”.

 Sample Entity
Copy{
  "entity": "stakeholder",
  "relationship": {
    "executive": true
  },
  "phone": {
    "primary": "9999999999",
    "secondary": "9999999999"
  },
  "notes": {
    "random_key_by_partner": "random_value"
  },
  "kyc": {
    "pan": "AVOPB1111K"
  },
  "id": "sth_GLGgm8fFCKc92m",
  "name": "Gaurav Kumar",
  "email": "gaurav.kumar@example.com",
  "percentage_ownership": 10,
  "addresses": {
    "residential": {
      "street": "506, Koramangala 1st block",
      "city": "Bengaluru",
      "state": "Karnataka",
      "postal_code": "560034",
      "country": "IN"
    }
  }
}

Create a Stakeholder🔗

Use the following API endpoint to create a stakeholder:

/accounts/:account_id/stakeholders

Handy Tip
A stakeholder can be a signatory or an owner of the business.

 Request Response
Copycurl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \
-X POST https://api.razorpay.com/v2/accounts/acc_GLGeLkU2JUeyDZ/stakeholders \
-H "Content-Type: application/json" \
-d '{
  "percentage_ownership": 10,
  "name": "Gaurav Kumar",
  "email": "gaurav.kumar@example.com",
  "relationship": {
    "director": true,
    "executive": false
  },
  "phone": {
    "primary": "7474747474",
    "secondary": "7474747474"
  },
  "addresses": {
    "residential": {
      "street": "506, Koramangala 1st block",
      "city": "Bengaluru",
      "state": "Karnataka",
      "postal_code": "560034",
      "country": "IN"
    }
  },
  "kyc": {
    "pan": "AVOPB1111K"
  },
  "notes": {
    "random_key_by_partner": "random_value"
  }
}'
Copy{
  "entity": "stakeholder",
  "relationship": {
    "director": true
  },
  "phone": {
    "primary": "7474747474",
    "secondary": "7474747474"
  },
  "notes": {
    "random_key_by_partner": "random_value"
  },
  "kyc": {
    "pan": "AVOPB1111K"
  },
  "id": "sth_GLGgm8fFCKc92m",
  "name": "Gaurav Kumar",
  "email": "gaurav.kumar@example.com",
  "percentage_ownership": 10,
  "addresses": {
    "residential": {
      "street": "506, Koramangala 1st block",
      "city": "Bengaluru",
      "state": "Karnataka",
      "postal_code": "560034",
      "country": "IN"
    }
  }
}

Path Parameter🔗

account_id: string The unique identifier of the sub-merchant account generated by Razorpay. For example, acc_GLGeLkU2JUeyDZ. This id is used to fetch or update a stakeholder. The stakeholder is created for this sub-merchant account id.

Request Parameters🔗

name mandatory

string The stakeholder's name as per the PAN card. The maximum length is 255 characters.

email

string The stakeholder's email address. The maximum length is:

local part (before @): 64 characters.
domain part (after @): 68 characters.
The total character length supported is 132.

percentage_ownershipoptional

float The stakeholder's ownership of the business in percentage. Only two decimal places are allowed. For example, 87.55. The maximum length is 100 characters.

relationship optional

boolean The stakeholder's relationship with the account’s business. The default value is false.

director: This attribute is set to true if the stakeholder is a director of the account's legal entity. By default, it is set to false.
executive: This attribute is set to true if the stakeholder is an executive of the account's legal entity. By default, it is set to false.

phone optional

object The stakeholder's phone number.

primaryoptional: integer The primary contact number of the stakeholder. The minimum length is 8 characters and the maximum length is 11.
secondaryoptional: integer The secondary contact number of the stakeholder. The minimum length is 8 characters and the maximum length is 11.

addresses optional

object Details of stakeholder's address.

residential

object Details of the stakeholder's residential address.

street optional: string The stakeholder's street address. The minimum length is 10 characters and maximum length is 255.
city optional: string The city. The minimum length is 2 and maximum length is 32.
state optional: string The state. The minimum length is 2 and maximum length is 32.
postal_code optional: string The postal code. The minimum length is 2 and maximum length is 10.
country optional: string The country. The minimum length is 2 and maximum length is 64.

kyc conditional

object The type of document required to establish the stakeholder's identity.

pan

string The PAN number of the stakeholder.

This is a 10-digit alphanumeric code. For example, AVOPB1111K.
Regex for Stakeholder PAN: /^[a-zA-z]{5}\d{4}[a-zA-Z]{1}$/.
Validation for Stakeholder PAN: The 4th digit should be 'P'.

notes optional

object Contains user-defined fields stored by the partner for reference purposes. Maximum 15 key-value pairs, 512 characters (maximum) each.

Response Parameters🔗

id: string The unique identifier of the stakeholder whose details are created. For example, sth_GLGgm8fFCKc92m.

Error Response Parameters🔗

Know about the various error responses for this API.

Fetch a Stakeholder🔗

Use the following endpoint to retrieve the details of a stakeholder:

/accounts/:account_id/stakeholders/:stakeholder_id

 Request Response
Copycurl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \
- X GET https://api.razorpay.com/v2/accounts/acc_GLGeLkU2JUeyDZ/stakeholders/sth_GOQ4Eftlz62TSL \
Copy{
  "entity": "stakeholder",
  "relationship": {
    "director": true
  },
  "phone": {
    "primary": "9999999999",
    "secondary": "9999999999"
  },
  "notes": {
    "random_key_by_partner": "random_value2"
  },
  "kyc": {
    "pan": "AVOPB1111J"
  },
  "id": "sth_GOQ4Eftlz62TSL",
  "name": "Gauri Kumar",
  "email": "gauri@example.com",
  "percentage_ownership": 20,
  "addresses": {
    "residential": {
      "street": "507, Koramangala 1st block",
      "city": "Bangalore",
      "state": "Karnataka",
      "postal_code": "560035",
      "country": "in"
    }
  }
}

Path Parameters🔗

account_id mandatory: string The unique identifier of a sub-merchant account generated by Razorpay. For example, acc_GLGeLkU2JUeyDZ.
id: string The unique identifier of the stakeholder whose details are to be fetched. For example, sth_GOQ4Eftlz62TSL.

Error Response Parameters🔗

Know about the various error responses for this API.

Fetch all Stakeholders🔗

Use the following endpoint to retrieve all stakeholders for a given account:

/accounts/:account_id/stakeholders

 Request Response
Copycurl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \
- X GET https://api.razorpay.com/v2/accounts/acc_GLGeLkU2JUeyDZ/   \
Copy{
  "entity": "collection",
  "items": [
    {
      "id": "GZ13yPHLJof9IE",
      "entity": "stakeholder",
      "relationship": {
        "director": true
      },
      "phone": {
        "primary": "9999999999",
        "secondary": "9999999999"
      },
      "notes": {
        "random_key_by_partner": "random_value"
      },
      "kyc": {
        "pan": "AVOPB1111K"
      },
      "name": "Gaurav Kumar",
      "email": "gaurav.kumar@acme.org",
      "percentage_ownership": 10,
      "addresses": {
        "residential": {
          "street": "506, Koramangala 1st block",
          "city": "Bengaluru",
          "state": "Karnataka",
          "postal_code": "560034",
          "country": "in"
        }
      }
    }
  ],
  "count": 1
}

Path Parameter🔗

account_id mandatory: string The unique identifier of a sub-merchant account generated by Razorpay. For example, acc_GLGeLkU2JUeyDZ.

Error Response Parameters🔗

Know about the various error responses for this API.

Update a Stakeholder🔗

The information you can update for a stakeholder using the Update a Stakeholder API differs based on the product activation status.

Activation Status	Update Permitted
`requested`	You can update the details for all the fields.
`needs_clarification`	The fields you can update depend on the `reason_code` mentioned in the `requirements` object in the Request a Product Activation API: document_missing or field_missing: You can update all the fields. needs_clarification: You can update only the specific field for which Razorpay is seeking clarification for.
`under_review`	You cannot update any fields.
`activated`	You cannot use this API to update any fields as your account is already active.

Use the following endpoint to update the details of a stakeholder:

/accounts/:account_id/stakeholders/:stakeholder_id

Currently, we do not support making concurrent requests to the following Onboarding APIs including their combination on the same account_id:

Please wait for the response of these APIs before making subsequent requests.

Path Parameter🔗

account_id mandatory: string The unique identifier of a sub-merchant account generated by Razorpay. For example, acc_GLGeLkU2JUeyDZ
id mandatory: string The unique identifier of the stakeholder whose details are to be updated. For example, sth_GOQ4Eftlz62TSL

 Request Response
Copycurl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \
-H "Content-Type: application/json" \
-X PATCH https://api.razorpay.com/v2/accounts/acc_GLGeLkU2JUeyDZ/stakeholders/sth_GOQ4Eftlz62TSL \
-d '{
  "percentage_ownership": 20,
  "name": "Gauri Kumar",
  "relationship": {
    "director": false,
    "executive": true
  },
  "phone": {
    "primary": "9898989898",
    "secondary": "9898989898"
  },
  "addresses": {
    "residential": {
      "street": "507, Koramangala 1st block",
      "city": "Bangalore",
      "state": "Karnataka",
      "postal_code": "560035",
      "country": "IN"
    }
  },
  "kyc": {
    "pan": "AVOPB1111J"
  },
  "notes": {
    "random_key_by_partner": "random_value2"
  }
}'
Copy{
  "entity": "stakeholder",
  "relationship": {
    "director": true
  },
  "phone": {
    "primary": "9898989898",
    "secondary": "9898989898"
  },
  "notes": {
    "random_key_by_partner": "random_value2"
  },
  "kyc": {
    "pan": "AVOPB1111J"
  },
  "id": "sth_GOQ4Eftlz62TSL",
  "name": "Gauri Kumar",
  "email": "gauri.kumar@example.com",
  "percentage_ownership": 20,
  "addresses": {
    "residential": {
      "street": "507, Koramangala 1st block",
      "city": "Bangalore",
      "state": "Karnataka",
      "postal_code": "560035",
      "country": "IN"
    }
  }
}

Request Parameters🔗

percentage_ownershipoptional

float The stakeholder's ownership of the business in percentage. Only two decimal places are allowed. For example, 87.55. The maximum length is 100 characters.

name optional

string The stakeholder's name as per the PAN card. The maximum length is 255 characters.

relationship optional

boolean The stakeholder's relationship with the account’s business. The default value is false.

director: This attribute is set to true if the stakeholder is a director of the account's legal entity. By default, it is set to false.
executive: This attribute is set to true if the stakeholder is an executive of the account's legal entity. By default, it is set to false.

phone optional

object The stakeholder's phone number.

primaryoptional: integer The primary contact number of the stakeholder. The minimum length is 8 characters and the maximum length is 11.
secondaryoptional: integer The secondary contact number of the stakeholder. The minimum length is 8 characters and the maximum length is 11.

addresses optional

object Details of stakeholder's address.

residential

object Details of the stakeholder's residential address.

street optional: string The stakeholder's street address. The minimum length is 10 characters and maximum length is 255.
city optional: string The city. The minimum length is 2 and maximum length is 32.
state optional: string The state. The minimum length is 2 and maximum length is 32.
postal_code optional: string The postal code. The minimum length is 2 and maximum length is 10.
country optional: string The country. The minimum length is 2 and maximum length is 64.

kyc conditional

object The type of document required to establish the stakeholder's identity.

pan

string The PAN number of the stakeholder.

This is a 10-digit alphanumeric code. For example, AVOPB1111K.
Regex for Stakeholder PAN: /^[a-zA-z]{5}\d{4}[a-zA-Z]{1}$/.
Validation for Stakeholder PAN: The 4th digit should be 'P'.

notes optional

object Contains user-defined fields stored by the partner for reference purposes. Maximum 15 key-value pairs, 512 characters (maximum) each.

Error Response Parameters🔗

Know about the various error responses for this API.

Stakeholder APIs