# Securitize iD

Securitize iD provides a simple and robust RESTful API to integrate KYC/KYB/AML within your application.

Securitize ID is a universal digital identity for the financial world. Knowing your customer is a crucial requirement for this sector, be it an individual or an entity. Securitize iD offers a fast and convenient way for investors to verify their identity, create accounts and log in to your website.

![](/files/-M1jdZa6xWFtf_JmLV1P)

With a Securitize iD API we provide partners and customers a mechanism with which they can 

* Provide single sign - on capabilities to 3 rd party services 
* Leverage KYC information with investor opt - in so they can use a verified identity 
* Expand the capabilities of the Securitize platform so that they can integrate their own offerings to the same investor base

### Examples

* An issuer may create their own investor experience not leveraging our fundraise platform, but using Securitize’s KYC process and leveraging the existing Securitize iD investor base. 
* An issuer can expand their offering with custom products and services, but investors only need register and KYC once. 
  * Eg. an issuer that wants to create a bulletin board for investors added to their offering and built by a third party but only available to an existing KYC’d investor base 
* A partner may want to leverage our existing investor base for on - boarding and compliance but not do a normal “offering” or use Securitize’s fundrase capabilities at all
  *  Eg. A third party ATS may onboard primary holders from Securitize into their trading venue with “just a click”

### What it does

* Allows to authenticate investors with their Securitize iD credentials in other sites/services
* Gets investor consent to share information with partner
* Provides KYC status and allows investor to complete KYC process with Securitize if needed
* Mechanisms for wallet registration for Security Token whitelisting (in progress)

### What it doesn’t do

* It does not provide a white-label KYC – the KYC process is managed by Securitize and with Securitize brand
  * **Legal implications** – to be able to share KYC cross issuers/partners there needs to be clear to investor they are giving the info to Securitize and that there are specific consents to share


# General information

Advantages for issuers and investors

## **Advantages for issuers**

### **Fast verification**

It takes an average of 26 days and 8 contacts to carry out the Know Your Customer process. An investor can be easily convinced not to participate in your offering or not to use your service due to this waiting time.  Securitize iD allows the users to do the verification process once in a process that can be carried out in minutes.

### **Real verified identity**

When a user decides to log in with Securitize iD they can share their identity details and verification status. Applications using real identity are usually less prone to be spam users and promote higher quality conversions.

### **Daily watchlist and AML checks**

Securitize iD checks everyday against multiple watchlists to ensure that investors are compliant. This reduces the risk posed by investors whose verification status has changed after entering a company's capitalisation table.

### **Account creation**

Logging in with Securitize iD allows investors to create quickly and easily an account in your website. Once the investor has created an account in one of the platforms connected with Securitize iD, he can log in easily with a few clicks in the rest of platforms. Entering the Securitize iD network implies the availability of a pool of potential investors that have already been verified.

### **Verification for individuals and entities**

Securitize ID supports verification of both individuals and businesses. Complying with all the requirements of Knowing Your Business (KYB) and Knowing Your Customer (KYC) begets many pain points for businesses who have to undertake long verification processes with many rote tasks. Using Securitize ID automates this process, saving time for investors. 

## **Advantages for investors**

### **Get verified once**

Investors only have to go through the verification process once. This streamlines the account creating and saves time.

### **No more passwords**

Investors do not have to remember multiple passwords across different platforms. 

### **Manage what you share**

The investor can manage easily who he shares his information with. His account remains consistent and he does not have to update it in different platforms since Securitize ID serves as his universal digital identity.


# Scope of Access

The degree of access to the information within Securitize iD may vary according to the agreement arrived to between Securitize iD and the third-party integrator

#### Authorisation to share information

When integrating Securitize iD within a third party product, the user has to give their consent to share their personal information. During the authentication flow, a dialog from Securitize will be shown to the user asking for authorisation to share their information with the third party integrator. This authorises Securitize iD to share the available information with you. The information that can be shared is layered and depends on the agreement arrived to between Securitize iD and the third party service always subject to the user's consent to share.

#### Access to verification states

Securitize iD provides information about the verification state of the user, be it an individual or an entity. In this case, no more information is provided. The possible states are the following.

