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
}

Field	Type
doc_type	string	one of "id_card" "passport" "driver_permit" "residency_permit"
country_code	string	country code ISO 3166-1.alpha-2
doc_model	string	internal model reference detected
ocr	object / {}	data extracted from the document
security	object / {}	detailed security checks
reason	string/""	If verdict is false, this will indicate the reasons of the rejection
verdict	bool	True if document is authentic, false if fraud suspected or other reasons

Reasons

reason	description
doc_expired	document expired
doc_expired_5y	Document expired since less than 5 years
no_doc_found	Missing document in the images
side_missing	Missing side (front or back)
missing_mrz	MRZ couldn't be extracted
wrong_mrz	MRZ is wrong
date_not extracted	Expiration or birth date couldn't be extracted
low_quality	Image quality not sufficient (example: low light)
blur_img	Blurry images
low_resolution	Image resolution not sufficient
first_name_mismatch	Mismatch in first name
last_name_mismatch	Mismatch in last name
inversed_name	Name and surname are inversed
doc_spoof	Document shown on a screen
doc_print	Document printed
doc_not_auth	Document not authentic (forgery or counterfeit document)
doc_auth	Document authentic

Document field