API

This documentation explains the server API and how to handle completed verifications.
General
Some clients are legally required to hold a copy of their customers' Personal data. In this case you can retrieve any of the data relative to your Authentications from our API: 
The Personal data required in the Authentication (i.e first name, last name, document number, identity score)
The Documents submitted by the User (i.e. ID document pictures, selfie videos)
Any metadata relative to the Authentication (i.e. user agent, timestamp, user references)
In general, we advice our clients to request & store as few information as possible about their users on their side. This decreases their data liability to the extent, that they only have to protect information they really need. If you only care that a user has been verified or is over a certain age, then you should store this as a boolean (true/false) about them, once we have completed the identity or age verification of that user.
API Key Information
In your previous sections we have worked with client side integrations. We used there the publishable API key. Since we are now working in your own server environment, you need to use the secret API key. Please never share this API key, since it gives access to your user data. If you leak this API key, a potential bad actor could retrieve and leak information about the identity verification of your users. 
Be very careful with the secret API key. Never share it or send it through unencrypted communication methods!
How to Send a Request
Please don't forget to use your secret API key in the header. The code below shows an example request from to our API. Your own functions should look similar like this:
Javascript
Python
Ruby
PHP
Go
Javascript
// Example using the the request module
const request = require('request');
​
// You received this key through our SDK or integration. 
// This key is related to a successfull authentication of a user
const authentication_key = '12345-12345-12345-12345' 
​
function getAuthenticationByKey(authentication_key) {
​
    const options = {
        url: 'https://app.passbase.com/api/v1/authentications/by_key/' + authentication_key,
        method: 'GET',
        headers: {
            'Authorization': 'YOUR_SECRET_API_KEY',
            'Accept': 'application/json'
        }
    };
    
    request(options, function(err, res, body) {
        let json = JSON.parse(body);
        console.log(json);
    });
}
Python
# Example using the the request module
import requests 
​
authentication_key = "12345-12345-12345-12345"
​
def getAuthenticationByKey(authentication_key):
  URL = "https://app.passbase.com/api/v1/authentications/by_key/" + authentication_key
  HEADER = {
    "Authorization":"YOUR_SECRET_API_KEY",
    "Accept":"application/json"
  }
​
  r = requests.get(url = URL, headers = HEADER)
  data = r.json() 
  print(data)
Ruby
authentication_key = "12345-12345-12345-12345"
​
response = Faraday.get("https://app.passbase.com/api/v1/authentications/by_key/" + authentication_key) do |req|
  req.headers['Authorization'] = "APIKEY #{your_api_key}"
end
​
response.body
PHP
// Example using the the Gruzzle
use GuzzleHttp\Client;
​
// You received this key through our SDK or integration.
// This key is related to a successful authentication of a user
$authentication_key = '12345-12345-12345-12345';
​
$client = new GuzzleHttp\Client([
    'base_uri' => 'https://app.passbase.com/api/v1',
    'headers' => [
        'Authorization' => 'YOUR_SECRET_API_KEY',
        'Accept' => 'application/json',
    ]
]);
// Send a request to https://app.passbase.com/api/v1/authentications/by_key/{$key}
$response = $client->request('GET', "authentications/by_key/{$authentication_key}");
// Store the response in variable
$body = $response->getBody()->getContents();
Go
package main
 
import (
	"fmt"
	"io/ioutil"
	"log"
	"net/http"
	"time"
)
​
// You received this key through our SDK or integration.
// This key is related to a successful authentication of a user
const authentication_key = "12345-12345-12345-12345"
 
func getAuthenticationByKey(authKey string) {
​
  req, err := http.NewRequest("GET", "https://app.passbase.com/api/v1/authentications/by_key/" + authKey, nil)
  if err != nil {
    log.Fatal("Error reading request. ", err)
  }
​
  req.Header.Add("Authorization", "YOUR_SECRET_API_KEY")
  req.Header.Add("Accept", "application/json")
​
  client := &http.Client{Timeout: time.Second * 10}
​
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal("Error reading response. ", err)
  }
  defer resp.Body.Close()
​
  body, err := ioutil.ReadAll(resp.Body)
  if err != nil {
    log.Fatal("Error reading body. ", err)
  }
