Documents API

This API allows managing documents in the system. It provides endpoints to create, read, update, and delete documents, as well as to handle their attachments.

The Document Object

The Document object represents a document in the system.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "borrowerId": "789e4567-e89b-12d3-a456-426614174001",
  "key": "identification",
  "label": "Identification Document",
  "value": "123456789",
  "tags": ["personal", "verified"],
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-01T00:00:00Z",
  "hasAttachments": true
}

Attributes

Attribute	Description	Type
id	Unique identifier of the document	String
borrowerId	ID of the borrower associated with the document	String
key	Key identifying the type of document	String
label	Descriptive label of the document	String
value	Value associated with the document	Any
tags	Tags associated with the document	Array of String
createdAt	Document creation date and time	String (ISO 8601)
updatedAt	Last update date and time	String (ISO 8601)
hasAttachments	Indicates if the document has attachments	Boolean

Available Operations

Create a New Document

Creates a new document in the system.

POST /v1/documents

Input Parameters

Parameter	Description	Type	Required
borrowerId	ID of the borrower associated with the document	String	Yes
key	Key identifying the type of document	String	Yes
value	Value associated with the document	Any	No
tags	Tags associated with the document	Array of String	No

Request Example

{
  "borrowerId": "789e4567-e89b-12d3-a456-426614174001",
  "key": "identification",
  "value": "123456789",
  "tags": ["personal", "verified"]
}

Successful Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Update a Document

Updates an existing document.

PATCH /v1/documents/:document_id

Path Parameters

Parameter	Description
:document_id	ID of the document to update

Input Parameters

Parameter	Description	Type	Required
key	New document key	String	No
value	New value associated with the document	Any	No
tags	New tags associated with the document	Array of String	No

Request Example

{
  "value": "987654321",
  "tags": ["personal", "verified", "updated"]
}

Successful Response

Returns the updated Document object.

Retrieve a Document

Retrieves the information of a specific document.

GET /v1/documents/:document_id

Path Parameters

Parameter	Description
:document_id	ID of the document to retrieve

Successful Response

Returns the complete Document object.

Delete a Document

Deletes a document from the system.

DELETE /v1/documents/:document_id

Path Parameters

Parameter	Description
:document_id	ID of the document to delete

Successful Response

Status code 204 (No Content) if the deletion was successful.

List Documents

Retrieves a paginated list of documents with filtering and sorting options.

GET /v1/documents

Query Parameters

Parameter	Description	Type
borrower-id	Filter by borrower ID	String
search	Text to search in documents	String
page	Page number (default: 1)	Integer
per-page	Items per page (default: 10)	Integer
key	Filter by document key	String
sort-by	Field to sort by	String
sort-direction	Sorting direction (asc or desc)	String

Successful Response

Paginated list of Document objects.

Add an Attachment to a Document

Adds a new attachment to an existing document.

POST /v1/documents/:document_id/attachments

Path Parameters

Parameter	Description
:document_id	ID of the document to add attachment to

Input Parameters

Parameter	Description	Type	Required
url	URL of the attached file	String	Yes
label	Descriptive label of the attachment	String	No
fileExtension	File extension	String	No
metadata	Metadata associated with the attachment	Object	No

Request Example

{
  "url": "https://example.com/file.pdf",
  "label": "Identity Document",
  "fileExtension": "pdf",
  "metadata": {
    "size": 1024,
    "pageCount": 2
  }
}

Successful Response

Status code 201 (Created) if the attachment was successfully added.

Upload an Attachment to a Document

Uploads a file as an attachment to an existing document.

POST /v1/documents/:document_id/attachments/upload

Path Parameters

Parameter	Description
:document_id	ID of the document to upload attachment to

Form Parameters

Parameter	Description	Type	Required
file	File to upload	File	Yes
label	Descriptive label of the attachment	String	No
metadata	Metadata in JSON format	String	No

Successful Response

Status code 201 (Created) if the file was successfully uploaded.

Retrieve Attachments of a Document

Retrieves the list of attachments associated with a document.

GET /v1/documents/:document_id/attachments

Path Parameters

Parameter	Description
:document_id	ID of the document to retrieve attachments from

Successful Response

List of Attachment objects associated with the document.

Delete an Attachment from a Document

Deletes a specific attachment from a document.

DELETE /v1/documents/:document_id/attachments/:attachment_id

Path Parameters

Parameter	Description
:document_id	ID of the document
:attachment_id	ID of the attachment to delete

Successful Response

Status code 204 (No Content) if the attachment was successfully deleted.

Error Handling

The API may return the following error codes:

Code	Description
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

Errors will include a descriptive message in the response body.

On this page