| Verification state | Definition                                                                                                                                                                       |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `None`             | The user has not filled in the information necessary for his verification.                                                                                                       |
| `Processing`       | The user has filled in his information and sent it to be verified but the verification is still being carried out.                                                               |
| `Updates Required` | The verification could not be done because some of the information sent by the user was not correct or could not be analysed. We require the user upload a new set of documents. |
| `Manual Review`    | Due a tu a variety of factors the verification could not be done automatically so one of our compliance agents handles this verification personally.                             |
| `Verified`         | The user has been verified.                                                                                                                                                      |
| `Rejected`         | The user verification has been rejected.                                                                                                                                         |

By using these states, the third party integrator can decide upon the logic within their service. 

#### Access to verification details

If the third party service requires additional information and not just the verification state, for example, the users identification card, selfie or proof of address there is the possibility to share that data, but it depends on the legal agreement arrived to with Securitize iD and  consent form the user has to be provided.

#### Additional information

If after this you need additional information, you can then gather it as part of your own on-boarding flow (for instance filling out a suitability form), but with the investor already having covered most of it through Securitize iD, which should simplify their registration and make it much faster for existing holders of Securities (which will have a verified profile already as otherwise they cannot be holders). 


# User Interface & Landing page

Integrating the Securitize iD button in the UI

### Securitize iD buttons 

Dark and light mode buttons

![](/files/-MA0eGrMeWcvDn5EFY60)

### Sample landing Page

You can integrate the Securitize iD button within your UI. The image page shows the VBank landing page, with the button which links to  Securitize iD.

![](/files/-MA0eLrMQ48MkiOo4RyA)


# Accessing the APIs

