SecureExchange creation via API

Overview

There are two ways a SecureExchange can be created :

By using the Admin Portal, a Client Advisor can create a SecureExchange for a client.
By calling our API endpoints, a provider can create and manage SecureExchanges for their clients. This is explained in detail in the following chapter.

Know more:

For detailed integration guidance, refer to our API documentation and sample codes.

SecureExchange Creation

In order to create a SecureExchange via API, a provider needs to supply the following details:

Property	Cardinality	Description
Username	mandatory	The user name of the client account. Must be unique and it is recommended to use a UUID.
External user id	mandatory	The external id of the client account. It must be unique and it is recommended to use a UUID.
Client language code	mandatory	The language code of the client’s default language. Possible values are "DE" "EN" "FR" "IT".
Password	mandatory	The password of the client account. The provider needs to store this password.
Client first name	optional	The first name of the client. maxLength: 64, minLength: 1.
Client last name	optional	The last name of the client. maxLength: 64, minLength: 1.
Client email address	mandatory	The email address of the client. Must be a syntactically valid email address.
Client mobile number	mandatory	The mobile number of the client. Used for sending the second factor with 2FA.
External SecureExchange id	mandatory	The external id of SecureExchange. It must be unique per provider and it is recommended to use a UUID.
SecureExchange name	mandatory	The name of SecureExchange (it is actually the name of the team safe created for the SecureExchange)
SecureExchange description	optional	A short description which explains the purpose of the SecureExchange. This information will be shown in the SecureExchange UI. maxLength: 1024, minLength: 1.
Client advisor first name	optional	The first name of client advisor. maxLength: 64, minLength: 1. This is the contact information of a person from provider’s side and is visible to the end user.
Client advisor last name	optional	The last name of client advisor. maxLength: 64, minLength: 1. This is the contact information of a person from provider’s side and is visible to the end user.
Client advisor mobile number	optional	The mobile number of the client advisor. This info is visible to the end user as contact information so that they can contact the provider in case of concerns / questions. This can be any mobile number that the provider would to be contacted by end user.
Client advisor email address	optional	The email address of the client advisor. Must be a syntactically valid email address. This info is visible to the end user as contact information so that they can contact the provider in case of concerns / questions. This can be any email address that the provider would to be contacted by end user.

With the above details a SecureExchange can be created. After that a SecureExchange link can be generated and sent to the Client.

Update SecureExchange

The following SecureExchange details can be updated by calling our “update team safe“ or “update account” endpoint.

SecureExchange name
SecureExchange description
Client language code
Client advisor first name
Client advisor last name
Client advisor email address
Client advisor mobile number

The same constraints apply as when creating the SecureExchange.

SecureExchange Deletion

SecureExchanges that are created via APIs can be deleted by calling the “delete“ endpoint.

Upload a file to SecureExchange

A call to the “Upload” endpoint enables a provider to upload a file to a specific folder.

Renaming a folder within SecureExchange

Created folders can be renamed by using the “rename team safe folder” endpoint.

SecureExchange Events

In order for the provider to know about the changes in a SecureExchange, the below events are created and delivered to a provider by means of webhooks:

Document upload event
Document shared event
Document deleted event

It is up to the provider to react accordingly to these events. For example, if the client uploads or shares a document, the provider might notify the client advisor about this event.