Skip to content

User documents

Definition

See the Glossary for a definition.

Context

In order for clients to be able to share documents with their customers, the Integration API offers several operations related to "user documents".

Base flow:

  • The client creates a document for a specific user via the Integration API
    • InvestSuite only stores a limited set of metadata for each document, including a blob_uri reference to the actual content binary that is to be stored in an object storage of the client.
  • These documents will then be accessible to the end customers in the mobile app
  • To be able to show the document contents from the mobile app, the client needs to implement a rest endpoint on top of their object storage. See Client endpoint needed to show document contents for a definition.

Create user document

Info

Also see the Documents section within the "Integration OpenAPI" specification.

  • This endpoint is to be used to insert the metadata of a new document in the InvestSuite system
  • The end customers will see, in the mobile application, all such documents that were assigned to their user_id (and portfolio_id)
  • Some additional field info (see the Documents section within the "Integration OpenAPI" specification for a complete list of fields to pass when creating a user document):
Field Description Data type Example Required
blob_uri The relative uri that points to the document binary. The endpoint of the client middleware (see below) has to be able to use it to uniquely determine the matching document content. string /storage/ref/to/doc/content Yes (within blob_uris)
blob_uris An object that contains a map from each document content type to its related blob_uri. As each document can have multiple content types (e.g. both a PDF and a WEB version), this map can contain multiple, but should at least contain 1 content type. json object { "PDF": "/storage/ref/to/doc/content" } Yes
external_id A unique external identifier for this document, also referred to as "Reference ID". This identifier can be any string used in your system to identify this document. string unique_external_doc_id No
types The type(s) of document. Only a pre-set list of possible values are allowed (listed in the Documents section within the "Integration OpenAPI" specification). Can contain multiple, but should at least contain 1 type. string array ["COST_OVERVIEWS", "OTHER"] Yes

Other available operations

Info

Also see the Documents section within the "Integration OpenAPI" specification.

  • List documents
    • to get a paginated, optionally filtered, list of documents
    • this endpoint does not support the query param as documented in Querying business objects
  • Retrieve single document
    • to get a single document based on the document id.
  • Patch document
    • to patch a subset of fields of a single document

Client endpoint needed to show document contents

As InvestSuite itself does not store the document binaries, the following flow was designed in order for end users to be able to see - in a secure way - the document contents from within the mobile application.

Sequence diagram:

FrontendFrontendDocument ApiDocument ApiMetadata tableMetadata tableClient middlewareClient middlewareBinary storageBinary storageAccess token in Authorization bearer headergetDocumentUrl(id, access_token)Get blob_uri for idblob_uriDoc API authenticates to client middleware with access tokenURL path can be defined by clientAccess token in Authorization bearer headerGET /<url-path-to-get-document-url> (blob_uri, access token)DocumentUrlResponse (url, isSignedUrl)Document URL + indication if url is signed or notAdds access token in Authorization bearer header if not a signed urlGET <Document URL>Document binary

The endpoint has to:

  • be available/accessible from the InvestSuite services
  • accept a blob_uri as query parameter. InvestSuite will pass the blob_uri value that matches the requested content type and which was stored during the document create (or patch)
  • verify the incoming JWT access token (passed via the Authorization header) to make sure that the user has access to the requested blob_uri
  • return a JSON containing
    • a url (string) that will allow the end customer to, from the front-end application, access the content of the document that matches the incoming blob_uri
    • a isSignedUrl (boolean) indication if the above url is a (short-lived) signed url or not. If not, the front-end application will pass an authorization header when accessing the url 
GET https://<full-path-to-be-defined-by-client>?blob_uri={BLOB_URI} HTTP/1.1
Content-Type: application/json
Authorization: Bearer {string}

{
    "url": "https://...",
    "isSignedUrl": true
}