High-level flow#
- Session Endpoint
- Customer provided data endpoints
- Redirect user to on-boarding flow
- Webhook
- Get data
1. Session Endpoint#
Endpoint to create the session in Sedicii's system.
The "id" contained in the response should be used to configure a personalized URL in order to start the process.
Request#
Input | Description |
---|---|
Method | POST |
Authorization | Basic Auth and API KEY |
Content-Type | application/json |
URL | https://<CUSTOMER_DOMAIN>/api/v1/sessions |
Body#
Example request#
Response#
Body#
2. Customer provided data endpoints#
Endpoints to load pre-defined custom data for a person and / or for a company in Sedicii's system.
2.1. Person's data#
Endpoint to load pre-defined custom data for the person.
Request#
Input | Description |
---|---|
Method | POST |
Authorization | Basic Auth and API KEY |
Content-Type | application/json |
URL | https://<CUSTOMER_DOMAIN>/api/v1/users/~actions/set-customer-user-data |
Body#
Example request#
Response#
Body#
2.2. Company's data#
Endpoint to load pre-defined custom data for the company.
Request#
Input | Description |
---|---|
Method | POST |
Authorization | Basic Auth and API KEY |
Content-Type | application/json |
URL | https://<CUSTOMER_DOMAIN>/api/v1/users/~actions/set-customer-company-data |
Body#
Example request#
Response#
Body#
3. Redirect user to on-boarding flow#
Using a previously created session, you can build a custom URL to allow the end user to start their flow.
Request#
Input | Description |
---|---|
Method | GET |
URL | https://<CUSTOMER_DOMAIN>?redirectUrl={redirectUrl}&sessionId={sessionId}&flowProcessId={flowProcessId}&extraMetadata={encodedJsonExtraMetadata}&variant={productVariant} |
Redirect params#
Parameter | Description |
---|---|
redirectUrl | URL which the user should be redirected after KYC flow. |
sessionId | Identifier (ID) received from session endpoint. |
flowProcessId | (Optional) Chosen BPMN flow. |
extraMetadata | (Optional) Extra data that customer wants to have available in the report. Should be in escaped JSON format. |
variant | (Optional) Chosen product variant. For KYB should be set to kyb. |
Example URL request#
Response#
The end user will be redirected to the on-boarding end user flow.
4. Webhook#
The webhook is a secured POST HTTPS request that will be sent to a customer-defined URL in order to notify changes in the lifecyle of an on-boarding process.
The response payload of a webhook will contain the summary of the on-boarding flow with a unique identifier that will enable the retrieval of the full on-boarding data in JSON format.
4.1. KYC#
Request#
Input | Description |
---|---|
Method | POST |
Authorization | Basic Auth |
Content-Type | application/json |
URL | Endpoint that the webhook will use for notifications |
Body#
{
“id“: “<event id, see below*>“,
“type”: “<event type, see below*>“,
“creationDate”: “2019-02-09T12:38:05+00:00”,
“payload”: {
“authenticatedReportUrl”: <a unique authenticated link that can be used to access the
kyc report>
“user”: {
“reference”: <id of the user in the customer system>
},
“kyc”: {
“id”: <id of the kyc that can be used to retrieve kyc info>,
“state”: “<KYC state, see below*>“
}
}
}
Possible webhook types:
- KYC_END_USER_FLOW_COMPLETED - launched when the end user finishes the web KYC flow.
- KYC_STATE_CHANGED - launched when the KYC state changes.
- KYC_PROCESS_FLOW_COMPLETED - launched when the full KYC process is finished.
Possible webhook KYC states:
- IN_PROGRESS - KYC is correct and still in progress.
- PENDING_REVIEWER_REVIEW - KYC is pending approval from a manual reviewer (CDD: Customer Due Diligence).
- PENDING_INTERVIEW - A video interview invitation has been sent to the customer (EDD: Enhanced Due Diligence).
- COMPLETED_PENDING_APPROVAL - KYC is ready for final approval from manual reviewer (“KYC Conclusions and Observations”).
- COMPLETED - KYC is finished with a successful or failed result.
Example request#
Response#
A customer's system receiving a POST HTTPS request on its webhook must return to Sedicii a response with an HTTPS 200 status.
In case that the customer does not return an HTTPS response with 200 status, then Sedicii's system will retry several times to deliver the request to the customer webhook.
4.2. KYB#
Request#
Input | Description |
---|---|
Method | POST |
Authorization | Basic Auth |
Content-Type | application/json |
URL | Endpoint that the webhook will use for notifications |
Body#
Possible webhook types:
- KYB_STATE_CHANGED - launched when the KYB state changes.
Possible webhook KYB states:
- IN_PROGRESS - KYB is correct and still in progress.
- COMPLETED - KYB is finished with a successful or failed result.
Example request#
curl --location --request POST 'https://' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Y3VzdG9tZXJ1c2VyOmN1c3RvbWVycGFzc3dvcmQ=' \
--data-raw '{
"id":"1985ba31-e089-47ef-8dc9-ae1b280e6f9e",
"type":"KYB_STATE_CHANGED",
"creationDate":"2020-01-01T11:39:26.666Z",
"payload": {
"user": {
"reference":"XXXXXXX"
},
"authenticatedReportUrl": "https://[CUSTOMER_DOMAIN]/admin/kyb/b8a426e5-09a7-4c38-aec3-0998430edbdg?authToken=d89f47dd-9c94-53eb-aaeb-9025c1d8ba95"
"kyb": {
"id":"c4a00aa3-9cf4-40e5-af23-ec923661ec66",
"state":"COMPLETED",
"flowPhase":"CUSTOMER_DEFINED_PHASE"
}
}
}'
Response#
A customer's system receiving a POST HTTPS request on its webhook must return to Sedicii a response with an HTTPS 200 status.
In case that the customer does not return an HTTPS response with 200 status, then Sedicii's system will retry several times to deliver the request to the customer webhook.
5. Get data#
You can call this endpoint to retrieve the information captured by Sedicii.
5.1. KYC#
You can call this endpoint any time after receiving the KYC id via webhook.
Request#
Input | Description |
---|---|
Method | GET |
Authorization | Basic Auth and API KEY |
Content-Type | application/json |
URL | https://<CUSTOMER_DOMAIN>/api/v1/kyc/{kycId}?fields={fields}&format={json|csv} |
Parameters#
Parameter | Description |
---|---|
fields | This parameter can be used to filter KYC data retreived from the server (see below*). |
format | (Optional) The format of the retrieved data. Available values are: json, csv. The default value is json. |
Available fields#
Input | Description |
---|---|
accreditedInvestor | Accredited investor captured information |
addressType | Address type captured information |
addressUserInteractiveOcr | Interactive OCR extracted data for Address |
addressUser | User address captured information |
addressUserImage | Proof of Address evidence |
identityDocumentCountry | Identity document country |
identityDocumentType | Type of identity document |
identityDocumentUserOcr | Identity document user extracted data for live OCR |
identityDocumentUserPicture | Proof of identity document |
identityDocumentUserOcrPicture | Identity document user extracted data for OCR |
sourceOfFunds | Source of funds |
identitySummary | Summary of identity |
formQuestionnaireAnswers | Defined questionnaires with answers |
shareholders | Shareholders related data |
extraMetadata | Provided extra metadata during start of KYC process |
addressUserReview | Address user review |
identityDocumentUserReview | Identity document user review |
summaryReview | Summary review |
identityDocumentReviewerReview | Reviewers review of identity document |
addressReviewerReview | Reviewers review of address |
videoReview | Video evidence review |
kycResult | KYC result |
metadata | Metadata collected during KYC process |
backgroundChecks | Background checks corresponding to captured data |
sourceOfFundReviews | Review of source of funds |
riskProfileHistoricals | Risk profile historical |
riskProfileHistoricalChecks | Risk profile historica checks |
interview | Interview |
identityDocumentUser | All user's identity documents |
identityDocumentUserOcr.identityDocumentSecurityChecks | Identity document security checks for live OCR |
identityDocumentUserOcr.identityDocumentFeatures | Identity document features for live OCR |
identityDocumentUserOcr.identityDocumentBiometrics | Identity document biometrics for live OCR |
identityDocumentUserOcrPicture.identityDocumentSecurityChecks | Identity document biometrics for captured evidence |
identityDocumentUserOcrPicture.identityDocumentFeatures | Identity document features for captured evidence |
identityDocumentUserPicture.identityDocumentBiometrics | Identity document biometrics for captured evidence |
faceImage | Face image evidence |
videoFile | Video file evidence |
livenessUser | User liveness |
genericDocuments | Documents captured during the flow |
genericDocumentReviews | Review for generic documents |
Example request#
Response#
Body#
- To refer for the full KYC response structure see 8.1 section.
5.2. KYB#
You can call this endpoint any time after receiving the KYB id via webhook.
Request#
Input | Description |
---|---|
Method | GET |
Authorization | Basic Auth and API KEY |
Content-Type | application/json |
URL | https://<CUSTOMER_DOMAIN>/api/v1/kyb/{kybId}?fields={fields}&format={json|csv} |
Parameters#
Parameter | Description |
---|---|
fields | This parameter can be used to filter KYB data retreived from the server (see below*). |
format | (Optional) The format of the retrieved data. Available values are: json, csv. The default value is json. |
Available fields#
Input | Description |
---|---|
metadata | Metadata collected during KYB process |
genericDocuments | Documents captured during the flow |
genericDocumentReviews | Review of each document captured during the flow |
extraMetadata | Provided extra metadata during start of KYB process |
formQuestionnaireAnswers | Defined questionnaires with answers |
loanNetCalculations | Loan net calculations |
company | Company associated to KYB |
consent | List of consents given by user |
Example request#
Response#
Body#
- To refer for the full KYB response structure see 8.2 section.
5.3. Self Declared User Data#
You can call this endpoint any time using the user reference after setting user data via endpoint. The user reference is the parameter (reference) that was provided in the session endpoint call.
Request#
Input | Description |
---|---|
Method | POST |
Authorization | Basic Auth and API KEY |
Content-Type | application/json |
URL | https://<CUSTOMER_DOMAIN>/api/v1/users/~actions/get-self-declared-user-data |
Body#
Example request#
Response#
Body#
5.4. Shareholders#
You can call this endpoint any time using the company id which can be obtained from KYB data endpoint.
Request#
Input | Description |
---|---|
Method | GET |
Authorization | Basic Auth and API KEY |
Content-Type | application/json |
URL | https://<CUSTOMER_DOMAIN>/api/v1/shareholders?companyId={companyId}&userId={userId}&offset={offset}&limit={limit}&sort={sort} |
Parameters#
Parameter | Description |
---|---|
companyId | (Optional) Identification given by Sedicii to the company. |
userId | (Optional) Identification given by Sedicii to the user. |
offset | (Optional) Number of shareholders to be excluded before the beginning of the result set. |
limit | (Optional) Maximum number of shareholders returned form the consultation. |
sort | (Optional) Order given to shareholders returned by consultation. It may be PARAM,ORDER; where PARAM is modificationDate or creationDate and ORDER is asc or desc. |
Example request#
Response#
Body#
6. Get files#
You can call this endpoint to retrieve documents (images and videos).
6.1. KYC#
You can call this endpoint using fileReference obtained from step 5.1 (KYC data).
Request#
Input | Description |
---|---|
Method | GET |
Authorization | Basic Auth and API KEY |
Content-Type | application/json |
URL | https://<CUSTOMER_DOMAIN>/api/v1/documents/{fileReference} |
Response#
The response will contain the requested file.
6.2. KYB#
You can call this endpoint using fileReference obtained from step 5.2 (KYB data).
Request#
Input | Description |
---|---|
Method | GET |
Authorization | Basic Auth and API KEY |
Content-Type | application/json |
URL | https://<CUSTOMER_DOMAIN>/api/v1/documents/{fileReference} |
Response#
The response will contain the requested file.
7. Get reports#
You can call this endpoint to retrieve reports with the specified file format.
7.1. KYC#
You can call this endpoint at any time after receiving the KYC id via webhook.
Request#
Input | Description |
---|---|
Method | POST |
Authorization | Basic Auth and API KEY |
Content-Type | application/json |
URL | https://<CUSTOMER_DOMAIN>/api/v1/kyc/{kycId}/~actions/get-report |
Body#
Example request#
Response#
The response will contain the requested file.
7.2. KYB#
You can call this endpoint at any time after receiving the KYB id via webhook.
Request#
Input | Description |
---|---|
Method | POST |
Authorization | Basic Auth and API KEY |
Content-Type | application/json |
URL | https://<CUSTOMER_DOMAIN>/api/v1/kyb/{kybId}/~actions/get-report |
Body#
Example request#
Response#
The response will contain the requested file.
8. Full response example#
8.1. KYC#
8.2. KYB#
9. Delete end customer data#
You can call this endpoint to delete end customer data.
This can be done at any time after creating the Session using the session endpoint with the same external userReference parameter.
Request#
Input | Description |
---|---|
Method | DELETE |
Authorization | Basic Auth and API KEY |
Content-Type | application/json |
URL | https://<CUSTOMER_DOMAIN>/api/v1/users?reference={userReference} |
Example request#
Response#
The response will contain an empty body with an HTTPS status code 204.