# Stocks

APIs related to Stocks

## STOCK SCREENING REPORT v.3

 - [POST /v3/musaffa/stocks/report](https://docs.musaffa.us/apis/stocks/stockscreeningreportv3.md): Get the screening results of Shariah-compliant stocks with comprehensive details. You can query by stock ticker.

## Request body:

| Parameter | Value | Description |
| --- | --- | --- |
| stock | “AAPL” | Stock symbol |

## Response body:

| Parameter | Type | Description |
| --- | --- | --- |
| companyName | string | Company name |
| symbol | string | Stock symbol |
| lastUpdate | string | Last update date in ISO 8601 Date/Time Format (YYYY-MM-DD). |
| shariahComplianceStatus | string | Shariah-compliance Status  (Halal, Not Halal, Doubtful, Not Covered) |
| complianceRanking | number | Compliance Rank (0-5) |
| revenueBreakdown | object |     Revenue Breakdown JSON Object  _{  "halalRatio": "number", // percentage value from 0 to 100  "notHalalRatio": "number", // percentage value from 0 to 100  "doubtfulRatio": "number", // percentage value from 0 to 100  "doubtfulRevenue": "number", // amount in units  "halalRevenue": "number", // amount in units  "notHalalRevenue": "number", // amount in units  "status": "string", // Pass or Fail  }_  Combined  revenue from DOUBTFUL and NOT HALAL sources must be less than 5% of  total revenue to be Shariah compliant based on AAOIFI stock screening  methodology.  Thus,    \- If DOUBTFUL+NOT HALAL revenue is equal or more than 5%, then the status will be FAIL  \- If DOUBTFUL+NOT HALAL revenue is less than 5%, then the status will be PASS  \- If HALAL, DOUBTFUL and NOT HALAL has no value, then the status will be NOT_UNDER_COVERAGE     |
| interestBearingSecuritiesAndAssets | object |     Interest-bearing Securities and Assets  Interest-Bearing  Securities and Assets should be less than 30% of Trailing 36-month  Average Market Capitalization to be Shariah compliant based on AAOIFI  stock screening methodology.Thus,    \- if Interest Ratio is equal or more than 30%, then the status will be ‘Fail’  \- if Interest Ratio is less than 30%, then the status will be ‘Pass’  \- if Interest Ratio has no value, then the status will be ’NOT_COVERED’     |
| interestBearingDebt | object |     Interest-bearing Debt  Interest-Bearing Debt should be less  than 30% of Trailing 36-Month Average Market Capitalization to be  Shariah compliant based on AAOIFI stock screening methodology.  Thus,    \- if Debt Ratio is equal or more than 30%, then the status will be ‘Fail’  \- if Debt Ratio is less than 30%, then the status will be ‘Pass’  \- if Debt Ratio has no value, then the status will be ’NOT_COVERED’     |
| reportDate | date | Reporting dates of the company in ISO 8601 Date/Time Format (YYYY-MM-DD). |
| reportSource | string | URL link to the company report. |
| totalRevenue | number | Total Revenue of the company |
| trailing36monAvrCap | number | Trailing 36-month Average Market Capitalization of the company. |
| totalAssets | number | Amount of Total Assets (in units) |
| accountsReceivable | number | Amount of Accounts Receivable (in units) |
| reportedYear | number | Reporting year |
| reportedQuarter | string | Reporting period (FIRST_QUARTER, SECOND_QUARTER, THIRD_QUARTER, ANNUAL) |
| mainCurrency | string | Reporting currency. Currency used in company filings |
| units | number | Number expression (e.g. in million) |
| revenueBreakdownDetail | object | Revenue breakdown JSON object that contains line items with  compliance type, ration, amount in once and comments.  _{ "amount": "number",  "amountInOnes": "number", "questionablePercentage": "number",  "halalPercentage": "number", "questionableAmountInOnes": "number",  "notHalalAmount": "number", "notHalalAmountInOnes": "number",  "halalAmountInOnes": "number", "percentage": "number", "name": "string",  "notHalalPercentage": "number", "halalAmount": "number", "items":  "array", "questionableAmount": "number" }_ |
| interestBearingSecuritiesAndAssetsDetail | object | Interest-bearing securities and assets JSON object that contains  line items with compliance type, ration, amount in once and comments.  _{ "totalAmount":"number", "totalRetio":"number", "longTermJson":"object",  "totalNonIslamicAmount":"number" "shortTermJson":"object" }_ |
| interestIncomeDetail | object | Interest Income JSON object that contains line items with compliance  type, ration, amount in once and comments.  _{ "amount":"number",  "amountInOnes":"number", "questionablePercentage":"number",  "halalPercentage":"number", "questionableAmountInOnes":"number",  "notHalalAmount":"number", "notHalalAmountInOnes":"number",  "halalAmountInOnes":"number", "percentage":"number", "name":"string",  "notHalalPercentage":"number", "halalAmount":"number", "items":"array",  "questionableAmount":"number" }_ |
| interestBearingDebtDetail | object | Interest-bearing debt JSON object that contains line items with  compliance type, ration, amount in once and comments.  _{ "totalAmount":"number", "totalRetio":"number", "longTermJson":"object",  "totalNonIslamicAmount":"number" "shortTermJson":"object" }_ |

## LIST OF STOCK SCREENING REPORTS v.1

 - [POST /v1/musaffa/stocks/list](https://docs.musaffa.us/apis/stocks/listofstockscreeningreportsv1.md): Get Shariah-Compliant Screening Results for stocks. You can query by stock ticker.

### List of Sectors:

- Health Care
    
- Financials
    
- Information Technology Consumer Staples Real Estate
    
- Energy
    
- Industrials
    
- Materials
    
- Utilities
    
- Consumer Discretionary
    
- Communication Services
    

### Sample country codes:

US, UK, SG etc

## Request body:

| Parameter | Value | Description |
| --- | --- | --- |
| country | "US" | Country code |
| sector | "Information Technology" | Sector |

## Response body:

| Parameter | Type | Description |
| --- | --- | --- |
| companyName | string | Company name |
| stockName | string | Stock symbol |
| shariahComplianceStatus | string | Shariah-compliance Status  (Halal, Not Halal, Doubtful, Not Covered) |
| complianceRanking | number | Compliance Rank (0-5) |

## LIST OF STOCK SCREENING REPORTS v.2

 - [POST /v2/musaffa/stocks/screening-list](https://docs.musaffa.us/apis/stocks/listofstockscreeningreportsv2.md): Get Shariah-Compliant Screening Results for stocks. You can query by stock tickers. Maximum permissible limit of tickers per request is 100.

## Request body:

| Parameter | Value | Description |
| --- | --- | --- |
| stocks | \["AAPL","NFLX","TSLA, . . . . "\] | Stock symbol list (Maximum 100 symbols per request) |

## Response body:

| Parameter | Type | Description |
| --- | --- | --- |
| companyName | string | Company name |
| symbol | string | Stock symbol |
| lastUpdate | dateTime | Last  update date in ISO 8601 date-time format YYYY "-" MM "-" DD "T" hh(00  through 23) ":" mm(00 through 59) ":" ss(00 through 59) |
| shariahComplianceStatus | string | Shariah-compliance Status  (HALAL, NOT HALAL, DOUBTFUL, NOT_UNDER_COVERAGE) |
| complianceRanking | number | Compliance Rank (0-5) |
| revenueBreakdown | object | Revenue Breakdown JSON Object  _{  "halalRatio": "number", // percentage value from 0 to 100  "notHalalRatio": "number", // percentage value from 0 to 100  "doubtfulRatio": "number", // percentage value from 0 to 100  "doubtfulRevenue": "number", // amount of doubtful revenue  "halalRevenue": "number", // amount of halal revenue  "notHalalRevenue": "number", // amount of not halal revenue  "status": "string", // Pass or Fail  }  _  Combined revenue from DOUBTFUL and NOT HALAL sources must be less than  5% of total revenue to be Shariah compliant based on AAOIFI stock  screening methodology.  Thus,  \- If DOUBTFUL+NOT HALAL revenue is equal or more than 5%, then the  status will be FAIL  \- If DOUBTFUL+NOT HALAL revenue is less than 5%, then the status will be  PASS  \- If HALAL, DOUBTFUL and NOT HALAL has no value, then the status will be  NOT_UNDER_COVERAGE |
| interestBearingSecuritiesAndAssets | object | Interest-bearing Securities and Assets JSON Object  _{  "amount": "number", // amount of Interest-bearing Securities and Assets  "ratio": "number", // percentage value from 0 to N  "status": "string", // Pass or Fail  }  _  Interest-Bearing Securities and Assets should be less than 30% of  Trailing 36-month Average Market Capitalization to be Shariah compliant  based on AAOIFI stock screening methodology.  Thus,  \- If Interest Ratio is equal or more than 30%, then the status will be  ‘Fail’  \- If Interest Ratio is less than 30%, then the status will be ‘Pass’  \- If Interest Ratio has no value, then the status will be ’NOT_COVERED’ |
| interestBearingDebt | object | Interest-bearing Debt JSON Object  _{  "amount": "number", // amount of Interest-bearing Debt  "ratio": "number", // percentage value from 0 to N  "status": "string", // Pass or Fail  }  _  Interest-Bearing Debt should be less than 30% of Trailing 36-Month  Average Market Capitalization to be Shariah compliant based on AAOIFI  stock screening methodology.  Thus,  \- If Debt Ratio is equal or more than 30%, then the status will be  ‘Fail’  \- If Debt Ratio is less than 30%, then the status will be ‘Pass’  \- If Debt Ratio has no value, then the status will be ’NOT_COVERED’ |
| reportDate | date | Reporting dates of the company in ISO 8601 Date/Time Format (YYYY-MM-DD). |
| reportSource | string | URL link to the company report |
| totalRevenue | number | Total Revenue of the company |
| trailing36monAvrCap | number | Trailing 36-month Average Market Capitalization of the company. |

## DIVIDEND PURIFICATION v.2

 - [POST /v2/musaffa/stocks/dividends/pure](https://docs.musaffa.us/apis/stocks/dividendpurificationv2.md): Get Dividend Purification Results for stocks. You can query by stock ticker.

## Request body:

| Parameter | Value | Description |
| --- | --- | --- |
| stock | "AAPL" | Stock symbol |

## Response body:

| Parameter | Type | Description |
| --- | --- | --- |
| non-compliant_revenue_ratio | number | Percentage of non-compliant revenue out of total revenue |
| symbol | string | Stock symbol |
| reported_quarter | string | Reported quarter |
| dividend_per_share_for_quarter | number | Dividend per share for the latest quarter |
| reported_year | number | Reported year |
| dividend_purification_amount_per_share | number | Dividend purification amount per share (DPAPS) |
| report_date | date | Report date |

## BULK DIVIDEND PURIFICATION v.2

 - [POST /v2/musaffa/stocks/dividends/pure/bulk](https://docs.musaffa.us/apis/stocks/bulkdividendpurificationv2.md): Get the list of Dividend Purification Results for stocks. You can query by stock tickers. Maximum permissible limit of tickers per request is 100.

## Request body:

| Parameter | Value | Description |
| --- | --- | --- |
| stocks | \["AAPL","NFLX","TSLA, . . . . "\] | Stock symbol list (Maximum 100 symbols per request) |

## Response body:

| Parameter | Type | Description |
| --- | --- | --- |
| non-compliant_revenue_ratio | number | Percentage of non-compliant revenue out of total revenue |
| symbol | string | Stock symbol |
| reported_quarter | string | Reported quarter |
| dividend_per_share_for_quarter | number | Dividend per share for the latest quarter |
| reported_year | number | Reported year |
| dividend_purification_amount_per_share | number | Dividend purification amount per share (DPAPS) |
| report_date | date | Report date |

## RELATED STOCKS v.1

 - [GET /v1/musaffa/stocks/related/{symbol}](https://docs.musaffa.us/apis/stocks/relatedstocksv1.md): Related stocks is a list of stocks which match with current stock by market, industry and sector.

### Response body:

| Field | Type | Description |
| --- | --- | --- |
| companyName | string | Company name |
| stockName | string | Stock symbol |
| shariahComplianceStatus | string | Shariah-compliance Status (Halal, Not Halal, Doubtful, Not Covered) |
| complianceRanking | number | Compliance Rank (0-5) |

## Calculate zakat

 - [GET /v1/musaffa/stocks/calculate_zakat/{symbol}](https://docs.musaffa.us/apis/stocks/calculatezakat.md): Get Zakat Calculation Results for stocks. You can query by stock ticker.Related stocks is a list of stocks which match with current stock by market, industry and sector.

### Response body:

| Field | Type | Description |
| --- | --- | --- |
| symbol | string | stock symbol |
| value | number | market price of a stock |
| investment_type | Short-term; Long-term | Short-term investments - the one which you do with the intent of trading. Usually this are the one’s which one holds for less than 1 year. These holdings are treated as liquid/cash and zakat is to be paid as 2.5% on the total amount. Long-term investments - the one which you do with the intent of long-term capital appreciation. Usually this are the one’s which one holds for more than 1 year. Zakat on these shares is based on the underlying Zakatable assets of the company. |
| zakat_amount_per_share | number | Zakat amount per share |