Photo-based authenticity check

API technical documentation for reading and verifying an identity document from a photo

This API is designed to verify the authenticity of an identity document based on images of the document. It also allows you to extract the textual information related the user.

Send a request

The service is accessible through an https api.

You must sent a POST request to {API}/flow/authenticity/photo with a form

Content-Type: multipart/form-data

containing those fields:

• data a json encoded object with those properties:

  {
       "api_key": "str"
       "business_hash": "str" 
       "doc_type": "str" 
       "country_code": "str"
       "first_name": "str" 
       "last_name": "str" 
   }

• photos a repeatable field which contains an image or a pdf document:

You can send a maximum of two documents.

The mime-type used (it must be one of image/* or application/pdf for a pdf document).

The accepted extensions are png, jpeg, webp and pdf.

The limit of the upload per photo is set to 10MB

Provide an extension to your filename: it must correspond to the mime/type used.

If you have only one image containing both, front and back side of the document,

Parameter	Mandatory	Type	Note
business_hash*	yes	string	This is a string provided by your contact @ShareID
api_key*	yes	string	This is a string provided by your contact @ShareID
doc_type	no	string	One of id_card, passport, driver_permit, residency_permit
country_code	no	string	a lowercase ISO 3166-1 alpha-2 country code, eg: "fr"
first_name	no	string	User First name
last_name	no	string	User Last name

* Your credentials are your responsibility. You must never enter them in hard copy in your application.

curl -F 'data={"api_key":"***","business_hash":"***","first_name":"robert"}' -F "photos=@user_permit_6783_recto.png;type=image/png" -F "photos=@user_permit_6783_verso.png;type=image/png" --trace-ascii log https://{API}/flow/authenticity/photo

if there's a timeout in the request the http code will be 408

Get the result

As soon as the request processing is finished, you will receive an http code 200 with a document described below:

{
  "doc_type": str,
  "country_code": str,
  "doc_model": str,
  "ocr": {
    "surname": str,
    "name": str,
    "sex": str,
    "nationality": str,
    "birth_date": date,
    "birth_place": str,
    "alternate_name": str,
    "doc_num": str,
    "expiration_date": date,
    "height": str,
    "issuance_date": date,
    "address": str
  },
  "security": {
  },
  "reason": ,
  "verdict": bool
}

Reasons

1	doc_expired	document expired
12	Date_not extracted	Expiration or Issuance date couldn't be extracted
21	first_name_mismatch	Mismatch in first name
22	last_name_mismatch	Mismatch in last name
3	low_quality	Image quality not sufficient (example: low light)
4	no_doc_found	Missing document in the images
5	side_missing	Missing side (front or back)
6	wrong_mrz	MRZ is wrong or couldn't be extracted
7	blur_img	Blurry images
8	low_resolution	Image resolution not sufficient
9	inversed_name	Name and surname are inversed
10	doc_spoof	Document shown on a screen
11	doc_print	Document printed
111	doc_auth	Document authentic
100	doc_not_auth	Document not authentic (forgery or counterfeit document)

Document field

Field	Type
doc_type	string	one of "id_card" "passport" "driver_permit" "residency_permit"
doc_model	string	internal model reference detected
country_code	string	country code ISO 3166-1.alpha-2
doc_front	string | null	base64 encoded image of document front page
doc_back	string | null	base64 encoded image of document back page