Flexperto API Developer Guide (IT)

Overview

The Flexperto API is powerful, as it provides most of Flexperto’s functionality programmatically. Whatever your desires, if you need to integrate Flexperto in your CRM or simply require access to individual features, like persisting archives, this guide has you covered.

Glossary

• Tenant - A tenant is an Enterprise Customer for which flexperto provides platform services. Tenants are strictly separated and have unique ids which related to their dedicated platform within the flexperto infrastructure. Throughout this document, the tenant demo will be used

• Platform and Environment - As mentioned prior, a platform is a tenants dedicated and isolated space. In addition, the flexperto infrastructure provides a platform on the following environments:

  • test - an environment without SLA guarantees, meant for integration and implementation purposes. A tenants test platform is available at https://{tenantID (eg. "demo")}.test.flexperto.com

  • live - an environment with SLA guarantees, meant for productive use. A tenants live platform is available at https://{tenantID (eg. "demo")}.live.flexperto.com.

• Expert - An expert typically is an employee of a tenant. Depending on your business domain, you can read expert for example as agent, broker, consultant or doctor.

• Customer - A customer is a tenant's end customer, typically the entity a tenant's expert is providing the tenant's business service for

• Admin - A admin is a special user on a tenant with elevated rights. Administrators have full access to the API, and can impersonate other users when interacting with the API.

• CRM - A system that is operated by the tenant and provides services for expert's. Typically the services enable:

  • Documenting Communication and Interaction between experts and customers

  • Engaging in Communication between experts and customers (eg. Scheduling an appointment or delivery of legal documentation to a customer)

