# Get started
ShareID SDK requires APIs to communicate with the backend.
The communications with the backend has a token-based authentication system.
If you don't have your business identifier and secret key yet, read the business credentials documentation
# Authentication
For security purposes, the ShareID authorization service requires a token per API call. This means that each demand requires a new token.
Access tokens must be included in the header of all requests made to the API.
🖋️ Note:
You will need your API Key to generate your tokens.
# 1. API Key
Upon your registration with ShareID, you will receive an email to generate your business Identifier and a Business Secret Key also called API Key.
Please make sure you store them in a safe and secure place as they are your credentials to access ShareID.
⚠️ Important:
Your crediantials are your responsability. You must never expose them in your frontend.
# 2. Access Token
# 2.1 Request token
A token request is a POST request with your business identifier and business secret key in ShareID's autorization service:
POST /authorization/v1/auth_business/login
{
"business_identifier": "32993bb8-baf1-4659-84f6-ab08799f6f75",
"business_secret": "my_secret_password"
}
# 2.2 Request reponses
When you POSTyour request, the server can return different responses as described in the table below:
| Code | Description |
|---|---|
| 200 | Login successful |
| 400 | Bad request |
| 500 | Internal server error |
Request successful
- Schema
{
status string
example: success
message string
example: Access token created
payload {
access_token string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
}
}
- Example value
{
"status": "success",
"message": "Access token created",
"payload": {
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY27DkwIiwibmFtZSI7IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk9yJV_adQssw5c"
}
}
Bad Request
- Schema
{
status string
example: failed
message string
example: Bad request
description {
oneOf ->
[
example: List [ "There is an error on business_identifier" ]
]
string
example: Identifier or password incorrect
}
example: Identifier or password incorrect
}
- Example value
{
"status": "failed",
"message": "Bad request",
"description": "Identifier or password incorrect"
}
# Internal server error
- Schema
{
status: string
example: failed
message string
example: Internal server error
description string
example: We currently experience issues with our services
}
- Example value
{
"status": "failed",
"message": "Internal server error",
"description": "We currently experience issues with our services"
}
In this case, please get in touch with ShareID's support.
# Onboarding demand result
An onboarding_demand is the demand you send to ShareIDs backend through the SDK to launch the identity verification process.
It can be used for a ponctual identity verification or for the onboarding of the users for authentication.
The setup of this demand per SDK is available on each SDK documentation.
This section describes how you retrieve ShareIDs results after an identity verification or a user onboarding in the authentication with official identity service.
# 1. Callback url setup
When creating your onboarding demand, you have set a callback-url.
ShareID will send you the results on this url as soon as they are available.
🖋️ Note:
You should implement a listner on the callback url you provided for the onboarding demand.
# 2. Response
Once the verification process is finished, ShareID will send you a response on the callback-url you have set when initiating the identity verification.
🖋️ Note:
All the dates follow the norm ISO 8601
The response format is described below:
type OnboardingDemandResult = {
id: string,
result: 'validated' | 'rejected',
reason: string | null,
reason_id: string | null,
metadata: {
external_id: string,
[key: string]: string // other metadata that you have sent
}
document_front: string | null, //secured url
document_back: string | null, //secured url
document: {
type: {
document_type: "id_card" | "passport" | "driver_permit" | "residency_permit",
document_year: string //ex: 1994
country: string //country code ISO 3166-1. ex: fr
},
ocr: {
doc_num: string | null,
surname: string | null,
alternate_name: string | null,
widow_of: string | null,
mariage_name: string | null,
name: string | null,
sex: string | null,
date_of_birth: string | null,
place_of_birth: string | null,
size: string | null,
address: string | null,
expiration_date: string | null,
issuance_date: string | null,
authority_issuer_fr: string | null,
type: string | null,
country_code: string | null,
nationality: string | null,
height: string | null,
eye_color: string | null,
issuance_date_place: string | null,
remark: string | null,
date_place_of_birth: string | null,
category: string | null,
issuance_date_by_category: string | null,
expiration_date_by_category: string | null,
complementary_info: string | null,
surname_name: string | null,
personal_number: string | null,
particularities: string | null,
start_date: string | null,
city: string | null,
codes: string | null,
signature: string | null,
issuance_place: string | null,
parent_name: string | null,
fiscal_code: string | null,
birth_certificate_details: string | null,
notes: string | null,
authority_date_issuer: string | null,
foreigner_authority: string | null,
management_number: string | null,
passport_number: string | null,
record_number: string | null,
id_card_number: string | null,
pin: string | null,
state_of_birth: string | null,
family_attitude: string | null,
place_of_origin: string | null,
issuance_date_place_authority: string | null,
entry_date: string | null,
reference: string | null,
surname_at_birth: string | null,
issuance_date_authority: string | null,
occupation: string | null,
company: string | null,
national_name: string | null,
birth_name: string | null,
blood_type: string | null,
father_surname: string | null,
father_name: string | null,
mother_name: string | null,
mother_surname: string | null,
control: string | null,
Profession: string | null,
marital_statue: string | null,
children: string | null,
authority_issuer: string | null,
}
} | null
}
# 3. Rejection reasons
ShareID provides you with 8 possible rejection reasons presented below by ID :
| Rejection ID | Rejection Value |
|---|---|
| 1 | document expired |
| 2 | document unusable (old, wrong capture) |
| 3 | hidden elements in the document |
| 4 | low resolution |
| 5 | printed or scanned document |
| 6 | fraud suspicion on document |
| 7 | fraud suspicion on liveness or facial recognition |
| 8 | fraud suspicion on both document and liveness |
# 4. Mapping table
The OCR output in the response above displays all the information available in the document provided by the user.
The list of fields can differ from a document to another and from a country to another.
In case you need to integrate these fields per documents, ShareID can provide you with a mapping per country
⚠️ Important:
Some fields are not available depending on the document type and country:
for example, the date of birth does not exist on the Romanian ID card
The maping table below provides all the possible variables that can be extracted from a user document.
| Key | Type | Description |
|---|---|---|
| doc_num | text | document number |
| surname | text | surname |
| alternate_name | text | alternate name |
| widow_of | text | widow of |
| mariage_name | text | mariage name |
| name | text | name |
| sex | text | sex |
| date_of_birth | date | date of birth |
| place_of_birth | text | place of birth |
| size | text | size |
| address | text | address |
| expiration_date | date (ISO 8601) | document expiration date |
| issuance_date | date (ISO 8601) | document issuance date |
| type | text | document type (diplomatic, driver licence type A, B) |
| country_code | text | country code |
| nationality | text | nationality |
| height | text | height |
| eye_color | text | eye color |
| issuance_date_place | text | document issuance place |
| remark | text | issuer remarks |
| date_place_of_birth | text | date and place of birth when aggregated in the same field within the document |
| category | text | category (mainly for driver licence) |
| issuance_date_by_category | text | issuance date per category |
| expiration_date_by_category | text | expiration date per category |
| complementary_info | text | complementary information provided by the document issuer |
| surname_name | text | surname and name |
| personal_number | text | personal number |
| particularities | text | particularities provided by the document issuer |
| start_date | date (ISO 8601) | document start date ( mainly for driver licence) |
| city | text | city |
| codes | text | codes provided by the issuer authority |
| signature | text | signature |
| issuance_place | text | document issuance place |
| parent_name | text | parent name |
| fiscal_code | text | fiscal code |
| birth_certificate_details | text | birth certificate details |
| notes | text | notes provided by the issuer authority |
| authority_date_issuer | text | authority issuing the document |
| foreigner_authority | text | foreigner authority |
| management_number | text | management number |
| ukf | text | registration number as british citizen |
| passport_number | text | passport number when available on another ID document. This is different from the doc_num which is the document number for all type of documents |
| record_number | text | record number |
| id_card_number | text | id card number when available on another ID document. This is different from the doc_num which is the document number for all type of documents |
| pin | text | pin |
| state_of_birth | text | state of birth |
| family_attitude | text | family attitude |
| can | text | commun account number |
| place_of_origin | text | place of origin |
| issuance_date_place_authority | date (ISO 8601) | issuance date, place and authority when aggregated in the same field within the document |
| entry_date | text | entry date to the country |
| reference | text | reference |
| surname_at_birth | text | surname at birth |
| issuance_date_authority | text | issuance date and authority when aggregated in the same field within the document |
| occupation | text | occupation |
| company | text | company |
| national_name | text | national name |
| birth_name | text | birth name |
| blood_type | text | blood type |
| father_surname | text | father surname |
| father_name | text | father name |
| mother_name | text | mother name |
| mother_surname | text | mother surname |
| control | text | control |
| profession | text | occupation |
| marital_status | text | marital status |
| children | text | children |
| authority_issuer | text | authority who issued the document |