API documentation


Introduction

The Sensefolio API is a suite of high-performance RESTful JSON endpoints that are specifically designed to meet the demands of application developers, data scientists, and enterprise business platforms.

This API reference includes all technical documentation developers need to integrate third-party applications and platforms.

Start Guide

For developers willing to start with the Sensefolio API, here are 3 quick steps to make your first call with the API.

  • 1. Sign up for a free account. Contact us for having an API key and you will get access to the API domain environment:
    • https://circular-hawk-253618.appspot.com
    • Endpoints:
      • a. /companyInfoFull
      • b. /companyScore?company_idx=XXX , where XXX is the company id
      • c. /ActualNews?company_idx=XXX , where XXX is the company id
      • d. /ActualTweets?company_idx=XXX , where XXX is the company id

  • 2. Copy your API Key.
  • 3. Make a test call using your key. You may use the code example provided below to make a test call with your programming language of choice.
  • 4. Be sure to replace the API Key in sample code with your own and use API domain
  • 5. Implement your application. Now that you've confirmed your API Key is working, get familiar with the API by reading the rest of this API
Reference and commence building your application!
Note: Making HTTP requests on the client side with Javascript is currently prohibited through CORS configuration. This is to protect your API Key which should not be visible to users of your application, so your API Key is not stolen. Secure your API Key by routing calls through your own backend service.

Example of the CompanyList endpoint

	
{
        "id": 0,
        "symbol": "AAPL",
        "name": "Apple Inc.",
        "cusip": "37833100",
        "isin": "US0378331005",
        "sedol": "2046251",
        "exchange_country_region": "North America",
        "fe_country": "United States of America",
        "fe_factsetid": "3783310",
        "bloomberg": "AAPL US",
        "gics_sector": "Information Technology",
        "gics_industry_name": "Technology Hardware & Equipmen",
        "glassdoor": "https://www.glassdoor.com/Reviews/Apple-Reviews-E1138.htm",
        "indeed": "https://www.indeed.com/cmp/Apple/reviews?fcountry=ALL",
        "comparably": "https://www.comparably.com/companies/apple",
        "fairygodboss": "https://fairygodboss.com/company-overview/apple",
        "inhersight": "https://www.inhersight.com/company/apple"
    },
	

Example of the Scores endpoint

	
{
        "ESG_Score": 59.9728,
        "E_Score": 59.1721,
        "G_Score": 61.3401,
        "S_Score": 59.6732,
        "_1_1_1_AirQuality_List": 56.8368,
        "_1_1_2_ComplianceEnvironmentalRegulations_List": 57.4779,
        "_1_1_3_EnergyMgmt_List": 58.924,
        "_1_1_4_FuelMgmt_List": 60.9399,
        "_1_1_5_GHGemissions_List": 56.4814,
        "_1_2_1_EnvironmentalImpactsAssetsOperations_List": 64.4135,
        "_1_2_2_SupplierEnvironmentalAssessment_List": 58.4981,
        "_1_2_3_EnvironBusinessDevelopment_List": 57.3556,
        "_1_2_4_EvaluationEnvironKPI_List": 61.5253,
        "_1_2_5_LifecycleImpactsProductsServices_List": 56.6798,
        "_1_2_6_ProductPackaging_List": 63.1125,
        "_1_2_7_ProductQualitySafety_List": 57.5552,
        "_1_2_8_ResponsibleConsumptionProduction_List": 65.7193,
        "_1_3_1_BiodiversityImpacts_List": 58.2344,
        "_1_3_2_WaterWastewaterMgmt_List": 55.8877,
        "_1_3_3_WasteHazardousMaterialsMgmt_List": 57.1114,
        "_2_1_1_HealthSafety_List": 71.3537,
        "_2_2_1_FairLaborPractices_List": 54.8548,
        "_2_2_2_LaborMgmtRelations_List": 62.5213,
        "_2_2_3_TrainingEducation_List": 63.8339,
        "_2_2_4_DiversityEqualOpportunity_List": 60.932,
        "_2_2_5_CompensationBenefits_List": 66.6666,
        "_2_2_6_RecruitmentDevelopmentRetention_List": 38.5313,
        "_2_3_1_AccessAffordability_List": 66.6692,
        "_2_3_2_CustomerHealthSafety_List": 66.4801,
        "_2_3_3_CustomerPrivacy_List": 72.6072,
        "_2_3_4_FairDisclosureLabeling_List": 37.2116,
        "_2_3_5_FairMarketingAdvertising_List": 74.9442,
        "_2_3_6_LocalCommunities_List": 36.6739,
        "_2_3_7_SocialImpactsAssetsOperations_List": 37.3922,
        "_2_4_1_ChildLabor_List": 73.4678,
        "_2_4_2_FreedomAssociationCollectiveBargaining_List": 56.7613,
        "_2_4_3_HumanRights_List": 60.2832,
        "_2_4_4_NonDiscrimination_List": 60.6164,
        "_2_4_5_RightsIndigenousPeoples_List": 71.9907,
        "_3_1_1_BoardLeadership_List": 58.2232,
        "_3_1_2_CeoExecutiveLeadership_List": 55.241,
        "_3_1_3_ManagementLeadership_List": 72.2424,
        "_3_1_4_InternalControlRisks_List": 59.4965,
        "_3_2_1_EconomicPerformance_List": 46.7483,
        "_3_2_2_IndustryInnovationInfrastructure_List": 70.3855,
        "_3_2_3_MarketPresence_List": 62.7271,
        "_3_3_1_IndirectEconomicImpacts_List": 73.7191,
        "_3_3_2_Partnerships_List": 60.4505,
        "_3_3_3_PeaceJusticeInstitutions_List": 70.7638,
        "_3_3_4_Transparency_List": 51.2251,
        "_3_4_1_AntiCorruptionPolicies_List": 54.8626,
        "_3_4_2_AntiCompetitiveBehavior_List": 61.0748,
        "_3_4_3_BusinessEthicsTransparencyPayments_List": 72.1066,
        "_3_4_4_RegulatoryCapturePoliticalInfluence_List": 50.8346,
        "company_idx": 0,
        "company_symbol": "AAPL",
        "timestamp” : "2010-01-01 00:00:00"
    }

	