• API - The flexpertos Application Programming Interface which is JSON/REST/OpenAPI2.0 based. API-clients can be generated based on the OpenAPI2.0 specification of the flexperto API (for a general introduction to OpenAPI2.0 refer to https://swagger.io/specification/v2/)

Requirements

The listed use cases have the following requirements for implementation:

• Administrative access to a dedicated platform.

• A way of sending HTTP requests to the Flexperto API, be that manually via tools like Postman, or programmatically via a service or CRM.

Base URL Schema

The base URL for any API call follows this schema:

where {tenant} refers to the tenant ID of your company, e.g. mlpfinanzberatung or quirinprivatbank, {environment} refers to the platform environment, e.g. test or live. The base URL for your use case may look like:

When you encounter {baseurl} in this document, replace it with your own base URL.

Use Cases

The following use cases are recurring journeys that tenants on the flexperto platform want to provide to their experts. All of these use cases are powered by the Flexperto API.

Authentication

As all following use cases for an Integration require interaction with the flexperto API. Generally, authentication against the flexperto API happens via an API-Key in the form of a JSONWebToken. An API-Key has a direct relation to a User and is valid for 2 years. Therefore an API-Key can be owned by an Expert, a Customer, or even an Admin (which would be a technical user for system integrations in these scenarios). There are two approaches:

• self-service integration

• integration via a technical user

Self-Service Authentication

The result of a self-service authentication is an API-Key that is owned by the authenticating User. The API-Key can only be used to act in the name of the user, and can only be obtained if the user is already registered on the flexperto platform and is in possession of email and password he used to sign up on the flexperto platform. Most use cases we have seen do not require self-service authentication, which is why documentation on how this could be achieved is left out here. If your use case requires self-service authentication, please reach out to us.

Administrative Authentication

With administrative authentication, your integration makes use of an API-Key owned by an administrator and therefore has full access to the flexperto API. In order to obtain an administrative API-Key, please log in to your tenant and navigate to the “Create new API Token“ page: https://demo.test.flexperto.com/admin/api/token/new

Once you created an API Key, please copy it and store it somewhere safe. Flexperto does not possess a copy of the API-Token, and can not recover it. You will be redirected to the API Token Management page, which is where you can also create new tokens or redeem old tokens (in case your token expires or you would like to rotate tokens more often than every 2 years).

Expert Provisioning

Most of the services that the flexperto platform provides, require at least an expert to be registered with the flexperto platform. In case of a Self-Service Authentication, an expert will already have registered himself on the flexperto platform, which is why this Scenario is omitted here. In the case of an Administrative Authentication, the expert might not yet be registered on the flexperto platform. As a very first step you should extend the user data of the expert with another property called flexperto_account_id. The property will contain the id of the experts account on the flexperto platform, and you will use it later on as a reference to such. If this property has not been set yet, this is also your datapoint to decide whether to find or create the experts account on the flexperto platform. The primary and unique identifier of flexperto accounts is the email of a user. As such the very first thing you should do, is to verify if the expert has already in some way been registered in the platform using the ListUsers Endpoint:

In case the Expert is already registered, the response will include his account:

In this case, you should store the id as the previously mentioned flexperto_account_id and stop the routine. If the account does not exist yet, it’s time to create it via the CreateUser Endpoint:

The response will again include the id property, which should store as mentioned flexpert_account_id.

Next, the email address of the account needs to be confirmed. In a non-integration scenario, the expert would have received an email with a confirmation link. In an integration scenario, it is up to you to confirm the email address. In most cases, the email address of the expert is already confirmed, which means you can simply continue with confirming the email using the ConfirmEmail Endpoint:

Once you did run through these steps, the expert is registered on the flexperto platform and his account is fully functional. You now, in addition, have access to the experts flexperto_account_id which you will require for subsequent use cases.

Starting a Video-Call

A common use case is to enable experts to start a video-call from within the service or CRM. Typically a button to do so is placed in relation to a customer (for example on a single view of a customer). Assuming, such a button has been implemented in the service or CRM, once the expert clicks on the button, you will have to first obtain the customer's personal data and the experts flexperto_account_id from your persistence layer. Using this data, you can perform the following API Call:

The API-Call will cause a meeting to be reserved on the flexperto Platform. The meeting will be moderated by the expert with the given flexperto_account_id, and given participants will be able to initially participate (inviting additional participants from within the meeting room, later on, is obviously still possible). Strictly speaking, no information about other participants is required (the participants property can very well have a value of [{}]). However, we do recommend to hand over information that is available, since it eases use and improves the User Experience by personalizing the Meeting Room (eg. showing the name of the participants).

As a response the API will return:

The response contains a few important things to note:

• First, there is the id (from here on referred to as the meetingId). Upon successful response, you should document in the service or CRM, that the expert started a Video-Call with the customer, and save the meetingId next to the documentation. The meetingId will, later on, be required for obtaining flexperto side documentation of the call.

• Next, there is the moderators join link. Using this link, anyone can authenticate as the expert, and will immediately join the meeting.

• For each participant included in the meeting, an individual link is generated and returned. These links also authenticate the user as the related participant and forward him immediately into the meeting.

All links are only valid for a limited amount of time. Which timespan this is, you can define when reserving the meeting (access_link_valid_until and access_link_not_before). You can now redirect the expert to the moderators join link - he will automatically join the Video-Call and wait for the customer to join.

Starting a Video Call with a Member of a Group

Currently, it is not possible to start an Instant Call with a group. A patch is currently in planning that will allow linking to a Groups Instant Call Process. Extended API functionality for identifying group availability, is planned to be available in Q4.

Signing Documents

The flexperto API provides functionalities required to sign a set of Documents. This functionality can be used to obtain Customer Signatures on, for example, contracts. Be aware that due to licensing limitations, you are not allowed to use the API for mass-signing processes. Fundamentally, you are allowed to integrate with the API and build a digital workflow to support your employees, but the workflow is required to be triggered by a human on a per customer/session basis. Mass-requesting of signature is not allowed.

There are two flows supported by the flexperto API:

• Asynchronous Flow - Uploading and Preparing documents for a customer to be signed at a later point in time

• Synchronous Flow - Uploading and Preparing documents for a customer to be signed as part of a flexperto session

In both cases, the Documents and their status will always be accessible by your employees through the flexperto Dashboard.

Asynchronous Flow

In the asynchronous flow, you start by initiating a new Contract Session. A Contract Session is a life-cycle container for multiple documents to be signed:

As a response, you will receive the Signature Sessions unique ID. Maintain this ID as a reference, as subsequent interactions require it:

The meta field contains foreign_session_id, which in VES and QES use cases you can use to obtain the related identification data.

Once the Contract Session has been created, you can start attaching documents to it, which should be signed. Keep in mind that the flexperto API does not provide the means to place signature fields on your documents. Please ensure that your documents which should obtain one or several signatures, already include signature fields (consult the technical documentation of your PDF generation tool kit / SDK). In order to attach a document to a session, first, request an upload URL:

The response contains the upload URL:

The URL can be used to upload documents to the flexperto file storage. It is valid for 1 hour. Keep in mind that currently up to 20 Documents with a total (not individual) size of 50MB are supported. Uploads are accepted as multipart/form-data:

While the request is to be formatted in multipart/form-data, the response is formatted in JSON:

The response contains the documents fileId id which can now be used to attach the document to the previously initiated contract session:

As a response, you will obtain the Documents ID, which in turn you should keep a reference of:

Using the Endpoint GET {baseurl}/api/v2/collaboration/contracts/contracts/documents?sessionId={sessionId} you can query for all the documents and check on their status at a later point in time. A few words about the status of a document, possible values are:

• ATTACHED - The document has been attached to a session

• UPLOADED - The related session has been handed over for signature / additional documents can not be attached to the session

• UPDATED - The document has been changed within the signature session (eg. a signature has been placed)

• FINISHED - All signatures have been placed on the document and the session has been finished

• DELETED - The document has been deleted

• FAILED - Only occurs for ves / qes sessions. If the identification process as part of these sessions fails, the document will transition to the FAILED state, and the reason for failure will be populated in failure_reason.

Once you have attached all documents that should be signed to the session, it is time to hand over the document for signature:

The Response contains the link for the signing party. Flexperto does not deliver an email to that party, this is up to you:

Once the signing party has placed all signatures, the related contract sessions transaction_completed property changes to true.

There are several ways to obtain signed Documents:

• Downloading the Archive of a Conference (see the Conference Archiving Section of this Documentation below)

• Downloading the Signature Sessions Archive

• Downloading individual documents

Downloading the Signature Sessions Archive

Using the documents-archive endpoint, you can download an Archive of the Signature Session:

As a response, you will receive a ZIP-File that contains all signed documents as well as an audit report. You can obtain the audit report individually using:

Downloading Individual Documents

Once documents are signed, you can use the document download endpoint to download the signed version of a document:

Synchronous Flow

The Synchronous Flow works in a very similar way to the Asynchronous Flow. Notable differences are:

• When initiating a Contract Session, in the request payload, you have to provide the meeting_id property, providing the id of the related meeting

• Be aware that the Contract Modal of your employee in the Meeting Room does not obtain live updates when you add documents. He has to close and open the Contract Modal again for obtaining live updates

• Be aware that until you hand over a session via the API, your employee is able to attach additional documents to the Contract Session using the Contract Modal in the Meeting Room

• For these reasons, we generally suggest that you request the new Meeting, then perform the API Calls to initiate the Contract Session, attach documents, and hand over the session, before redirecting your employee into the Meeting Room.

• Be aware that once a Contract Session has been handed over, the Employee will be able to join the Contract Session and place additional signature fields on the documents. In this flow, it should also be the employees' responsibility to explain the documents to other participants and to hand them over to them for signature (you can ignore the Contract Session URL in this case)

Recording conferences

Flexperto affords experts to record conferences in one of two ways: automated, or manual. Administrators of a platform can enable either by toggling the enableAutomaticRecording (for automatic) or enableRecordingVerbalConsent (for manual) configuration settings. Note that these are mutually exclusive. Recordings include all streamed media (video, audio, shared screens) in one combined video file (codec information: video: h264, audio acc, format: mp4).

How can I record a conference?

Automated recordings start immediately, as soon as any participant of a conference begins enabling their camera, microphone, or shares their screen. It does not stop until the conference has ended and all participants have stopped streaming media.

Manual recordings can be started by the expert, by clicking the start recording button in the menu. A popup will appear, prompting the expert to ask participants for consenting to the recording. Once approved, the recording will start, and won’t stop until the expert manually stops it, or the conference has ended and all participants have stopped streaming media.

How can I retrieve a recorded conference?

Currently, recordings can only be retrieved as part of an archive .

Archiving (MiFID II)

Flexperto provides archiving of all data associated with a business interaction between the expert and their customers. Administrators of a platform can enable archiving by toggling the enableAutomaticArchivingOfConferences configuration setting.

What is in an archive?

The archive file is a single, compressed file (zip) that holds aggregated information about a conference, including data such as:

• whiteboard event history (JSON) and uploaded documents (binary)

• text-chat history (JSON) and uploaded files (binary)

• multimedia recordings of video and audio tracks and shared screen (mp4)

• meta data of the conference (JSON)

• contracts signed via E-Signature as part of a conference (PDF), this does not include asynchronous contract sessions created on the dashboard

Archive files are kept on the platform until they are claimed, at which point they enter an expiration period. After a short delay (3 days by default), the archives are deleted.

The archive record (retrievable via the API) is a JSON object describing relevant associative data of the archive, including conference start and end dates, expert and participant information. The object structure is described in the CommunicationConferencesArchiveResponse model in our API documentation.

How can I interact with the flexperto API to manage my archives?

These API endpoints are relevant for the archiving process:

• GET /communication/archives/archives lists all archive records of the tenant.

• GET /communication/archives/archives/{archiveId} finds a single archive by its unique ID.

• GET /communication/archives/archives/{archiveId}/download downloads the compressed archive file.

• POST /communication/archives/archives/{archiveId}/abandon signals that an archive has been claimed. After an archive has been claimed it will be deleted from flexperto’s platform at a later point in time.

• POST /communication/subscriptions/subscriptions/webhook affords registering a web hook that is triggered once an archive becomes available.

Assuming a conference has been recorded, and the archiving feature is enabled on the platform, flexperto creates an archive record and begins processing the relevant files. The archive goes through several states:

1. While the archive is being processed, the status field is PROCESSING. In this state, the compressed file is not yet available, and can not yet be downloaded via the /download endpoint.

2. Once all data has been aggregated, and the zip finalized, the status moves to AVAILABLE. Now the archive can be downloaded via the API.

3. If there have been any failures in the process, the status is set to FAILED, and the error field describes the failure.

4. When the /abandon endpoint has been called, the archive is scheduled for expiration. The status changes to ABANDONED. In the expiration period (which defaults to 3 days), the archive file can still be downloaded via the /download endpoint.

5. After the expiration period has passed, the archive record transitions to the EXPIRED status, and the file can no longer be downloaded via the /download endpoint. The file is deleted from the flexperto platform.

When are archives deleted?

Archives are not automatically deleted, unless they are claimed, by calling the POST /communication/archives/archives/{archiveId}/abandon endpoint.

How can I claim archives?

How, specifically, you can integrate the flexperto archiving process into your service or CRM depends on your business processes. We offer two distinct approaches for claiming archives, via registering a web hook, or by regularly polling the API. The code examples are using bash, but any language can be used.

For web hooks, follow steps A1 - A3 and continue with C1 - C3, for polling, follow steps B1 - B2 and continue with C1 - C3.

Approach: Registering a web hook

This approach includes registering a web hook against the flexperto API, which is triggered when an archive becomes available.

A1. Create a server with a new endpoint. The service should expose a public POST endpoint, for example POST https://internal.mycompany.de/callbacks/archive, that receives callbacks from flexperto in JSON format. The received notification POSTed against your callback follows the ProduceNotificationRequest model in our API documentation, where the data field is populated with the archive-id and archive_subject. A notification would look like the following snippet.

A2. Register the web hook. Replace {api-key} with your API token, and {your-callback-url} with the previously exposed endpoint, e.g. https://internal.mycompany.de/callbacks/archive.

A3. On receiving a notification for an available archive, extract the archive ID from response.body.data.archive_id, and continue with step C1.

Approach: Polling the API on regular schedule

This approach comprises of running a script on a regular basis, via cron job, mongodb agendas, postgres pg_cron, etc. As part of your back end, regularly query all available archives from the flexperto API, and persist them.

B1. As part of your script, fetch all available archives. Replace {api-key} with your API token.

The response will be a list of archive records:

B2. For any archives received, reject archives you have already claimed, assuming that you are persisting already claimed archives somehow (See C3). For all remaining archives, extract the archive.id. Continue with step C1.

Regardless of which approach you use, continue with:

C1. Download and persist the compressed file. Replace {api-key} as before, and {archive-id} with the archive ID you extracted in the previous step. The response here will be a 302 (Found), redirecting to our S3. We recommend that you persist the file in your document storage of choice (e.g. S3).

C2. Signal that you have claimed the archive by calling the the /abandon endpoint. This will change the archive status to ABANDONED. Replace {api-key} and {archive-id} as before.

C3. Persist the archive record. We recommend persisting the archive record in your database of choice so that you can filter unclaimed archives in a future iteration, and for an easier association between archive files, archive records, and your own compliance business processes.