/list_documents

List previously uploaded supporting documentation for KYC

During the KYC onboarding process, it may be necessary to upload supporting documentation. This endpoint will support the listing of previously uploaded documentation.

Requests

The request body at this endpoint is the header_msg JSON object.

header.user_handle should have the registered handle to be verified.

Both authsignature and usersignature headers are required for this request.

Pagination

This endpoint supports pagination via URL query parameters:

/list_documents?page=1&per_page=20&order=asc
  • page: page number to retrieve. default: 1
  • per_page: number of items per page. default: 20, max: 100
  • order: sort returned items (usually by creation date). Allowed values: asc (default), desc
POST /0.2/list_documents HTTP/1.1
Host: sandbox.silamoney.com
authsignature: [GENERATED AUTHSIGNATURE HEX STRING HERE]
usersignature: [GENERATED USERSIGNATURE HEX STRING HERE]
Content-Type: application/json

{
  "header": {
    "created": 1234567890, 
    "app_handle": "handle.silamoney.eth", 
    "user_handle":"user.silamoney.eth", 
    "version": "0.2", 
    "crypto": "ETH", 
    "reference": "ref"
  }, 
  "message": "header_msg",
  "start_date": "2020-07-31",
  "end_date": "2020-08-07",
  "doc_types": [
    "id_drivers_license",
    "id_passport"
  ],
  "search": "my_CA_drivers_license",
  "sort_by": "name"
}
  
***

HTTP/1.1 200 OK

{
  "success": true,
  "status": "SUCCESS",
  "reference": "<your unique id>",
  "response_time_ms": "171",
  "documents": [
    {
      "user_handle": "user.silamoney.eth",
      "document_id": "279687a0-30c6-463d-85bc-eee9bf395e21",
      "name": "passport_2017",
      "filename": "img_201901022_034923",
      "hash": "075f0956584cfa8d32beb384fcf51ce3ee30a7e5aeee6434acc222928a30db3e",
      "type": "id_passport",
      "size": "12345678",
      "created": "2020-08-03T17:09:24.917939"
    }
  ],
  "pagination": {
    "returned_count": 2,
    "total_count": 2,
    "current_page": 1,
    "total_pages": 1
  }
}
const filters = {   
  page: 1,  
  perPage: 1,   
  order: 'asc', 
  startDate: '2020-10-30'), 
  endDate: '2020-10-30',    
  docTypes: ['doc_green_card'], 
  search: 'logo',   
  sortBy: 'name',   
};  
const res = await sila.listDocuments(userHandle, userPrivateKey, filters);  

// Success Response Object  
console.log(res.statusCode); // 200 
console.log(res.data.success); // true  
console.log(res.data.status); // SUCCESS    
console.log(res.data.documents); // An array of documents   
console.log(res.data.pagination); // Pagination information (returned_count, total_count, current_page, total_pages)
payload = {
    "user_handle": user_handle,
    "start_date": "2020-01-01", # Optional
    "end_date": "2020-12-31", # Optional
    "doc_types": ["id_drivers_license"], # Optional
    "search": "my CA driver", # Optional
    "sort_by": "name" # Optional
}
page = 1 # Optional
per_page = 20 # Optional
order = "asc" # Optional. Only asc or desc are allowed

response = silasdk.Documents.listDocuments(app, payload, user_private_key, page, per_page, order)

# Success Response Object
{
    "status_code": 200,
    "success": true,
    "status": "SUCCESS",
    "documents": [
        {
            "user_handle": "user.silamoney.eth",
            "document_id": "279687a0-30c6-463d-85bc-eee9bf395e21",
            "name": "passport_2017",
            "filename": "img_201901022_034923",
            "hash": "075f0956584cfa8d32beb384fcf51ce3ee30a7e5aeee6434acc222928a30db3e",
            "type": "id_passport",
            "size": "12345678",
            "created": "2020-08-03T17:09:24.917939"
        },
        ...
    ],
    "pagination": {
        "returned_count": 2,
        "total_count": 2,
        "current_page": 1,
        "total_pages": 1
    }
}
List<String> docTypes = new ArrayList<String>();
docTypes.add("doc_green_card");
// With no pagination
ListDocumentsMessage message = ListDocumentsMessage.builder()
        .userHandle("user_handle")
        .userPrivateKey("user_private_key")
        .order("asc") // Optional. Sort returned items (usually by creation date). Allowed values: asc (default), desc
        .search("logo") // Optional. Only return documents whose name or filename contains the search value. Partial matches allowed, no wildcards.
        .sortBy("name") // Optional. One of: name or date
        .docTypes(docTypes) // Optional. A list of strings of supported document types
        .startDate(LocalDate.now()) // Optional. Only return documents created on or after this date.
        .endDate(LocalDate.now()) // Optional. Only return documents created before or on this date.
        .build();
ApiResponse response = api.listDocuments(message);
// With pagination
PaginationMessage pagination = PaginationMessage.builder()
    .page(1) // Optional. Page number to retrieve. default: 1
    .perPage(40) // Optional. Number of items per page. default: 20, max: 100
    .build();
ApiResponse response = api.listDocuments(message, pagination);

