# Endpoints

## Clients

Extend and build your own custom platform using Orba One's available endpoints. We currently offer a Node.js REST API client, available on [npm](https://www.npmjs.com/package/@orbaone/api).

{% hint style="info" %}
All API endpoints require the field `AuthKey` is present in the request header of each request. `AuthKey` is a combination of your `ApiKey and Secret` separated by a ':' and encoded in using base64 encoding.
{% endhint %}

Creating your `AuthKey` key header is simple and intuitive, simple and easy. 

1. Get your ApiKey and Secret from within your [dashboard](https://dashboard.orbaone.com/home/integration).
2. Concatenate both values separated by a colon `:`
3. Encode the resulting concatenation in base64.
4. Append the `AuthKey` field in your header request and send the encoded value.

{% hint style="info" %}
You can access your `ApiKey` and `Secret` from within your [dashboard](https://dashboard.orbaone.com).
{% endhint %}

## Create Applicant

<mark style="color:green;">`POST`</mark> `https://api.orbaone.com/api/v1/applicants/create`

This endpoint allows you to create an Applicant.

#### Request Body

| Name       | Type   | Description                    |
| ---------- | ------ | ------------------------------ |
| email      | string | Applicant's email, if provided |
| middleName | string | Middle name of the Applicant   |
| lastName   | string | Last name of the Applicant     |
| firstName  | string | First name of the Applicant    |

{% tabs %}
{% tab title="200 Applicant successfully created." %}

```javascript
{
  "isSuccessful": true,
  "data": {
    "id": "08d8cd40-11da-423c-8d56-e3a5f9f2b6e0",
    "email": null,
    "firstName": "John",
    "middleName": "",
    "lastName": "Brown",
    "thumbnailPath": "",
    "completed": false,
    "completedAt": "0001-01-01T00:00:00",
    "createdAt": "2021-02-09T21:17:13.4036674Z",
    "selfieDataId": null,
    "selfieTurnDirection": "right",
    "selfieData": null,
    "idDocumentDataId": null,
    "idDocumentData": null,
    "updatedAt": "2021-02-09T21:17:13.4037257Z",
    "vendorId": "08d8b75c-b964-4da8-8e05-205022297e35",
    "adminApprovalStatus": "pending",
    "adminApprovalDate": "0001-01-01T00:00:00",
    "vendorApprovalStatus": "pending",
    "vendorApprovalDate": "0001-01-01T00:00:00",
    "approvedByUser": null,
    "approvalScore": 0,
    "faceMatchScore": 0,
    "ipAddress": null,
    "deviceInfo": null
  },
  "errors": []
}
```

{% endtab %}
{% endtabs %}

## Get Applicants

<mark style="color:blue;">`GET`</mark> `https://api.orbaone.com/api/v1/applicants`

Get all the applicants

#### Query Parameters

| Name     | Type   | Description                                     |
| -------- | ------ | ----------------------------------------------- |
| search   | string | The search string to find a specific Applicant. |
| pageSize | number | Amount of applicants per page (default: 50)     |
| page     | number | Current page of applicants (default: 1)         |

{% tabs %}
{% tab title="200 " %}

```
{
  pageIndex: 1,
  totalPages: 0,
  totalItems: 0,
  items: [
    {
      adminApproval: "",
      adminApprovalDate: "",
      approvalScore: 0,
      completed: false,
      completedAt: "",
      createdAt: "",
      faceMatchScore: 0,
      idDocumentData: {
        authenticationScore: 0,
        backImageUrl: "",
        frontImageUrl: "",
        dateOfBirth: "",
        documentNumber: "",
        documentType: "",
        expirationDate: "",
        firstName: "",
        lastName: "",
        fullName: "",
        id: "",
        issueDate: "",
        issuingCountry: "",
        nationality: "",
        sex: "",
      },
      selfieCode: 0,
      selfieTurnDirection: "",
      selfieData: {
        id: "",
        nearImageUrl: "",
        thumbnailUrl: "",
        videoUrl: "",
      },
      email: "",
      firstName: "",
      middleName: "",
      lastName: "",
      thumbnailUrl: "",
      status: "",
      vendorApproval: "",
      vendorApprovalDate: "",
    },
  ],
  hasPreviousPage: false,
  hasNextPage: false,
}
```

{% endtab %}
{% endtabs %}

## Get an Applicant

<mark style="color:blue;">`GET`</mark> `https://api.orbaone.com/api/v1/applicants/<applicantId>`

This endpoint takes a unique `applicantId` and return the corresponding details.

#### Path Parameters

| Name        | Type   | Description                    |
| ----------- | ------ | ------------------------------ |
| applicantId | string | The unique ID of an Applicant. |

{% tabs %}
{% tab title="200 " %}

```
{
  adminApproval: "",
  adminApprovalDate: "",
  approvalScore: 0,
  completed: false,
  completedAt: "",
  createdAt: "",
  faceMatchScore: 0,
  idDocumentData: {
    authenticationScore: 0,
    backImageUrl: "",
    frontImageUrl: "",
    dateOfBirth: "",
    documentNumber: "",
    documentType: "",
    expirationDate: "",
    firstName: "",
    lastName: "",
    fullName: "",
    id: "",
    issueDate: "",
    issuingCountry: "",
    nationality: "",
    sex: ""
  },
  selfieCode: 0,
  selfieTurnDirection: "",
  selfieData: {
    id: "",
    nearImageUrl: "",
    thumbnailUrl: "",
    videoUrl: ""
  },
  email: "",
  firstName: "",
  middleName: "",
  lastName: "",
  thumbnailUrl: "",
  status: "",
  vendorApproval: "",
  vendorApprovalDate: ""
}
```

{% endtab %}
{% endtabs %}

## Reset an Applicant

<mark style="color:green;">`POST`</mark> `https://api.orbaone.com/api/v1/applicants/<applicantId>/reset`

This endpoint resets an applicant's state, commonly used for reauthentication.

#### Path Parameters

| Name        | Type   | Description                   |
| ----------- | ------ | ----------------------------- |
| applicantId | string | The unique ID of an Applicant |

{% tabs %}
{% tab title="200 " %}

```
{
    "isSuccessful": true,
    "data": {
        "id": "08d8d148-6ba3-490c-8615-fd65723f0aw2",
        "email": null,
        "firstName": "John",
        "middleName": "",
        "lastName": "Brown",
        "thumbnailPath": "",
        "completed": false,
        "completedAt": "0001-01-01T00:00:00",
        "createdAt": "2021-02-15T00:27:04.667389",
        "selfieDataId": "08d8d148-788f-46fa-8a6b-27480f1eb331",
        "selfieTurnDirection": "right",
        "selfieData": {
            "selfieType": 0,
            "thumbnailUrl": "",
            "videoUrl": "",
            "nearImageUrl": "",
            "farImageUrl": "",
            "createdAt": "2021-02-15T00:27:26.34442",
            "updatedAt": "2021-02-16T15:08:12.8089274Z"
        },
        "idDocumentDataId": null,
        "idDocumentData": null,
        "updatedAt": "2021-02-16T15:08:12.8067632Z",
        "vendorId": "08d8b75c-b964-4da8-8e05-205022297e35",
        "adminApprovalStatus": "pending",
        "adminApprovalDate": "0001-01-01T00:00:00",
        "vendorApprovalStatus": "pending",
        "vendorApprovalDate": "0001-01-01T00:00:00",
        "approvedByUser": null,
        "approvalScore": 0,
        "faceMatchScore": 0,
        "ipAddress": "1.2.3.4",
        "deviceInfo": ""
    },
    "errors": []
}
```

{% endtab %}
{% endtabs %}

## Create Applicant Verification Link

<mark style="color:blue;">`GET`</mark> `https://api.orbaone.com/api/v1/applicants/<applicantId>/verification_link`

Create a verification link for a given applicant

#### Path Parameters

| Name        | Type   | Description                   |
| ----------- | ------ | ----------------------------- |
| applicantId | string | The unique ID of an Applicant |

#### Query Parameters

| Name       | Type    | Description                                           |
| ---------- | ------- | ----------------------------------------------------- |
| regenerate | boolean | Boolean to determine if the link should be regenrated |

{% tabs %}
{% tab title="200 " %}

```
{
    "isSuccessful": true,
    "data": {
        "applicantId": "01d8cw84-1e24-4f02-837c-08626fd0c92f",
        "email": null,
        "url": "https://verify.orbaone.com/?magic=f0eb0f5e1a774a3096b8f36c0db85b846bcdd8a9f0cf4131bb20f48792abc0dc77c11b17024e42428511a00a73b8fa8a&publicKey=2af861789aa84aa68fd6bba19f7b589c&applicantId=08d8cd84-1e24-4f02-837c-08126fd0c92f"
    },
    "errors": []
}
```

{% endtab %}
{% endtabs %}

## Applicant PEP Scan

<mark style="color:blue;">`GET`</mark> `https://api.orbaone.com/api/v1/applicants/<applicantId>/pep`

This endpoint facilitates a Politically Exposed Person (PEP) scan on an Applicant.

#### Path Parameters

| Name        | Type   | Description                   |
| ----------- | ------ | ----------------------------- |
| applicantId | string | The unique ID of an Applicant |

{% tabs %}
{% tab title="200 This response shows a possible match for a Politically Exposed Person" %}

```
{
    "date": "2020-09-28T15:42:32.2620868+10:00",
    "scan_id": "s6227134",
    "number_of_matches": 1,
    "number_of_pep_matches": 1,
    "number_of_sip_matches": 0,
    "persons": [
        {
            "category": "PEP",
            "name": "Peter Bunting",
            "gender": "male",
            "reference_type": "PEP",
            "nationality": "",
            "citizenship": "",
            "places": [
                {
                    "country": "Jamaica",
                    "type": "Legislature"
                }
            ],
            "roles": [
                {
                    "title": "Member of House of Representatives (People's National Party)",
                    "since": "2012-01-17",
                    "to": "2016-02-25",
                    "type": ""
                },
                {
                    "title": "Member of House of Representatives (People's National Party)",
                    "since": "2016-03-10",
                    "type": ""
                }
            ],
            "identities": [
                {
                    "number": "peter_bunting",
                    "type": "EveryPolitician Legacy"
                }
            ],
            "images": [
                "http://jamaica-elections.com/general/2016/info/candidates_images/peter_bunting_pnp.jpg"
            ],
            "match_rate": 100.0
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Applicant Sanction Scan

<mark style="color:blue;">`GET`</mark> `https://api.orbaone.com/api/v1/applicants/<applicantId>/sanction`

This endpoint facilitates a Sanction scan on an Applicant.

#### Path Parameters

| Name        | Type   | Description                    |
| ----------- | ------ | ------------------------------ |
| applicantId | string | The unique ID of an Applicant. |

{% tabs %}
{% tab title="200 This response shows a possible match for a Sanction scan." %}

```

{
    "date": "2020-09-28T15:41:28.7270459+10:00",
    "scan_id": "s6227132",
    "number_of_matches": 2,
    "number_of_pep_matches": 0,
    "number_of_sip_matches": 2,
    "persons": [
        {
            "update_at": "2017-01-24T19:12:01+00:00",
            "category": "SIP",
            "name": "ROBERT WILLIAM FISHER",
            "gender": "Male",
            "dates_of_birth": [
                {
                    "date": "April 13, 1961"
                }
            ],
            "places_of_birth": [
                {
                    "text": "Brooklyn, New York"
                }
            ],
            "reference_type": "Sanction",
            "references": [
                {
                    "name": "US - Federal Bureau of Investigation (FBI) List",
                    "id_in_list": "da4fa184bbed15a4dc7524d0988d53c1"
                }
            ],
            "nationality": "American",
            "citizenship": "",
            "other_names": [
                {
                    "name": "Robert W. Fisher",
                    "type": ""
                }
            ],
            "images": [
                "https://www.fbi.gov/wanted/topten/robert-william-fisher/@@images/image/thumb",
                "https://www.fbi.gov/wanted/topten/robert-william-fisher/fisher2bw.jpg/@@images/image/thumb",
                "https://www.fbi.gov/wanted/topten/robert-william-fisher/longhairwithbeard.jpg/@@images/image/thumb",
                "https://www.fbi.gov/wanted/topten/robert-william-fisher/shorthairnobeard.jpg/@@images/image/thumb",
                "https://www.fbi.gov/wanted/topten/robert-william-fisher/longhairwithgoatee.jpg/@@images/image/thumb",
                "https://www.fbi.gov/wanted/topten/robert-william-fisher/baldlongbeard.jpg/@@images/image/thumb",
                "https://www.fbi.gov/wanted/topten/robert-william-fisher/shorthairandgoatee.jpg/@@images/image/thumb",
                "https://www.fbi.gov/wanted/topten/robert-william-fisher/longhairnobeard.jpg/@@images/image/thumb",
                "https://www.fbi.gov/wanted/topten/robert-william-fisher/shorthairandbeard.jpg/@@images/image/thumb",
                "https://www.fbi.gov/wanted/topten/robert-william-fisher/baldnobeard.jpg/@@images/image/thumb",
                "https://www.fbi.gov/wanted/topten/robert-william-fisher/fisher5bw.jpg/@@images/image/thumb"
            ],
            "sources": [
                "https://www.fbi.gov/wanted/topten/robert-william-fisher/download.pdf"
            ],
            "summary": "Eyes: blue;\nHair: brown;\nBuild: Medium;\nRace: white;\nWeight: 190 Pounds;\nHeight: 72 Inches;\nDescription: Unlawful Flight to Avoid Prosecution - First Degree Murder (3 Counts), Arson of an Occupied Structure;\nWarning: SHOULD BE CONSIDERED ARMED AND EXTREMELY DANGEROUS;\nReward: The FBI is offering a reward of up to $100,000 for information leading directly to the arrest of Robert William Fisher.;\nField Offices: phoenix;\nOccupations: Surgical Catheter Technician, Respiratory Therapist, Fireman;\nPossible Countries: USA;\nScars and Marks: Fisher has surgical scars on his lower back.;\n[Remarks]: Fisher is physically fit and is an avid outdoorsman, hunter, and fisherman. He has a noticeable gold crown on his upper left first bicuspid tooth. He may walk with an exaggerated erect posture and his chest pushed out due to a lower back injury. Fisher is known to chew tobacco heavily. He has ties to New Mexico and Florida. Fisher is believed to be in possession of several weapons, including a high-powered rifle.;\n[Caution]: Robert William Fisher is wanted for allegedly killing his wife and two young children and then blowing up the house in which they all lived in Scottsdale, Arizona, in April of 2001.",
            "match_rate": 100.0
        },
        {
            "category": "SIP",
            "name": "FISHER, ROBERT WILLIAM",
            "first_name": "ROBERT WILLIAM",
            "last_name": "FISHER",
            "gender": "Male",
            "dates_of_birth": [
                {
                    "date": "1961/04/13"
                }
            ],
            "places_of_birth": [
                {
                    "text": "Tucson, Arizona, United States"
                }
            ],
            "reference_type": "Sanction",
            "references": [
                {
                    "name": "Interpol Wanted List",
                    "id_in_list": "2002/3398"
                }
            ],
            "nationality": "United States",
            "citizenship": "",
            "images": [
                "https://ws-public.interpol.int/notices/v1/red/2002-3398/images/60039342",
                "https://ws-public.interpol.int/notices/v1/red/2002-3398/images/60039344",
                "https://ws-public.interpol.int/notices/v1/red/2002-3398/images/60039346",
                "https://ws-public.interpol.int/notices/v1/red/2002-3398/images/60039348",
                "https://ws-public.interpol.int/notices/v1/red/2002-3398/images/60039358",
                "https://ws-public.interpol.int/notices/v1/red/2002-3398/images/60039360",
                "https://ws-public.interpol.int/notices/v1/red/2002-3398/images/60039376",
                "https://ws-public.interpol.int/notices/v1/red/2002-3398/images/60039378",
                "https://ws-public.interpol.int/notices/v1/red/2002-3398/images/60039380",
                "https://ws-public.interpol.int/notices/v1/red/2002-3398/images/60039382",
                "https://ws-public.interpol.int/notices/v1/red/2002-3398/images/60039384"
            ],
            "sources": [
                "https://ws-public.interpol.int/notices/v1/red/2002-3398"
            ],
            "summary": "Reason: Wanted By United States;\nHeight: 1.83 metres;\nWeight: 86 kilograms;\nColour of eyes: Blue;\nColour of hair: Brown;\nLanguage Spoken: English;\nCharges: First degree murder (3 counts);  arson of an occupied structure;\nDistinguishing marks and characteristics: Surgical scar on lower back;  gold crown on upper left first bicuspid",
            "match_rate": 83.0
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Create OCR Scan for document

<mark style="color:green;">`POST`</mark> `https://api.orbaone.com/api/v1/scans/ocr`

This endpoint facilitates an Optical Character Recognition (OCR) scan for a document.

#### Request Body

| Name                                                 | Type   | Description                                                 |
| ---------------------------------------------------- | ------ | ----------------------------------------------------------- |
| referenceId                                          | String | A ID or name used to retrieve a scanned document            |
| documentType<mark style="color:red;">\*</mark>       | String | The type of document being scanned                          |
| documentSide                                         | String | The side of the document being scanned                      |
| issuingCountryCode<mark style="color:red;">\*</mark> | String | The country code for the country the document was issued in |
| documentImage<mark style="color:red;">\*</mark>      | Image  | An image of the document to be scanned                      |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Get OCR Scanned documents

<mark style="color:blue;">`GET`</mark> `https://api.orbaone.com/api/v1/scans/ocr`

The endpoint gets all the OCR scanned documents.

#### Query Parameters

| Name        | Type   | Description                                            |
| ----------- | ------ | ------------------------------------------------------ |
| referenceId | String | An ID or name used to retrieve scanned document        |
| dateFrom    | Date   | Returns scanned documents starting from this date      |
| dateTo      | Date   | Returns scanned documents up to this date              |
| pageNumber  | Number | The current page of the scanned documents (default: 1) |
| pageSize    | Number | The number of scanned documents per page               |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Get an OCR Scanned document

<mark style="color:blue;">`GET`</mark> `https://api.orbaone.com/api/v1/scans/ocr/<id>`

This endpoint takes a unique `id` and returns the corresponding data.

#### Path Parameters

| Name                                 | Type | Description                          |
| ------------------------------------ | ---- | ------------------------------------ |
| id<mark style="color:red;">\*</mark> | UUID | The unique id for a scanned document |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Create face comparison

<mark style="color:green;">`POST`</mark> `https://api.orbaone.com/api/v1/scans/facematch`

This endpoint facilitates a face comparison for a document

#### Request Body

| Name                                                 | Type   | Description                                                 |
| ---------------------------------------------------- | ------ | ----------------------------------------------------------- |
| referenceId                                          | String | An ID or name used to retrieve face comparison              |
| documentType<mark style="color:red;">\*</mark>       | String | The type of document being scanned                          |
| documentSide                                         | String | The side of the document being scanned                      |
| issuingCountryCode<mark style="color:red;">\*</mark> | String | The country code for the country the document was issued in |
| documentImage<mark style="color:red;">\*</mark>      | Image  | An image of the document                                    |
| selfieImage<mark style="color:red;">\*</mark>        | Image  | An image of the owner of the document                       |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Get face comparisons

<mark style="color:blue;">`GET`</mark> `https://api.orbaone.com/api/v1/scans/facematch`

This endpoints gets all the face comparisons

#### Query Parameters

| Name        | Type   | Description                                           |
| ----------- | ------ | ----------------------------------------------------- |
| referenceId | String | An ID or name used to retrieve face comparison        |
| dateFrom    | Date   | Returns face comparisons starting from this date      |
| dateTo      | Date   | Returns face comparisons up to this date              |
| pageNumber  | Number | The current page of the face comparisons (default: 1) |
| pageSize    | Number | The number of the face comparisons per page           |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Get a face comparison

<mark style="color:blue;">`GET`</mark> `https://api.orbaone.com/api/v1/scans/facematch/<id>`

This endpoint takes a unique `id` and returns the corresponding data.

#### Path Parameters

| Name | Type | Description                         |
| ---- | ---- | ----------------------------------- |
| id   | UUID | The unique ID for a face comparison |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}