API docs by Redocly

UpPass API (1.2.1)

Download OpenAPI specification:Download

UpPass

Introduction

UpPass API provides access to call various verification APIs from your system. The APIs are REST based and accept both GET and POST apis with parameters mentioned below. There are two types of APIs in this document, Authentication and Verification. You will need to request access such as app_id, app_secret_keys, api_token from the UpPass team in order to test UpPass APIs

Definitions

Below are the list of terms which are most used across UpPass APIs.

Term Description
workspace A group of forms managed by users
form UI Verification Form generated from UpPass Portal
form_slug A (programically) flow name created by the client
lang Language of the form UI
slug Unique identification of form web address requesting for the end user
step The step of the filling form
section The sub-step of the form
answers Collections of question_key and response of input by end users via UpPass Form
extras Returns in some of the API response, which contains verification data (e.g. Liveness, ID documents,etc)

Example URL

  • Dashboard Page
    https://app.uppass.io/{lang}/dashboard/flows/{slug}/overall?workspace={workspace}

  • Form Entry Page
    https://app.uppass.io/{lang}/{form}

  • In Progress Form
    https://app.uppass.io/{lang}/form/{form}/{slug}/{step}/{section}

Supported Browsers

Platform Browser Version
Android Google Chrome 107+
Android Samsung Internet Browser 6.2+
Android Firefox 106+
iOS Safari 12+
iOS WKWebView 14.3+

Note: Above browsers are for mobile web view only as users will not be able to verify on web browsers. If user attempts to verify on web browsers, they will be prompted to switch to mobile.

Get Started

After you have signed up, you will be taken to the dashboard, where you can see the workflows and overview of the total verification submissions by the users.

Below screen is what will you see for the first time

Flow - Empty State

Workspace is a container where all the flows are stored. You can only have one workspace per account. However, you can view and edit another workspace based on the invitation only.

First, you need to create a new flow. A flow contains multiple steps of verification. You can use the Flow name in the API to generate unique verification link to the end users.

Use Case

Scenario

  • User visits client's application for verification
    • Partner calls UpPass API to create a new verification form
    • Partner's app redirect to UpPass Form generated by API
  • User completes verification
  • UpPass Form redirects to Partner's app
  • Partner receive webhook from UpPass App

api

Implementation

  • Registered account at UpPass.io

  • Create a new Workspace at UpPass.io

  • Create Form under the same Workspace

  • Create a API Token for API authentication request

  • Configure Webhook Submission event

  • Call Create Form API with api_token and form_slug

    • In Success response, form_url will be returned
    • Redirct end user to the form_url

  • Receive verification result via Webhook Submission after end user complete form submission

Error Codes

UpPass APIs return standard http response codes for success and failure of API requests. There are two types of errors:

HTTP Error

Error Type Description
400: BAD REQUEST ParseError Malformed request
401: UNAUTHORIZED AuthenticationFailed Incorrect authentication credentials
403: FORBIDDEN PermissionDenied Do not have permission to perform the action
400: BAD REQUEST ParseError Malformed request
401: UNAUTHORIZED AuthenticationFailed Incorrect authentication credentials
401: UNAUTHORIZED NotAuthenticated Authentication credentials were not provided.
403: FORBIDDEN PermissionDenied Do not have permission to perform the action
404: NOT FOUND NotFound Not found
404: NOT FOUND Http404 Not found
405: METHOD NOT ALLOWED MethodNotAllowed Method "{method}" not allowed.
406: NOT ACCEPTABLE NotAcceptable Could not satisfy the request Accept header
415: UNSUPPORTED MEDIA TYPE UnsupportedMediaType Unsupported media type {media_type} in request.
422: VALIDATIONERROR ValidationError Invalid input. Return with errors detail in json.
Example: { "input": ["Input is invalid."] }
429: TOO MANY REQUESTS Throttled Request was throttled
431: REQUEST HEADER FIELDS TOO LARGE RequestHeaderFieldsTooLarge One or more header fields exceeds the maximum size.
500: INTERNAL SERVER ERROR APIException A server error occurred.
500: INTERNAL SERVER ERROR Exception A server error occurred.