In the following sections, we will provide a brief overview of how to access Securitize iD APIs. In any case, you can find all the available methods in [Securitize iD Swagger](https://sec-id-api.sandbox.securitize.io/swagger#/), which is the reference documentation.

We suggest that you read the following sections to get acquainted with the OAuth process, and how to interact with the platform.

##


# Authentication

The authentication process describe how to add a link to your website to Securitize D and how to retrieve the information provided after the login process and use it on Connect API

## Requisites

Before you can interact with Securitize iD APIs, request from Customer Success team the following information:

* **issuerID or DomainID**: this is the ID which identifies your unique Domain.
* **OAuthsecret:** this is the OAuth secret.
* **Base URL:** where to connect to Securitize iD (Sandbox or Production environments).

You will have to provide a **redirectURL** to a server where your logic is running. This URL has to be **whitelisted** by Securite. You can find more information of how to perform the process [here](/whitelisting/whitelisting-redirected-urls). 

In order to integrate Securitize iD as an authentication procedure, you will just have to add a Log in with Securitize iD button to your log in/registration page. That button will provide a link to initiate the OAuth process so the user can login and carry out the verification steps.

![Securitize iD Log in button](/files/-M8p1g-neVqd4-gSEOrg)

## The initial flow

![](/files/-MdpdasK6tQX3RjNE5BF)

## Initiating the OAuth process

To initiate the authentication process simply redirect the user to:

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

```http
https://id.securitize.io/#/authorize?issuerId=[CLIENT_ID]&scope=[SCOPE]&redirecturl=[REDIRECT_URL]
```

{% endtab %}
{% endtabs %}

| Parameter     | Description                                                                                              |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| CLIENT\_ID    | Your application client id provided by Securitize                                                        |
| SCOPE         | Scope of data access (we currently only support `info details verification)`                             |
| REDIRECT\_URL | The url to redirect after investor signs the data share agreement. MUST be list in `redirectUrls` array. |

### Example:

{% tabs %}
{% tab title="URL Call" %}

```
https://id.securitize.io/#/authorize?issuerId=123e4567-e89b&scope=info%20details%20verification&redirecturl=https://dashboard.securitize.io/authorization
```

{% endtab %}

{% tab title="HTML" %}

```markup
<body>
 <div id="SecuritizeID">
 </div>
</body>
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
function showSecuritizeIDLogInLogo() {
   var baseUrl     = "STRING";
   var issuerID    = "STRING";
   var scope       = "info details verification";
   var redirecturl = "URL"

   var securitizeID = document.getElementById("SecuritizeID");
   var link = document.createElement("a");
   var logo = document.createElement("img");

   var href = baseUrl + "#/authorize" + "?issuerId=" 
              + issuerID + "&scope=" + scope + "&redirecturl=" + redirecturl;
   logo.src = "./images/securitizeID.png";
   link.href = href;
   link.appendChild(logo);
   securitizeID.appendChild(link);
 }
```

{% endtab %}
{% endtabs %}

## Working with OAuth response

If the process was successful we will return the following data added to your redirect url

```http
https://REDICT_URL?code=40cba031-8fd2-4a88-89ff-36e07e5e060b&country=US&authorized=true
```

| Parameter  | Description                                                                                                                                                                               |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code       | Authorisation code used to get the user access token. (Code will expire after 5 minutes)                                                                                                  |
| country    | Securitize iD Investor country                                                                                                                                                            |
| authorized | Returns `true` if investor was authorized on with your Application in the past. NOTE: does not return if its the first time investor is going through OAuth process with your application |

### Example:

This JavaScript snippet captures the query string of the redirected URL:

```javascript
 function captureTOKEN() {
   const queryString = window.location.search;
   const urlParams   = new URLSearchParams(queryString);
   const code        = urlParams.get("code");
   const country     = urlParams.get("country");
   const authorized  = urlParams.get("authorized");
   console.log(code, country, authorized);
   if (authorized == "true") {
     // User has signed-up and has a SecuritizeID
   }
 }
```


# Access Token

How to get the Access Token after the login process and how to use it

## Obtaining Investor Access

The next step is to get the token for the issuer. Use the `v1/{domainID}/oauth2/authorize` endpoint, like:

**`curl -X POST "{baseUrl}" -H "accept: application/json" -H "Authorization: {secret}" -H "Content-Type: application/json" -d "{ \"code\": \"{code}\"}"`**<br>

| **P**arameter | Description                                       |
| ------------- | ------------------------------------------------- |
| {domainID}    | Your application client id provided by Securitize |
| authorization | Your application secret provided by Securitize    |
| code          | The Code you received in the previous set         |

## Investor Authorization

<mark style="color:green;">`POST`</mark> `https://sec-id-api.securitize.io/v1/{clientId}/oauth2/authorize`

Used to exchange provided code for accessToken

#### Path Parameters

| Name     | Type   | Description                                       |
| -------- | ------ | ------------------------------------------------- |
| clientId | string | Your application Client Id provided by Securitize |

#### Headers

| Name          | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| authorization | string | Your application secret provided by Securitize |

#### Request Body

| Name | Type   | Description                                             |
| ---- | ------ | ------------------------------------------------------- |
| code | string | Code provided from Authentication flow on users browser |

{% tabs %}
{% tab title="200 Returns JWT signed accessToken" %}

```
{
  "investorId": "string",
  "accessToken": "string",
  "refreshToken": "string",
  "expiration": "2020-05-23T18:52:03.415Z"
}
```

{% endtab %}

{% tab title="401 Could not find a cake matching this query." %}

```
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Failed to authorize",
  "details": null
}
```

{% endtab %}
{% endtabs %}

JavaScript Example:

```javascript
 function requestToken() {
   var issuerID = "STRING";
   const baseUrl = "https://sec-id-api.sandbox.securitize.io/v1/" 
                    + issuerID + "/oauth2/authorize";
   var scope = "info details verification";
   var redirecturl = "STRING";
   var OAuthSecret = "STRING";

   // Get the CODE in the URL
   const queryString = window.location.search;
   const urlParams = new URLSearchParams(queryString);
   const code = urlParams.get("code");

   var data = JSON.stringify({
     "code": code
   });

   var xhr = new XMLHttpRequest();
   xhr.withCredentials = true;

   xhr.addEventListener("readystatechange", function () {
     if (this.readyState === 4) {
       if (this.status === 200) {
         // User is logged-in and has authorized the app
         // Know we can get the TOKEN and start interacting
         var response = JSON.parse(this.responseText);
         console.log("Authorized with access Token: ", response.accessToken);
       }
       console.log(this.responseText);
     }
   });
   xhr.open("POST", baseUrl);
   xhr.setRequestHeader("Content-Type", "application/json");
   xhr.setRequestHeader("Authorization", OAuthSecret);
   xhr.send(data);
 }
```


# Refresh Access Token

How to refresh the Access Token

## Refresh Token

<mark style="color:green;">`POST`</mark> `https://sec-id-api.securitize.io/v1/{clientId}/oauth2/refresh`

Used to exchange provided refresh token for new accessToken.\
NOTE: Access token expires in 7days, refresh token is one time use and expires in 365 days.

#### Path Parameters

| Name     | Type   | Description                                       |
| -------- | ------ | ------------------------------------------------- |
| clientId | string | Your application Client Id provided by Securitize |

#### Headers

| Name          | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| authorization | string | Your application secret provided by Securitize |

#### Request Body

| Name         | Type   | Description                                             |
| ------------ | ------ | ------------------------------------------------------- |
| refreshToken | string | Code provided from Authentication flow on users browser |

{% tabs %}
{% tab title="200 Returns new access token and a new refresh token" %}

```
{
  "investorId": "string",
  "accessToken": "string",
  "refreshToken": "string",
  "expiration": "2020-05-23T18:52:03.415Z"
}
```

{% endtab %}

{% tab title="401 " %}

```
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Failed to authorize",
  "details": null
}
```

{% endtab %}
{% endtabs %}


# Application Configuration

How to get Post Issuer information.

## Get your current client configuration

## Get Client configurations

<mark style="color:blue;">`GET`</mark> `https://sec-id-api.securitize.io/v1/{clientId}`

Used to display current application configuration

#### Path Parameters

| Name     | Type   | Description                                       |
| -------- | ------ | ------------------------------------------------- |
| clientId | string | Your application Client Id provided by Securitize |

#### Headers

| Name          | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| authorization | string | Your application secret provided by Securitize |

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

```
{
  "status": 0,
  "data": {
    "appIcon": "string",
    "appName": "string",
    "redirectUrls": [
      "string"
    ]
  },
  "error": {},
  "success": true
}
```

{% endtab %}
{% endtabs %}

## Update your Application configurations

## Patch Client Configuration

<mark style="color:purple;">`PATCH`</mark> `https://sec-id-api.securitize.io/v1/{clientId}`

Allows update display name, icon or allowed redirect urls.\
Redirect urls will be used to authorize a redirection after a login process.\
If the URL used on the query string parameter is part of the redirectURL array, Securitize iD will redirect the user to that page.

#### Path Parameters

| Name     | Type   | Description                                       |
| -------- | ------ | ------------------------------------------------- |
| clientId | string | Your application Client Id provided by Securitize |

#### Headers

| Name          | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| Authorization | string | Your application secret provided by Securitize |

#### Request Body

| Name         | Type   | Description                                      |
| ------------ | ------ | ------------------------------------------------ |
| appIcon      | string | URL to image displayed on share information form |
| appName      | string | Name displayed on share information form         |
| redirectUrls | array  | Array of allowed redirect URLs                   |

{% tabs %}
{% tab title="200 Updated application configurations" %}

```
{
  "status": 0,
  "data": {
    "appIcon": "string",
    "issuerName": "string",
    "redirectUrls": [
      "string"
    ]
  },
  "error": {},
  "success": true
}
```

{% endtab %}
{% endtabs %}


# Investor Information

Please see the responses example for New as well as Individual and Entity Investor.

## Get Investor Information

<mark style="color:blue;">`GET`</mark> `https://sec-id-api.securitize.io/v1/{clientId}/investor`

Used to get investor information

#### Path Parameters

| Name     | Type   | Description                                       |
| -------- | ------ | ------------------------------------------------- |
| clientId | string | Your application Client Id provided by Securitize |

#### Headers

| Name          | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| access-token  | string | Investor accessToken                           |
| authorization | string | Your application secret provided by Securitize |

{% tabs %}
{% tab title="200 Returns investor information according to investor type ( null | individual | entity )" %}

```
{
  "status": 0,
  "data": {
    "investorId": "5defbf8130b4212eb55044b4",
    "email": "string",
    "fullName": "string",
    "verificationStatus": "Enum [ none, processing, updates-required, verified, manual-review, rejected, expired ]",
    "tfaEnabled": true,
    "language": "string",
    "createDate": "2017-07-21T17:32:28.000Z",
    "details": {
      "firstName": "string",
      "lastName": "string",
      "middleName": "string",
      "birthday": "string",
      "phone": {
        "code": "+380",
        "number": "8888888",
        "fullNumber": "+3808888888"
      },
      "investorType": "Enum [individual, entity]",
      "gender": "Enum [male, female]",
      "birthCountry": "string",
      "birthCity": "string",
      "birthState": "string",
      "mainIdentificationNumber": "string",
      "entityName": "string",
      "businesses": "string",
      "entityType": "string",
      "entityIdNumber": "string",
      "tax": [
        {
          "taxId": "string",
          "taxCountryCode": "string"
        }
      ],
      "address": {
        "street": "string",
        "houseNumber": "string",
        "entrance": "string",
        "city": "string",
        "countryCode": "string",
        "state": "string",   // only for US
        "zip": "string"
      }
    }
  },
  "error": {},
  "success": true
}
```

{% endtab %}
{% endtabs %}


# New Investor Example

How to get information from an investor

## Get Investor Information ( brand new investor )

<mark style="color:blue;">`GET`</mark> `https://sec-id-api.securitize.io/v1/{clientId}/investor`

Example for a brand new investor who just registered ( min available data )

#### Path Parameters

| Name     | Type   | Description                                       |
| -------- | ------ | ------------------------------------------------- |
| clientId | string | Your application Client Id provided by Securitize |

#### Headers

| Name          | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| access-token  | string | Investor accessToken                           |
| authorization | string | Your application secret provided by Securitize |

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

```
{
  "status": 200,
  "data": {
    "investorId": "strinf",
    "createDate": "2020-05-27T20:24:42.304Z",
    "fullName": "",
    "tfaEnabled": false,
    "language": "EN",
    "email": "string",
    "verificationStatus": "Enum [ none, processing, updates-required, verified, manual-review, rejected, expired ]",
    "details": {
      "tax": [],
      "address": {
        "countryCode": "IL"
      }
    }
  },
  "error": null,
  "success": true
}
```

{% endtab %}
{% endtabs %}


# Individual Investor Example

How to get information from an investor (full response)

## Get Investor Information ( Individual )

<mark style="color:blue;">`GET`</mark> `https://sec-id-api.securitize.io/v1/{clientId}/investor`

Example for individual investor data ( full individual investor information )

#### Path Parameters

| Name     | Type   | Description                                       |
| -------- | ------ | ------------------------------------------------- |
| clientId | string | Your application Client Id provided by Securitize |

#### Headers

| Name          | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| access-token  | string | Investor accessToken                           |
| authorization | string | Your application secret provided by Securitize |

{% tabs %}
{% tab title="200 Example of individual investor information" %}

```
{
  "status": 200,
  "data": {
    "investorId": "string",
    "createDate": "string",
    "fullName": "string",
    "tfaEnabled": "boolean",
    "language": "string",
    "email": "string",
    "verificationStatus": "Enum [ none, processing, updates-required, verified, manual-review, rejected, expired ]",
    "details": {
      "investorType": "Enum [individual, entity]",
      "firstName": "string",           
      "middleName": "string",
      "lastName": "string",
      "birthCountry": "string",
      "birthCity": "string",
      "mainIdentificationNumber": "string",
      "gender": "Enum [male, female]",
      "tax": [
        {
          "id": "string",
          "taxCountryCode": "string",
          "taxId": "string"
        },
        ...
      ],
      "phone": {
        "code": "string",
        "number": "string",
        "fullNumber": "string"
      },
      "address": {
        "countryCode": "string",
        "state": "string",   // only for US
        "city": "string",
        "entrance": "string",
        "houseNumber": "string",
        "street": "string",
        "zip": "string"
      },
      "birthday": "date"
    }
  },
  "error": null,
  "success": true
}
```

{% endtab %}
{% endtabs %}


# Entity Investor Example

How to get information from an entity investor (full response)

## Get Investor Information ( Entity )

<mark style="color:blue;">`GET`</mark> `https://sec-id-api.securitize.io/v1/{clientId}/investor`

Example for individual investor data ( full entity investor information )

#### Path Parameters

| Name     | Type   | Description                                       |
| -------- | ------ | ------------------------------------------------- |
| clientId | string | Your application Client Id provided by Securitize |

#### Headers

| Name          | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| access-token  | string | Investor accessToken                           |
| authorization | string | Your application secret provided by Securitize |

{% tabs %}
{% tab title="200 Example of entity investor information" %}

```
{
  "status": 200,
  "data": {
    "investorId": "string",
    "createDate": "2020-05-27T20:30:50.369Z",
    "fullName": "",
    "tfaEnabled": false,
    "language": "EN",
    "email": "string",
    "verificationStatus": "Enum [ none, processing, updates-required, verified, manual-review, rejected, expired ]",
    "details": {
      "investorType": "Enum [individual, entity]",
      "entityName": "string",
      "businesses": "string",
      "entityType": "string",
      "entityIdNumber": "string",
      "tax": [],
      "address": {
        "countryCode": "IL",
        "city": "string",
        "entrance": "string",
        "houseNumber": "string",
        "street": "string",
        "zip": "string"
      }
    }
  },
  "error": null,
  "success": true
}
```

{% endtab %}
{% endtabs %}


# Investor Documents

How to get documents from an investor

## Get Investor Document Information

## Investor Documents List

<mark style="color:blue;">`GET`</mark> `https://sec-id-api.securitize.io/v1/{clientId}/investor/documents`

#### Path Parameters

| Name     | Type   | Description                                       |
| -------- | ------ | ------------------------------------------------- |
| clientId | string | Your application Client Id provided by Securitize |

#### Headers

| Name          | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| access-token  | string | Investor accessToken                           |
| authorization | string | Your application secret provided by Securitize |

{% tabs %}
{% tab title="200 Returns list of investor documents" %}

```
{
  "status": 0,
  "error": {},
  "success": true,
  "data": [
    {
      "documentId": "string",
      "docType": "passport",
      "docCategory": "identification",
      "side": "front",
      "fileName": "30dec9b7-c2b8-4d3b-99ab-6bfde86a1a00.jpeg",
      "thumbnail": "string",
      "fileType": "image/jpeg",
      "verificationStatus": "pending",
      "createDate": "2020-05-27T18:08:53.501Z"
    },
    ...
  ]
}
```

{% endtab %}
{% endtabs %}

## Preview or Download document

## Get Document URL based on documentId

<mark style="color:blue;">`GET`</mark> `https://sec-id-api.securitize.io/v1/{clientId}/investor/documents/{documentId}/view`

Get temporary link to view or download document

#### Path Parameters

| Name       | Type   | Description                                       |
| ---------- | ------ | ------------------------------------------------- |
| clientId   | string | Your application Client Id provided by Securitize |
| documentId | string | Id of the selected document to view               |

#### Headers

| Name          | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| access-token  | string | Investor accessToken                           |
| authorization | string | Your application secret provided by Securitize |

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

```
{
  "status": 0,
  "error": {},
  "success": true,
  "data": {
    "url": "https://staging-testing-documents.s3.us-east-2.amazonaws.com/documents/5df248a0856b2b202eab3ebc/23fe3c65-50c9-4024-b254-784b0d529dae.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=b5970e428c24e3bb&X-Amz-SignedHeaders=host"
  }
}
```

{% endtab %}
{% endtabs %}


# Legal Signers

How to get Legal Signers Information

## Get Investor Legal Signers Information

<mark style="color:blue;">`GET`</mark> `https://sec-id-api.securitize.io/v1/{clientId}/investor/signers`

Used to get investor legal signers information ( returns list of legal signers )

#### Path Parameters

| Name     | Type   | Description                                       |
| -------- | ------ | ------------------------------------------------- |
| clientId | string | Your application Client Id provided by Securitize |

#### Headers

| Name          | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| access-token  | string | Investor accessToken                           |
| authorization | string | Your application secret provided by Securitize |

{% tabs %}
{% tab title="200 Returns list of legal signers with document information" %}

```
{
  "status": 200,
  "data": [
    {
      "signerId": "5ecece7244ba5b00184cbb87"
      "signerType": "individual - Enum [individual, entity]",
      "email": "string",
      "individualName": {
        "firstName": "string",
        "middleName": "string",
        "lastName": "string"
      },
      "address": {
        "street": "string",
        "houseNumber": "string",
        "entrance": "string",
        "city": "string",
        "countryCode": "US",
        "state": "CA",
        "zip": "string"
      },
      "birthDate": "1997-05-21",
      "documents": [
        {
          "documentId": "string",
          "docType": "string",
          "docCategory": "string",
          "side": ""Enum [front, back]",
          "fileName": "60848310-8067-4846-86b6-533fe3d93521.jpeg",
          "fileType": "image/jpeg",
          "verificationStatus": "Enum [pending, verified, not-verified, manual-review],
          "thumbnail": "string",
          "createDate": "2020-05-27T20:32:50.630Z"
        }
      ],
      "createDate": "2020-05-27T20:32:50.414Z"
    },
    {
      "signerId": "string",
      "signerType": "entity - Enum [individual, entity]",
      "legalName": "string",
      "businessName": "string",
      "entityType": "string",
      "taxId": "string",
      "birthDate": "2020-05-27",
      "documents": [
        {
          "documentId": "string",
          "docType": "other",
          "docCategory": "string",
          "side": ""Enum [front, back]",
          "fileName": "1070314e-7cdf-4aaf-b488-8173d71b91ef.jpeg",
          "fileType": "image/jpeg",
          "verificationStatus": "Enum [pending, verified, not-verified, manual-review],
          "thumbnail": "string",
          "createDate": "2020-05-27T20:33:19.226Z",
        }
      ],
      "createDate": "2020-05-27T20:33:19.015Z"
    }
  ],
  "error": null,
  "success": true
}
```

{% endtab %}
{% endtabs %}

## Preview or Download document

## Get Investor Legal Signers Information

<mark style="color:blue;">`GET`</mark> `https://sec-id-api.securitize.io/v1/{clientId}/investor/signers/{signerId}/documents/{documentId}/view`

Used to get temporary link to view or download the file.

#### Path Parameters

| Name       | Type   | Description                                       |
| ---------- | ------ | ------------------------------------------------- |
| documentId | string | Id of the selected document to view               |
| clientId   | string | Your application Client Id provided by Securitize |

#### Headers

| Name          | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| access-token  | string | Investor accessToken                           |
| authorization | string | Your application secret provided by Securitize |

{% tabs %}
{% tab title="200 Returns temporary view url" %}

```
{
  "status": 0,
  "error": {},
  "success": true,
  "data": {
    "url": "https://staging-testing-documents.s3.us-east-2.amazonaws.com/documents/5df248a0856b2b202eab3ebc/23fe3c65-50c9-4024-b254-784b0d529dae.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=b5970e428c24e3bb&X-Amz-SignedHeaders=host",
  }
}
```

{% endtab %}
{% endtabs %}


# Verification Details

How to get investor verification details

## Get investor verification details

## Investor verification

<mark style="color:blue;">`GET`</mark> `https://sec-id-api.securitize.io/v1/{clientId}/investor/verification`

Used to get latest verification status with errors if they exist

#### Path Parameters

| Name     | Type   | Description                                       |
| -------- | ------ | ------------------------------------------------- |
| clientId | string | Your application Client Id provided by Securitize |

#### Headers

| Name          | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| access-token  | string | Investor accessToken                           |
| authorization | string | Your application secret provided by Securitize |

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

```
{
  "status": 0,
  "data": {
    "investorId": "string",
    "status": "none",
    "createDate": "2020-05-27T18:13:51.193Z",
    "updateDate": "2020-05-27T18:13:51.193Z",
    "operatorFullName": "string",
    "isManual": true,
    "errors": [
      "string"
    ]
  },
  "error": {},
  "success": true
}
```

{% endtab %}

{% tab title="404 If investor never ran verification this call will return 404" %}

```
{
  "status": 0,
  "data": {},
  "error": {},
  "success": true
}
```

{% endtab %}
{% endtabs %}

Get investor Verification Details


# Wallets

These are the endpoints on the OAuth API that allow at domain level for the access token:

* See the wallets registered per token to the investor and their status (ready, pending, failed)
* Add wallets to the investor (equivalent to adding them via the CP)

### **Important concepts and parameters**

* **address** - the address of the wallet to add. The format for this value will depend on the specific blockchain the token is using (i.e. Ethereum tokens will require Ethereum addresses, Algorand wallets will require Algorand addresses, etc...)
* **wallet name** - the user-friendly name for this wallet, so that the user can identify it without having to check the address itself when looking at it from the Securitize dashboard
* **tokenId** - the token for which this wallet wants to be authorized. This operation basically is set to add a wallet address to the whitelist of an specific token, and since in a given domain there may be multiple tokens this is needed to specify which one
* **securitizeiDwalletID** - this is used to associate the wallet being whitelisted at token level with the same wallet iff it was registered to the user profile in Securitize iD. This is not required, as the whitelisting at token level does NOT require the wallet being registered at Securitize iD (the UI enforces this process for simplifity, but the system does not require it) and in some cases it would not be possible (e.g. for networks that are not exposed in Securitize iD, like BESU). If the link exists it fundamentally means the wallet was authorized through our UI by leveraging a previously SiD-registered wallet, but for an automatic operation via API this is likely not needed.

## Get Wallets

<mark style="color:blue;">`GET`</mark> `https://sec-id-api.securitize.io/v1/{clientId}/investor/domain/wallets`

This endpoint allows you to get the wallets of a specific investor<br>

#### Path Parameters

| Name     | Type   | Description                          |
| -------- | ------ | ------------------------------------ |
| clientId | string | Your ClientID provided by Securitize |

#### Headers

| Name          | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| access-token  | string | Investor Access Token                          |
| authorization | string | Your application secret provided by Securitize |

{% tabs %}
{% tab title="200 Wallet successfully retrieved." %}

```
{    "name": "[
   {
      "securitizeIdWalletId":"60d1d2cdffa486001dc19c31",
      "walletType":"other",
      "walletName":"Algorand 1",
      "walletAddress":"254zubmgyf3up6z7d6w56vekkdpgezzj6bzw3ruhlqbulwh3azqxrs4hp4",
      "blockchain":"algorand",
      "tokens":[
         {
            "tokenName":"SOPA",
            "tokenId":"65be0954-a803-48f0-ad2e-8c7c1ccdbd10",
            "status":"not-authorised"
         }
      ]
   }
] Could not find a cake matching this query.
```

{% endtab %}
{% endtabs %}

## Add Investor Wallet&#x20;

<mark style="color:green;">`POST`</mark> `https://sec-id-api.securitize.io/v1/{clientId}/investor/domain/wallets`

This endpoint allows you to add an Investor Wallet&#x20;

#### Path Parameters

| Name       | Type   | Description |
| ---------- | ------ | ----------- |
| {clientId} | string |             |

#### Headers

| Name          | Type   | Description |
| ------------- | ------ | ----------- |
| access-token  | string |             |
| authorization | string |             |

#### Request Body

| Name                 | Type   | Description |
| -------------------- | ------ | ----------- |
| tokenId              | string |             |
| walletName           | string |             |
| address              | string |             |
| securitizeIdWalletId | string |             |

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

```
```

{% endtab %}
{% endtabs %}


# Whitelisting redirected URLs

In order for redirection to work, it's necessary to whitelist the URL to be redirected.

To do that, you have to add your URL into this PATCH:

| **curl -X PATCH "<https://sec-id-api.securitize.io/v1/{domainID}>" -H "accept: application/json" -H "Authorization: {secret}" -H "Content-Type: application/json" -d "{body}"**&#x50; |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| Parameter     | Description                                       |
| ------------- | ------------------------------------------------- |
| {domainID}    | Your application client id provided by Securitize |
| Authorization | Your application secret provided by Securitize    |
| body          | looks like below                                  |

```javascript
{
"appIcon": "Icon url",
"appName": "The Name of your App or [yourdomain]",
"redirectUrls": [
"https://[yourdomain]/*"
}
```

### Example

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

```
curl -X PATCH "https://sec-id-api.securitize.io/v1/{domainID}" -H "accept: application/json" -H "Authorization: {secret}" -H "Content-Type: application/json" -d "{body}"
```

where the body looks like below:

```
{
"appIcon": "Icon url",
"appName": "The Name of your App or [yourdomain]",
"redirectUrls": [
"https://[yourdomain]/*"
}
```

{% endtab %}

{% tab title="Python" %}
Python snippet to Whitelist a specific domain ***\[yourdomain]***

```python
serviceUrl = 'https://sec-id-api.sandbox.securitize.io/v1/'
ClientID   ="STRING"
Secret     ="STRING"

body = {'appIcon':'TheIcon',
       'appName':'TheAppName',
       'redirectUrls':['yourdomain']}

response = requests.patch(
   serviceUrl + ClientID ,
   headers={'Authorization': Secret},
   data= body
)

print(response.headers)

if (response.status_code == 200):
 print("Correctly updated")
else:
 print('Error: ', response.content)
```

{% endtab %}
{% endtabs %}