Introduction

The Appruve REST API is a core building block of the Appruve Platform. The API is built using RESTful endpoints and standard HTTP verbs, and uses HTTP response codes to indicate API errors. You can use the API to verify the identities of persons and businesses, and is optimized for face recognition flows.

Authentication

To access the Appruve API, you'll need an Access Token, commonly referred as token in code samples. You can create and manage your Access Tokens in the Dashboard.

To use your token, simply provide it as part of the authorization header when you make a request. Tokens use the bearer authorization header when you make a request. This just means you need to specify the bearer type in the header.

                  
    $ curl \
      -s https://api.appruve.co/verifications/773b72e3-35da-429f-bdbd-cf57a403c668 \
      -H 'Authorization: Bearer token' \
      -H 'Accept: application/json' \
                  
                

Integration Use Cases

Identity Verification Using Video Selfie And ID Document

This flow requires the following steps:

  1. Call OCR Endpoint
  2. Get Signed Url
  3. Upload Selfie Video
  4. Get Verification Result

Call OCR Endpoint

Call this endpoint to extract the ID card details and present to the user to confirm.

POST https://api.appruve.co/v1/verifications/ocr/:country/:id_type
      
  $ curl -X POST \
    https://api.appruve.co/v1/verifications/ocr/gh/passport \
    -H 'Authorization: Bearer token' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
    -F id_image=path-to/passport.jpg
      
                      
      
  {
    "id_details": {
        "first_name": "John",
        "last_name": "Doe",
        "passport_number": "G0756012",
        "date_of_birth": "07 JUL 1956",
        "date_of_issue": "25 APR 2014",
        "date_of_expiry": "24 APR 2019",
        "place_of_issue": "",
        "id_photo": "url"
    },
    "transaction_reference": "8b41b360-1457-47dc-a44a-bd8bb7f90a15"
  }
      
                      

Get Signed Url

Call this endpoint to get a signed url for uploading the video selfie.

POST https://api.appruve.co/v1/verifications/video/signed_url
                        
  curl -X POST \
    https://api.appruve.co/v1/verifications/video/signed_url \
    -H 'Authorization: Bearer token' \
    -H 'Content-Type: application/json' \
    -d '{
      "transaction_reference": "8b41b360-1457-47dc-a44a-bd8bb7f90a15",
      "filename": "video_selfie.mp4",
      "callback_url": "https://my-url/callback"
    }'
                        
                      
                        
{
  "signed_url": "https://signed-url"
}
                        
                      

Upload Selfie Video

Make a Binary File Upload PUT request to the signed url. A required x-goog-meta-transaction-ref header must be added to the request. The value of this header should be the transaction_reference value returned from the ocr endpoint.

                        
  curl -X PUT \
    'https://signed_url' \
    -H 'x-goog-meta-transaction-ref: 8b41b360-1457-47dc-a44a-bd8bb7f90a15'
                        
                      

A status code of 200 is returned upon successful upload

Get Verification Result

There are two ways to get a verification result.

For real-time results implement a POST endpoint to accept callbacks. Pass this endpoint URL to the Get Signed Url endpoint. After a verification job has been processed, we will pass the resulting Verification Data to the pre-defined callback URL.

You can also manually call the Get Verification Result endpoint to get the Verification Data.

GET https://api.appruve.co/v1/verifications/:ref
                        
  curl -X GET \
    https://api.appruve.co/v1/verifications/773b72e3-35da-429f-bdbd-cf57a403c668 \
    -H 'Authorization: Bearer token' \
                        
                      
                        
  {
    "id": "773b72e3-35da-429f-bdbd-cf57a403c668",
    "confidence_score": "90.15",
    "id_type": "passport",
    "country_code": "gh",
    "result_text": "Verification Successfully Completed",
    "status": "success",
    "created_at": "2018-12-03T09:49:27Z",
    "id_details": {},
    "face_on_id_document": "url",
    "face_on_video": "url"
  }
                        
                      

Web Implementation

Live video capture is not widely supported by browsers. Checkout MediaRecorder and its browser compatibility. Also checkout the WebRTC implementation. If you are working within a Node.js environment check out Video.js Record.

Confidence Score

Each verification is assigned a Confidence Score. The confidence score is a number between 0 and 100. The higher the score the greater the confidence in that identity. We arrive at a Confidence Score by aggregating the scores of the facial match and scores from comparing the ID details to our data sources.

Verification Status

Each verification is assigned a "status". The "status" value can be "success", "provisional", or "failed" depending on the value of the Confidence Score.