Photo-based authenticity API

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

Authenticity-photo 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:

File types	Size limits	Other requirements
PNG (.png) JPEG (.jpeg and .jpg) WEBP (.webp) PDF (.pdf)	The total limit of the upload (all photo/doc included) is set to 10MB Low-resolution: 224px x 224px You can send a maximum of 2 documents.	Provide an extension to your filename: it must match the mime/type used. The mime-type must be: image/* or application/pdf.

• If you have only one image containing both, front and back side of the document, you can use it and the analysis will detect both sides.

• The order of the documents is not important.

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": {
  },
  "security": {
  },
  "reason": ,
  "verdict": bool,
  "flow_id": str
}

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	document model reference (year of first issue)
ocr	object / {}	data extracted from the document, example: "ocr": { "name": str, "surname": str, "sex": str, "nationality": str, "birth_date": date-ISO 8601, "birth_place": str, "doc_num": str, "expiration_date": date-ISO 8601, "issuance_date": date-ISO 8601, "address": str }
security	object / {}	detailed security checks, example: "security": { "mrz_vs_viz": true, "printing_technique": False, "integrated_photo": null, //Not verified "streaks_around_the_card": true, "info_coherence": true }
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
flow_id	str	The unique identifier of your request (you are advised to keep track of it)

Reasons

reason	description
doc_expired	document expired
doc_expired_5y	Document expired since less than 5 years
missing_doc	Missing document in the images
missing_front	Front of the document not found
missing_back	Back of the document not found (only front is found)
sides_inconsistency	Front and back do not belong to the same document model
out_of_scope	Document not accepted
missing_mrz	MRZ not found or 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
name_not_extracted or surname_not_extracted	Name or surname couldn't be extracted

Document field