Integration guide for developers

Starting with PlusID is easy. You can follow this Integration Guide to start using PlusID services easily in your application or other online service.

Getting started

This document provides a developer integration guide for integrating PlusID services via public REST API. Please note that that API may be updated from time-to-time, but we aim to keep semantic versioning rules in place for the API.

This guide is for PlusID Service Provider API v1.x

If you have any questions, please contact us for technical support at:

We provide support for technical integrations and questions during the normal business hours and working days. Please note that dedicated integration and business support work may require a separate support agreement.

Principles

The PlusID API follows REST principles. It has predictable resource-oriented URLs, accepts form-encoded request bodies and it returns JSON-encoded responses.

The communication follows standard HTTP response codes and verbs.

The authentication is based on your  own unique API key, which is Service Provider specific and confidential.

Always ensure that your implementation does not over-use, overload and anyway otherwise harm the system and platform.

The development should be done against our staging (test) server, which does not affect the live data or interact with the external services and/or networks. The API key you use to authenticate the request is environment specific.

We will only accept encrypted connections (https) both for the incoming requests and for the outgoing webhooks.

Once your development is ready, you may want to inform us to get feedback and confirmation about the usage. However, you are always free to start using the API once your Service Provider has been created, reviewed and ID verified.

Base URL for development is:

Base URL for production is:

Authentication

The PlusID API uses API keys to authenticate requests. You can view and manage your API keys in the PlusID Service Provider Dashboard under Settings / API key. API key may also be provided to you by your PlusID technical representative.

Your API keys define the permissions/privileges for your account, so be sure to keep them secure! Do not share your secret API keys in any publicly accessible areas such as GitHub, client-side code, and so forth.

In case of breach or accidental exposure of the API key, please contact us immediately to revoke access for your API key, or login to your dashboard to reset/regenerate it!

To authenticate your requests, you need to include the ApiKey into the X-API-Key header, i:e X-API-Key: YOUR_API_KEY

All API requests must be made over HTTPS. Calls made over plain HTTP will fail, always. API requests without authentication will also fail.

Errors

For error reporting, we use standard HTTP response codes to indicate the success or failure of an API request. In general:

  • Codes in the 2xx range indicate success.
  • Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was missing, payment failed, permission not granted, no access to the data, etc.).
  • Codes in the 5xx range indicate an error with PlusID’s application and/or servers (please inform us about these).

 

Some 4xx errors may include error code and message to help to determine the issue which allows handling of the error programmatically (e.g. permission to this data is not granted).

Usually for 5xx errors, you can use retries in server-to-server calls with increasing timeouts between retries as they may be caused by network glitch or temporary issue in the server side.

Please note that we will be throttling the number of API request per time. Do not overload or overuse the system!

HTTP Status Code Summary

Pagination

Some of the API resources that provide “list” type of access to data (such as list of transactions), support pagination and have following parameters:

  • page
  • limit

Data types

During the user authentication and in specific user data requests, certain data types can be requested as part of the call which is then delivered after the user’s explicit acceptance of the data.

Please note that for each data request and for each new data type, the user needs to provide explicit acceptance to share the data with the Service Provider.

Please note that not all data may be available from the user. In such a case, the data object returned will contain status: “not_available”.

Please note that you can request data both from personal User and from Service Provider.

Possible data types are (provided in dataTypes field as part of the data request):

				
					{
  "age": "Returns exact age in years at this specific moment, e.g. 43",
  "ageGroup": "Returns age group. Options: minor (0-12), teen (13-17), age18_24, age25_34, age35_49, age50_65, over65",
  "bankAccountBic": "Returns bank account BIC/SWIFT code",
  "bankAccountIban": "Returns bank account IBAN number",
  "bankAccountInfo": "Returns bank account information",
  "bankAccountOwnerName": "Returns bank account owner full name",
  "city": "Returns user’s address city",
  "companyId": "Returns service provider's company ID",
  "companyName": "Returns service provider's company name",
  "companyType": "Returns service provider's company type",
  "country": "Returns user’s address country",
  "dob": "Returns date of birth in ISO 8601 syntax (YYYY-MM-DD)",
  "driverLicense": "Returns driver license information, e.g. ABC",
  "driverLicenseAuthorizedBy": "Returns driver license authorized by information",
  "driverLicenseCountry": "Returns driver license country information (country name, e.g. Finland)",
  "driverLicenseExpiresAt": "Returns driver license expiration date in ISO 8601 syntax (YYYY-MM-DD)",
  "email": "Returns email address",
  "facebookUrl": "Returns Facebook social media page URL",
  "firstNames": "Return all official first names",
  "fullAddress": "Returns full address information",
  "fullName": "Return full official name: first names + last names",
  "isDriverLicense": "Returns true if person has valid driver license",
  "isRetired": "Returns true if person has retired (is pensionist)",
  "isStudent": "Returns true if person currently stufying (is student)",
  "isVerified": "Returns true if person ID has been verified",
  "lastNames": "Return all official last names",
  "linkedinId": "Returns LinkedIn social media account ID",
  "mobilePhone": "Returns mobile phone number",
  "passportAuthorizedBy": "Returns passport authorized by information",
  "passportCountry": "Returns passport person country information (country name, e.g. Finland)",
  "passportExpiresAt": "Returns passport expiration date in ISO 8601 syntax (YYYY-MM-DD)",
  "passportNumber": "Returns passport number or ID",
  "passportValidFrom": "Returns passport valid from date in ISO 8601 syntax (YYYY-MM-DD)",
  "personId": "Returns person identification number or social security number (SSN)",
  "pin": "Same as *personId*", // alias
  "postalCode": "Returns user’s address postal code (or zip code)",
  "preferredFirstName": "Return preferred first name (or 1st if not selected)",
  "preferredLastName": "Return preferred last name (or 1st if not selected)",
  "profileImageUrl": "Returns user’s profile image public URL. This image is provided by the user. No content moderation!",
  "profileImage": "Returns user’s profile image raw data as base64 encoded string. This image is provided by the user. No content moderation!",
  "sex": "Returns person sex if provided by the user",
  "ssn": "Same as *personId*", // alias
  "stateOrRegion": "Returns user’s address state or region",
  "streetAddress": "Returns user’s address street address 1 and 2",
  "studentNumber": "Returns person student number",
  "studentSchoolName": "Returns person student school name",
  "supportEmail": "Returns service provider's support email address",
  "supportPhone": "Returns service provider's support phone number",
  "trustScore": "Returns PlusID Trust score in range of 0..100 (the higher the better). Application can set a threshold for user 'trustness' to decide if user is trustworthy or not.",
  "trustStatus": "Returns PlusID Trust status",
  "twitterId": "Returns Twitter social media account ID",
  "vatId": "Returns service provider's company VAT ID",
  "walletAddressBitcoin": "Returns user Bitcoin wallet address",
  "walletAddressEthereum": "Returns user Ethereum ERC20 wallet address",
  "website": "Returns website address",
  "whatsappNumber": "Returns Whatsapp phone number",
}

				
			