// Success Response
System.out.println(response.getStatusCode()); // 200
ListDocumentsResponse parsedResponse = (ListDocumentsResponse) response.getData();
System.out.println(parsedResponse.getSuccess()); // true
System.out.println(parsedResponse.getStatus()); // SUCCESS
System.out.println(parsedResponse.getPagination().getCurrentPage()); // 1
System.out.println(parsedResponse.getPagination().getReturnedCount()); // 1
System.out.println(parsedResponse.getPagination().getTotalCount()); // 1
System.out.println(parsedResponse.getPagination().getTotalPages()); // 1
System.out.println(parsedResponse.getDocuments().get(0).getUserHandle()); // user_handle
System.out.println(parsedResponse.getDocuments().get(0).getDocumentId()); // some-uuid-code
System.out.println(parsedResponse.getDocuments().get(0).getName()); // logo
System.out.println(parsedResponse.getDocuments().get(0).getFilename()); // logo
System.out.println(parsedResponse.getDocuments().get(0).getHash()); // yourfilehash
System.out.println(parsedResponse.getDocuments().get(0).getType()); // doc_green_card
System.out.println(parsedResponse.getDocuments().get(0).getSize()); // 211341
System.out.println(parsedResponse.getDocuments().get(0).getCreated()); // 2020-08-03T17:09:24.917939
$userHandle = 'user.silamoney.eth';
$privateKey = 'some private key';
$page = '1'; // Optional. Page number to retrieve. Default: 1
$perPage = '10'; // Optional. Number of items per page. Default: 20, Max: 100
$sort = 'desc'; // Optional. Sort returned items. Allowed values: asc (default), desc
$startDate = new DateTime::createFromFormat('m/d/Y', '1/8/2020'); // Optional. Only return documents created on or after this date.
$endDate = new DateTime::createFromFormat('m/d/Y', '1/8/2020'); // Optional. Only return documents created before or on this date.
$docTypes = ['doc_type', 'doc_type_2']; // Optional. You can get this values from getDocumentTypes()
$search = 'some_file_name'; // Optional. Only return documents whose name or filename contains the search value. Partial matches allowed, no wildcards.
$sortBy = 'name'; // Optional. One of: name or date
$response = $client->listDocuments($userHandle, $privateKey, $page, $perPage, $sort, $startDate, $endDate, $docTypes, $search, $sortBy);


// Response 200
echo $response->getStatusCode(); // 200
echo $response->getData()->success; // TRUE
echo $response->getData()->status; // SUCCESS
echo $response->getData()->documents; // An array of documents
echo $response->getData()->documents[0]->user_handle; // The user handle that owns the document
echo $response->getData()->documents[0]->document_id; // The document id
echo $response->getData()->documents[0]->name; // The name of the document
echo $response->getData()->documents[0]->filename; // The file name of the document
echo $response->getData()->documents[0]->hash; // The hash of the file contents
echo $response->getData()->documents[0]->type; // The document type
echo $response->getData()->documents[0]->size; // The file size
echo $response->getData()->documents[0]->created; // The datetime of creation
echo $response->getData()->pagination->returned_count; // The amount of documents returned in this request
echo $response->getData()->pagination->total_count; // The total amount of documents that meet the filters
echo $response->getData()->pagination->current_page; // The current page of documents
echo $response->getData()->pagination->total_pages; // The total amount of pages that meet the filters
// userHandle is required
// privateKey is required
// All other parameters are optional
List<string> docTypes = new List<string> { "" };
var response = api.ListDocuments(userHandle, privateKey, DateTime.Today, DateTime.Today.AddDays(1), docTypes, search, sortBy, page, perPage, order);

// Success Object Response
Console.WriteLine(response.StatusCode); // 200
var parsedResponse = (ListDocumentsResponse)response.Data;
Console.WriteLine(parsedResponse.Success);
Console.WriteLine(parsedResponse.Status); // SUCCESS
Console.WriteLine(parsedResponse.Documents); // A list of documents
Console.WriteLine(parsedResponse.Documents[0].DocumentId);
Console.WriteLine(parsedResponse.Documents[0].UserHandle);
Console.WriteLine(parsedResponse.Documents[0].Name);
Console.WriteLine(parsedResponse.Documents[0].Filename);
Console.WriteLine(parsedResponse.Documents[0].Hash);
Console.WriteLine(parsedResponse.Documents[0].Type);
Console.WriteLine(parsedResponse.Documents[0].Size);
Console.WriteLine(parsedResponse.Documents[0].Created);
Console.WriteLine(parsedResponse.Pagination); // Pagination information (CurrentPage, ReturnedCount, TotalPages, TotalCount)

Request Document Metadata

Key Name

Data Type / Subtype

Optional

Description

start_date

string / ISO‑8601 date

yes

Only return documents created on or after this date.

end_date

string /
ISO‑8601 date

yes

Only return documents created before or on this date.

doc_types

list of strings

yes

see Supported Document Types. Use the short form ("name"), not the long form ("label").

search

string

yes

Only return documents whose name or filename contains the search value. Partial matches allowed, no wildcards.

sort_by

string

yes

One of: name or date

Responses

Status CodesuccessDescription
200trueNo errors encountered, but possible that no documents were found
400falseOne or more invalid document types specified

Response Document Metadata

Key NameData Type / SubtypeDescription
user_handlestringuser unique handle
document_idstring / uuid4document unique identifier
namestringdocument descriptive name
filenamestringdocument filename at upload, no extension
hashstring / SHA-256document SHA-256 signature, calculated after upload
typestringdocument type short-form name
createdstring / ISO‑8601 timestampdocument upload timestamp

See Also:


Did this page help you?