# MUSAFFA B2B API

Musaffa’s API is one of the most comprehensive Shariah-Compliant Stock Screener organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

All requests are made to endpoints beginning: `https://b2b.musaffa.us/b2b/api`.

# Developer Agreement

By using Musaffa’s API, you agree to our [Terms of Use](https://musaffa.com/terms-of-use).

## Rate Limits

There are limitations for the API calls.

Depending on the B2B subscription plan it can be up to 100 000 API calls per month and 1 API call per second.

If your limit is exceeded, you will receive a response with status code 429.

# Authentication and API

Musaffa will provide a secret key and a client ID to every B2B client.

``` plaintext
secretKey=< should be shared separately for each client >
clientId=< should be shared separately for each client >

 ```

UTC is used for time zone “UTC+5”

``` plaintext
TimeZone = "UTC"
DateTimeFormatter = "yyyyMMddHHmmss"

 ```

Using current time, the secret key, the client ID and a body of the message a token is generated using the following code:

``` plaintext
token = Base64.getEncoder().encodeToString(DigestUtils.sha512 (secretKey + time + json String body))

 ```

The token is placed in the header of the message for both sides of the communication and used for validating messages.

## Example Token Generation

``` java
String secretKey = "gRUsdfsdfkv8yBEyQWGbPeShVmYq3tREWRC&F)JMcQfTjWnZ"
String jsonInStringBody = "{"stock":"AAPL"}"
String time = ZonedDateTime.ofInstant(nowUtc,zoneId).format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));
String token = Base64.getEncoder().encodeToString(DigestUtils.sha512(secretKey + time + jsonInStringBody));

 ```

Version: 1.0.0

## Servers

```
https://b2b.musaffa.us/b2b/api
```

```
https://b2b.musaffa.us/b2b/api/v1
```

## Security

### MusaffaAuth

Authentication token generated using SHA512 hashing

Type: apiKey
In: header
Name: token

## Download OpenAPI description

[MUSAFFA B2B API](https://docs.musaffa.us/_bundle/apis/index.yaml)

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

## ETFs

APIs Related to ETFs

### ETF LIST v.1

 - [POST /v1/musaffa/etf/list](https://docs.musaffa.us/apis/etfs/etflistv1.md): Get ETF List.

## Request body:

| Parameter | Value | Description |
| --- | --- | --- |
| country | "US" | Market where ETF traded |

## Response body:

| Parameter | Type | Description |
| --- | --- | --- |
| symbol | string | ETF symbol |
| isin | string | ETF ISIN |
| name | string | ETF Name |
| assetClass | string | Asset Class |
| investmentSegment | string | Investment Segment. |
| market | string | Market |
| navCurrency | string | NAV currency. |
| numberOfHoldings | number | Number of holdings. |
| uncoveredHoldings | number | Number of uncovered holdings. |
| complianceStatus | string | Shariah-compliance Status (Halal, Not Halal, Doubtful) |

### ETF SCREENING REPORT v.1

 - [POST /v1/musaffa/etf/report](https://docs.musaffa.us/apis/etfs/etfscreeningreportv1.md): Get Shariah-Compliant Screening Results for ETFs. You can query by stock ticker.

EndFragment

## Request body:

| Parameter | Value | Description |
| --- | --- | --- |
| symbol | "SEMI" | ETF symbol |

## Response body:

| Parameter | Type | Description |
| --- | --- | --- |
| symbol | string | ETF symbol |
| isin | string | ETF ISIN |
| name | string | ETF Name |
| assetClass | string | Asset Class |
| investmentSegment | string | Investment Segment. |
| market | string | Market |
| navCurrency | string | NAV currency. |
| numberOfHoldings | number | Number of holdings. |
| uncoveredHoldings | number | Number of uncovered holdings. |
| complianceStatus | string | Shariah-compliance Status  (HALAL, NOT HALAL, DOUBTFUL) |
| aggregateRevenueBreakdown | 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 |
| aggregateInterestBearingSecuritiesAndAssets | object | Interest-bearing Securities and Assets JSON Object  {  "interestAmount": "number", // amount of Interest-bearing Securities and Assets  "interestRatio": "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’ |
| aggregateInterestBearingDebt | object | Interest-bearing Debt JSON Object  _{  "debtAmount": "number", // amount of Interest-bearing Debt  "debtRatio": "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’ |
| 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) |
| aggregateRevenue | number | Total Revenue of the company |
| month36AverageMarkCap | number | Trailing 36-month Average Market Capitalization of the company. |

### ETF SCREENING PURIFICATION v.1

 - [POST /musaffa/etf/purification](https://docs.musaffa.us/apis/etfs/etfscreeningpurificationv1.md): ETF SCREENING PURIFICATION v.1

### List of ETF holdings

 - [POST /v1/musaffa/etf/holdings](https://docs.musaffa.us/apis/etfs/listofetfholidngs.md): LIST OF ETF Holidngs

### ETF PROFILE

 - [POST /v1/musaffa/etf/profile](https://docs.musaffa.us/apis/etfs/etfprofile.md): ETF PROFILE

### ETF sector

 - [POST /v1/musaffa/etf/sector](https://docs.musaffa.us/apis/etfs/etfsector.md): ETF Sector

### Zakatable assets

 - [POST /v1/musaffa/etf/zakatableAssets](https://docs.musaffa.us/apis/etfs/zakatableassets.md): Generated from cURL: curl --location 'https://b2b.musaffa.us/b2b/api/v1/musaffa/etf/zakatableAssets' \
--header 'Content-Type: application/json' \
--header 'clientId: AX6kFk5ywERyZacb' \
--header 'time: 20250306111840' \
--header 'token: ONcCawsaE09G76NOBa2tI8TaVUHZ2sSB0glfSh720bFS1RrgpzIXg1QMKe62lkJm63TldKkWoAgF3ESKK9y76Q==' \
--data '{
    "symbol":"QQQ"
}'

### ETF country

 - [POST /v1/musaffa/etf/country](https://docs.musaffa.us/apis/etfs/etfcountry.md): ETF Country

## Customer Account

Customer account management APIs

### CUSTOMER CALL STATISTICS v.1

 - [GET /v1/b2b-users/statistics](https://docs.musaffa.us/apis/customer-account/customercallstatisticsv1.md): Get the Request Statistics of your account.

## Response body:

| Parameter | Type | Description |
| --- | --- | --- |
| clientId | string | Client ID |
| companyName | string | Company Name |
| subscriptionPlan | string | Subscription Plan |
| monthlyRequestLimit | number | Monthly request limit |
| activeMonthRequestAmount | number | Number of requests made for the active month |
| lastRequestDate | dateTime | Last request date |
| subscriptionEndDate | dateTime | Subscription end date |
| activeMonthStartDate | dateTime | Start date of the active month |