Skip to content

Photo-based authenticity API

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.

This API allows you to check the authenticity of an identity document in a basic way, if you need an advanced authenticity verification, we recommend using video based verification via SDKs.

Here is a summary of the verifiations:

Photo Video (SDK)
Document manipulation x x
Document MRZ and level 1 security elements x x
Document level 2 security elements x
Document liveness x

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"
       "tags": optional ["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 ofid_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
tags no array of string Tags represent a list of tags. Each tag is just a keyword you can attach to your call. This could be a way to classify your calls to the api. A tag must be match by this regular expression "^[a-z0-9_]{4,16}$"

Warning

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

Curl example:

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
}
FieldType
doc_typestringone of "id_card" "passport" "driver_permit" "residency_permit"
country_codestringcountry code ISO 3166-1.alpha-2
doc_modelstringdocument model reference (year of first issue)
ocrobject / {}

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
    }
securityobject / {}

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
    }
reasonstring/""If verdict is false, this will indicate the reasons of the rejection
verdictboolTrue if document is authentic, false if fraud suspected or other reasons
flow_idstrThe unique identifier of your request (you are advised to keep track of it)

Reasons

reason description reason_id (informational)
doc_expired document expired 1
doc_expired_5y Document expired since less than 5 years 2
missing_doc Missing document in the images 4
missing_front Front of the document not found 5
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 66
wrong_mrz MRZ is wrong 6
date_not_extracted Expiration or birth date couldn't be extracted 12
low_quality Image quality not sufficient (example: low light) 3
blur_img Blurry images 7
low_resolution Image resolution not sufficient 8
first_name_mismatch Mismatch in first name 21
last_name_mismatch Mismatch in last name 22
inversed_name Name and surname are inversed 9
doc_spoof Document shown on a screen 10
doc_print Document printed 11
doc_not_auth Document not authentic (forgery or counterfeit document) 100
doc_auth Document authentic 111
name_not_extracted or surname_not_extracted Name or surname couldn't be extracted