​
  fmt.Printf("%s\n", body)
}
get
Get Authentication by key
https://app.passbase.com /api/v1/authentications/by_key/:authentication_key
Retrieves the Authentication specified by authentication_key 
Request
Response
Request
Path Parameters
authentication_key
required
string
The UUID of the Authentication you want to retrieve
Headers
Authorization
required
string
Your secret API key found in the dashboard. 
Must respect the "APIKEY api_key" format.
Content-Type
required
string
application/json
Response
200: OK
{
  "authentication": {
    "key": "29884359-fb70-478b-ba06-53d48b210aa0",
    "reviewed_at": null,
    "review_status": null,
    "created_at": "2020-03-09T12:05:31.877Z",
    "additional_attributes": {
      "identifier": "user@email.com",
      "country_code": "us",
      "identifier_type": "email"
    },
    "authentication_assessments": {
      "facematch": {
        "value": "0.9"
      },
      "id_authenticity": {
        "value": "0.9"
      },
      "liveness": {
        "value": "0.9"
      },
      "overall": {
        "value": "0.9"
      }
    },
    "authentication_document": "PASSPORT",
    "additional_document": null,
    "documents": [
      {
        "document_type": "PASSPORT",
        "document_information": [
          {
            "key": "FIRST_NAMES",
            "value": "John"
          },
          {
            "key": "LAST_NAME",
            "value": "Doe"
          },
          {
            "key": "DOCUMENT_NUMBER",
            "value": "12345"
          },
          {
            "key": "NATIONALITY",
            "value": "United States"
          },
          {
            "key": "DATE_OF_BIRTH",
            "value": "1960-12-12"
          }, ...
        ]
      }
    ],
    "end_user": {
      "customer_user_id": "user-12345"
    }
  },
  "status": "success",
  "code": "200"
}
get
List completed Authentications
https://app.passbase.com /api/v1/authentications
Retrieves a list of completed Authentications for the owner of the API key
Request
Response
Request
Headers
Authorization
required
string
Your secret API key found in the dashboard.
Must respect the "APIKEY api_key" format.
Content-Type
required
string
application/json
Query Parameters
from_created_at
optional
integer
UNIX timestamp initial creation date
to_created_at
optional
integer
UNIX timestamp final creation date
limit
optional
integer
Max result length
offset
optional
integer
Specifies the items to skip when returning the result list
Response
200: OK
{
  "authentications": [ 
    {
      "key": "29884359-fb70-478b-ba06-53d48b210aa0",
      "reviewed_at": null,
      "review_status": null,
      "created_at": "2020-03-09T12:05:31.877Z",
      "additional_attributes": {
        "identifier": "user@email.com",
        "country_code": "us",
        "identifier_type": "email"
      },
      "authentication_assessments": {
        "facematch": {
          "value": "0.9"
        },
        "id_authenticity": {
          "value": "0.9"
        },
        "liveness": {
          "value": "0.9"
        },
        "overall": {
          "value": "0.9"
        }
      },
      "authentication_document": "PASSPORT",
      "additional_document": null,
      "documents": [
        {
          "document_type": "PASSPORT",
          "document_information": [
            {
              "key": "FIRST_NAMES",
              "value": "John"
            },
            {
              "key": "LAST_NAME",
              "value": "Doe"
            },
            {
              "key": "DOCUMENT_NUMBER",
              "value": "12345"
            },
            {
              "key": "NATIONALITY",
              "value": "United States"
            },
            {
              "key": "DATE_OF_BIRTH",
              "value": "1960-12-12"
            }, ...
          ]
        }
      ],
      "end_user": {
        "customer_user_id": "user-12345"
      }
    },
    ...
  ],
  "number_of_authentications": 3,
  "status": "success",
  "code": "200"
}
get
Get Document by Authentication key
https://app.passbase.com /api/v1/id_documents/:authentication_key/:document_token
Retrieve the Documents submitted by the user for the Authentication authentication_key
Request
Response
Request
Path Parameters
authentication_key
required
string
The UUID of the Authentication you want to retrieve.
document_token
required
string
The Document  you want to retrieve. 
Possible values are front, back, selfie.
Headers
Authorization
required
string
Your secret API key found in the dashboard.
Must respect the "APIKEY api_key" format.
Content-Type
required
string
application/json
Response
200: OK
Binary content
server - Previous
Webhooks
Next - web - reauthentication
HTML + JS
Last updated 4 weeks ago
API

General

API Key Information

How to Send a Request

getGet Authentication by key

getList completed Authentications

getGet Document by Authentication key

get
Get Authentication by key

get
List completed Authentications

get
Get Document by Authentication key