Example of data request of a Trusted User

Choosing which data types to request from the user can be difficult due to so many options. We strongly recommend to request only the need-to-know data that is essential to the application’s functionality. If the data is nice-to-have, do not request it. This will ensure that user is also more willing to share the data with you.

If for any reason, such data is requested, it is possible to define which data is mandatory and which data is optional. Please note, that we may require some additional information about your justification for data requests, in case you plan to request sensitive user data.

Below you can find an example of typical and recommended data types to receive necessary information for a Trusted User – a user whose ID has been verified and therefore is strongly authenticated and can fulfill simple KYC requirements and avoids you from any fraudulent users to register into your application.

				
					{
  "mandatoryData": [
    "firstNames",
    "lastNames",
    "idVerified"
  ],
  "optionalData": [
    "dob"
  ],
  "message": "max 160 char message for the user",
  "urlPrivacyPolicy": "link to your privacy policy URL"
}
				
			

And this data request would be responding as follows:

				
					{
  "dataId": "f5dbe6c1-xxxx-xxxx-a41b-969baef0ba3f",
  "dataUrl": "https://staging-dashboard.plusid.app/dataform/auth/f5dbe6c1-xxxx-xxxx-a41b-969baef0ba3f",
  "plusId": "ISHIDDEN",
  "mandatoryData": {
    "firstNames": {
      "data": "John James",
      "status": "verified",
      "source": "id_verification"
    },
    "lastNames": {
      "data": "Smith",
      "status": "verified",
      "source": "id_verification"
    },
    "idVerified": {
      "data": "true",
      "status": "verified",
      "source": "id_verification"
    }
  },
  "optionalData": {
    "idVerified": {
      "data": "19820704",
      "status": "verified",
      "source": "id_verification"
    }
  },
  "createdAt": "2022-02-23T12:05:00.540Z",
  "status": "authorized",
  "statusMessage": "OK",
  "authorizedAt": "2022-02-23T12:26:30.577Z"
}

				
			

Authorizations

Authorizations from the user can be requested as part of the Data request, included as own dataTypes. These authorizations are useful to request some typical consent from the user at the same time as with other data, such as user explicit consent to receive marketing communication from the company.

Please note that status of the authorization is always “not_applicable” as this data is not verified, but instead always coming from the user input.

Please note that the support for custom authorizations is under development and not yet available.

Possible data types for authorizations are:

				
					{
  "authorizeDebtCollectionDigital": "Authorization to send payment reminders and debt collection correspondence via digital/electronic channels",
  "authorizeMarketingCommunication": "Authorization to send marketing communication and sales messages to the user",
}

				
			

API Reference

A more detailed Open API v3 (Swagger) specification is available and can be accessed using the button below. You can use this page also to test the API once you have the API key available.

SDK

If you are using NodeJS to do the integration with PlusID API, it is possible to use the following library to even further boost the integration with your solution.

Please note that if you need support to any other platforms, please let us know and we can help you or provide you more information.

Recommended libraries for integration:

Node API library (github.com/readmeio/api), which will automatically generate a SDK from our OpenAPI definition.

				
					const sdk = require('api')(API_SPECIFICATION_URI);
sdk.auth(apiKey); // authenticate (not chainable anymore with latest versions)

// Send data request
const body = { plusId, mandatoryData, optionalData, message, privacyPolicyUrl };
const { dataId } = await sdk.auth(apiKey).postData(body);

// Get data request
const { status } = await sdk.getData(dataId);

				
			

If you are in need for another SDK on another environments, please let us know!