Authentication

Acquiring an API Key

All HTTP requests made against the Sensefolio API must be validated with an API Key. If you don't have an API Key yet visit the Sensefolio Team to register for one.

Using Your API Key

You may use any server-side programming language that can make HTTP requests to target the Sensefolio API
through the following Python code.

	
import requests
import json

apiKey = ‘XXXXXXXXXXXXX’

headers = {'x-api-key':apiKey,
	'content-type': 'application/json'}

company_list_url = 'https://circular-hawk-253618.appspot.com/companyInfoFull'

score_1_url = 'https://circular-hawk-253618.appspot.com/companyScore?company_idx=1'
actualnews_1_url = 'https://circular-hawk-253618.appspot.com/ActualNews?company_idx=1'
actualtweets_1_url = 'https://circular-hawk-253618.appspot.com/ActualTweets?company_idx=1'
companyInfoFull = requests.get('https://circular-hawk-253618.appspot.com/companyInfoFull', headers=headers).json() companyScore_companyExample = requests.get('https://circular-hawk-253618.appspot.com/companyScore?company_idx=1', headers=headers).json() companyScore_companyExample_ActualNews = requests.get('https://circular-hawk-253618.appspot.com/ActualNews?company_idx=1', headers=headers).json() companyScore_companyExample_ActualTweets = requests.get('https://circular-hawk-253618.appspot.com/ActualTweets?company_idx=1', headers=headers).json()

Security Warning: It's important to secure your API Key against public access. The custom header option is strongly recommended over the querystring option for passing your API Key in a production environment.


Standards and Conventions

Each HTTP request must contain the header Accept: application/json.

Errors and Rate Limits

API Request Throttling

Use of the Sensefolio API is subject to API call rate limiting or "request throttling". This is the number of HTTP calls that can be made simultaneously or within the same minute with your API Key before receiving an HTTP 429 "Too Many Requests" throttling error.

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of an API call.

  • 400 (Bad Request) The server could not process the request, likely due to an invalid argument.
  • 401 (Unauthorized) Your request lacks valid authentication credentials, likely an issue with your API Key.
  • 402 (Payment Required) Your API request was rejected due to it being a paid subscription plan with an overdue balance.
  • 403 (Forbidden) Your request was rejected due to a permission issue, likely a restriction on the API Key's associated service plan.
  • 429 (Too Many Requests) The API Key's rate limit was exceeded; consider slowing down your API Request frequency if this is an HTTP request throttling error. Consider upgrading your service plan if you have reached your monthly API call credit limit for the day/month.
  • 500 (Internal Server Error) An unexpected server issue was encountered.