# 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

  1. Schema
{
    status	string
            example: success
    message	string
            example: Access token created
    payload	{
        access_token string
                     example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
    }
}
  1. Example value
{
  "status": "success",
  "message": "Access token created",
  "payload": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY27DkwIiwibmFtZSI7IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk9yJV_adQssw5c"
  }
}

Bad Request

  1. 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
}
  1. Example value
{
  "status": "failed",
  "message": "Bad request",
  "description": "Identifier or password incorrect"
}

# Internal server error

  1. Schema
{
    status:	    string
                example: failed
    message	    string
                example: Internal server error
    description	string
                example: We currently experience issues with our services
}
  1. 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