Getting started
Get Access to APIAuthenticationMaking your first requestGuides
Generate Doc X-RayGenerate Bank X-RayGenerate Financial X-RayGenerate ESG X-RayGenerate Manager X-RayConcepts
OverviewRequestReportsMediumDoc X-RayBank X-RayFinancial X-RayESG X-RayManager X-RayResources
API versioningWebhooksUploading a mediaAdd a creator to your requestTesting environmentOrganization & MembersSecuritySupportOctober x Financial X-Ray
In this page, you will find a step-by-step guide that will walk you through the generation of a Financial X-Ray using the October Connect API.
In this guide, you will generate your first Financial X-Ray using the following steps:
- Create a request
- Generate financial statement
- Retrieve Financial X-Ray
- Review the analysis
1. Create a request
For the first step of the analysis, create a request with a POST call to /requests
In the example below, all fields are mandatory except if mentioned otherwise:
POST /requests
{
"code": {
"type": "siren",
"id": "514673987"
}
}
The API will answer with additional fields on the request:
{
"request": {
"id": "[requestId]", // Unique ID of the request
"code": {
"type": "siren",
"id": "514673987"
}
"status": "pending_analysis",
"stage": "1.1",
...
}
}
If you wish to re-fetch the data of a request, you can make a GET call to /requests/[id]
.
2. Generating the Financial X-Ray
We currently have two ways to generate a financial X-Ray which are also complementary to one another. Indeed, you can either upload a medium or add notes to the request
2.1 Upload a medium
The upload of a document is done in 3 steps:
POST /media
to our API with the type and metadata of the file you wish to send us. You will receive data needed to upload to S3.- Use the following
name
in order to categorise the document - Upload the file to AWS S3 using the data received from the previous step.
- Once the upload is successful, call
POST /media/[id]
to set thestatus
toonline
and optionally add the period and date of the document.
certified_financial_statement, interim_financial_statement, other
To read a detailed step-by-step guide, please read Resource: Uploading a media
2.2 Notes
The notes
field of the request will hold all the business information and financial data that you will send us.
To update a request:
POST /requests/[requestId]
to our API with the body containing anotes
object.- Include the fields tagged “mandatory” in the
notes
object
Name | Description | Type | Mandatory | Possible values |
holding | Is the company a holding? | boolean | Yes | |
workforceNumber | How many people are working in the company? | number | Yes | Minimum 1 |
equity | Equity of the company | number (in cents) | Yes | |
revenue | Revenue of the company for the last year | number (in cents) | Yes | |
amortizationDepreciation | Amount of amortization and depreciation | number (in cents) | Yes | |
netIncome | Net income of the company/holding for the last year | number (in cents) | Yes | |
interestExpense | Interest payable on any borrowings (bonds, loans, convertible) | number (in cents) | Yes | |
cashAvailable | Amount of cash available | number (in cents) | Yes | |
totalFixedAssets | Total amount of fixed assets | number (in cents) | Yes | |
totalAssets | The sum of the company’s assets | number (in cents) | Yes | |
shortTermDebt | Financial debt which must be repaid within at max one year | number (in cents) | Yes | |
totalDebt | Total debt amount | number (in cents) | Yes | |
currentLiabilities | Financial obligations that are expected to be paid off within a year | number (in cents) | Yes | |
esgGenderDiversity | What is the percentage of women in the workforce of the company? | enum | No | 0-20% , 21-40% , 41-60% , 61-80% , 81-100% |
esgLabels | Does the company have any ESG label or certification? | array of text | No | E.g: lucie , ecovadis , b-corp , …
If there are no labels or certification, use none |
esgEmployeeProtection | Number of current employees that, thanks to the your financing, the company would be able to retain instead of potentially laying off (e.g. ability to pay wages, continue operations, etc.) | enum | No | 0 , 1 , 2-5 , 6-10 , 10+ |
esgJobCreation | Number of new workers that the your financing would allow the company or require the company to hire (e.g. by enlarging existing teams, creating new teams or new single positions, etc.) | enum | No | 0 , 1 , 2-5 , 6-10 , 10+ |
3. Retrieve Financial X-Ray
Once you have uploaded a media, our Financial X-Ray will be launched automatically and will return an analysis within a few minutes. However, if our OCR fails, we use an alternative extraction method that can take up to 48h.
To wait for the end of the request analysis, you have two options:
- Poll regularly the API to check when a new report is available; or
- Use webhooks to be notified when a new report has been created. (Our recommendation)
When the report has been created, refer to the cases below to know the next steps.
Polling the API
Make GET HTTP requests to /requests/[requestId]
to receive the latest data of the request.
Make GET HTTP requests to /reports?source=magpie&request=[requestId]
to receive the Financial X-Ray reports associated to the request
Using webhooks
We provide a webhook that will update you when a new report is generated:
new_report
when a new report has been created
{
"event": "new_report",
"requestId": "[requestId]",
"reportId": "[reportId]"
}
After receiving webhooks, retrieve the data of the request or offer using the following GET HTTP calls:
GET /requests/[requestId]
GET /reports/[reportId]
4. Review the analysis
Once you have received the update using either the API calls or webhooks from the previous section, you can retrieve the Financial X-Ray report using the following GET HTTP call:
GET /reports/[reportId]
The API will answer with additional fields on the report:
{
"report": {
"id": "[reportId]",
"request": "[requestId]",
"source": "magpie",
"raw": {
"criterias": {
"totalFixedAssetsTotalAssets": {
"value": 0.0867204257133327,
"source": "magpie"
}
},
"probabilityOfDefault": 0.039524826661933084,
"riskClass": 3,
"reasons": [
{
"typeCode": "trafficLight",
"sentiment": "good",
"weight": 0.039524826661933084,
"criteria": {
"supplierScore": "yellow"
}
},
...
]
}
}
← Previous