Transaction Error

Error Type Description
461: INSUFFICIENT CREDIT InsufficientCredit Insufficient Credit
462: STORE SCAN CODE EXPIRED StoreScanCodeExpired Code expired.
463: STORE SCAN CODE INVALID StoreScanCodeInvalid Invalid payment code
464: TERM LOAN EXPIRED TermLoanExpired Term loan expired
465: TERM LOAN EXPIRED ReturnAmountExceedCreditUsage Return amount exceed credit usage

Create Form API

Passing parameters when calling Create Form API

Upon calling Create Form API, you can pass parameters to UpPass. When the verification is completed, UpPass will return the data via webhook.

Parameters

1. eKYC

If your form has KYC verification step, you can pass inside answers parameters on which documents UpPass should check for verification.

{
  "answers": {}
}

By default, UpPass will ask National ID for KYC verification. If you want to verify using Passport, you can pass answers as below :

{
  "answers": {"ekyc_document_type": "passport"}
}

2. Input Parameters

You can also pass input parameters (predefined answers) when create the form.

Go to the form > builder > Input Parameter to set input parameters.

Input Parameter Setting

Example

{
  "answers" : {
    "customer_id": "uuid_1"
  }
}

Create Form API Specification

Authorizations:
Authorization
path Parameters
lang
required
string

A language of the output form for the end user {en|th}

form_slug
required
string

A flow you want to create a new applied_form for

header Parameters
Authorization
required
string
Example: Bearer {api_token}

A {api_token} generated from UpPass dashboard

Request Body schema: application/json
answers
object

Responses

Request samples

Content type
application/json
{
  • "answers": { }
}

Response samples

Content type
application/json
{
  • "info": "{UPPASS_HOSTNAME}/{lang}/api/forms/{form_slug}/applied-forms/{slug}/info/",
  • "detail": {
    },
  • "form_url": "{UPPASS_HOSTNAME}/en/form/{form_slug}/{slug}/?"
}

Webhook Submission

Webhook Configuration

You can configure one or more webhooks from the UpPass Portal.

After user has finished verification, system will call webhook to pass results data to your system.

Setting up Webhook

  • First, go to UpPass Portal
  • Go to, Connect Tab and Add Webhook

Connect Tab

  • Configure your webhook here (For Authorization, please choose Bearer)

WebHook Detail

Callbacks

Callback payload samples

Callback
POST: CLIENT_WEBHOOK_SUBMISSION_RECEIVER_URL
Content type
application/json
{
  • "event": {
    },
  • "extra": {
    },
  • "answers": {
    },
  • "application": {
    }
}

Resend Webhook

Use this API when you want to resend webhook to the end server

API Specification

Authorizations:
Authorization
path Parameters
lang
required
string

A language of the output form for the end user {en|th}

form_slug
required
string

A flow you want to create a new applied_form for

slug
required
string

A slug of an applied_form you want to resend the webhook

header Parameters
Authorization
required
string
Example: Bearer {api_token}

A {api_token} generated from UpPass dashboard

Responses

Webhook Events

submit_form

  • When the end user has submitted the verification

update_status

  • When admin has changed the status of eKYC via UpPass Portal

drop_off

  • When the verification form is expired
  • Requires configuration to trigger please contact the support team for inquery

ekyc_front_card_reached_max_attempts

  • When the verification of ID scan has reached maximum attempt
  • Requires configuration to trigger please contact the support team for inquery

ekyc_liveness_reached_max_attempts

  • When the verification of facial liveness has reached maximum attempts
  • Requires configuration to trigger please contact the support team for inquery

Callbacks

Callback payload samples

Callback
POST: CLIENT_WEBHOOK_EVENTS_RECEIVER_URL
Content type
application/json
{
  • "event": {
    },
  • "application": {
    }
}