/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.

Authorization / Authentication

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

Apps using Access Token Authorization

Use a valid access token in a Authorization: Bearer request header.

See Authenticating with an Access Token for more details.

Apps using ECDSA Authentication

Both authsignature and usersignature headers are required for this request. See the section on ECDSA Authentication for more detail about ECDSA signature generation.

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
sandbox.silamoney.com
Content-Type: application/json
// if using OAuth2
Authorization: Bearer [GENERATED JWT TOKEN HERE]
// if using ECDSA
authsignature: [GENERATED AUTHSIGNATURE HEX STRING HERE]
usersignature: [GENERATED USERSIGNATURE HEX STRING HERE]

{
  "header": {
    "created": 1234567890, 
    "app_handle": "handle.silamoney.eth", 
    "user_handle":"user.silamoney.eth", 
    "version": "0.2", 
    "reference": "<your unique id>"
  }, 
  "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 NameData Type / SubtypeOptionalDescription
start_datestring / ISO‑8601 dateyesOnly return documents created on or after this date.
end_datestring /
ISO‑8601 date
yesOnly return documents created before or on this date.
doc_typeslist of stringsyessee Supported Document Types. Use the short form ("name"), not the long form ("label").
searchstringyesOnly return documents whose name or filename contains the search value. Partial matches allowed, no wildcards.
sort_bystringyesOne 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: