Flexperto API Developer Guide (EN)

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.

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:

• folder themis:

  • text-chat history (JSON)

  • uploaded files (binary)

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

  • metadata of the conference (JSON), including (but not limited to):

    • the tenant ID

    • moderator E-Mail, name, and account ID

    • participant E-Mails and names (when given), account IDs, and permissions

    • start and end date-time of the conference

• folder mithra:

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

Are archives guaranteed to be immutable?

On creation, an archive file is hashed, and its hash is stored in the archive record. In retrospect, this hash can be used to verify the integrity of the archive. If a notification is registered against the Flexperto API (see below), consumers are also immediately notified of the available archive, including the hash.

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

These API endpoints are relevant for the archiving process:

What is the life cycle of an archive?

Assuming a conference has been recorded, and the archiving feature is enabled on the platform, an archive is created:

1. While being processed, the archive transitions through several internal states that mark steps in creating the archive (PROCESSING, ARTIFACT_GATHERING_COMPLETE, PACKING). In these states, the compressed file is not yet available, and can not yet be downloaded via the download archive endpoint.

2. Once all data has been aggregated, and the zip finalized, the status transitions 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 archive 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 archive 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 archive 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 abandon archive 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, registering a webhook, or regularly polling the API. The code examples are using bash, but any language can be used.

Approach: Registering a webhook

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

Step 1: 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.

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

Step 3: On receiving a notification for an available archive, extract the archiveId from response.body.data.archive_id and the conferenceId from response.body.data.archive_subject.conference_id. You will need both later.

Step 4: Download and persist the compressed file. The response here will be a 302 (Found), redirecting to our S3. We recommend that you persist the file in your object storage of choice (e.g. S3). Replace {archiveId} with what you extracted in step 3.

Step 5: Signal that you have claimed the archive by calling the abandon archive endpoint. This will change the archive status to ABANDONED. Replace {api-key} and {conferenceId} as before.

Step 6: We recommend persisting the archive record in your database of choice for an easier association between archive files, archive records, and your own compliance business processes. At the very least, persist the conferenceId, archiveId and sha256CheckSum fields.

Approach: Polling the API on a regular schedule

This approach involves 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.

Step 1: Fetch all available archives. Replace {api-key} with your API token.

The response will be an object, which includes the key items, which holds the list of available archive records.

Step 2: For each archive, extract the id as archiveId, and the subject.conference_id as conferenceId. Download and persist the compressed file. Replace {api-key} as before, and {archiveId} with the archive ID you extracted. The response here will be a 302 (Found), redirecting to our S3. We recommend that you persist the file in your object storage of choice (e.g. S3).

Step 3: Signal that you have claimed the archive by calling the abandon archive endpoint. This will change the archive status to ABANDONED. Replace {api-key} and {conferenceId} as before.

Step 4: We recommend persisting the archive record in your database of choice for an easier association between archive files, archive records, and your own compliance business processes. At the very least, persist the conferenceId, archiveId and sha256CheckSum fields.

Webhooks

The flexperto platform provides Webhooks in order to ease implementation of integrations as well as to provide close-to-realtime data exchange between the flexperto platform and your systems. In order to receive Webhooks, a Subscription has to be created. You can do so via:

Once a Subscription has been created, you will receive HTTP Callbacks at the url you have specified. The API-Documentation of your tenant ({baseurl}/api/v2/spec) lists the available topics for subscription under the “create Subscription” endpoints request specification.

Subscriptions can only be managed by administrators of a tenant, and are not account scoped (read as administrators can manage subscriptions of other administrators of the same tenant).

There are certain guarantees and contracts which come in line with providing and consuming Webhooks. These are:

Payload

Webhooks will always be delivered with an HTTPs POST request to your endpoint. The Payload will always be of Content-Type: application/json. The payload relating to a topic is documented on the API-Documentation of your tenant ({baseurl}/api/v2/spec). Scrolling down the page, the Models section should contain a model that relates to the topic (searching for NotificationPayload should navigate your browser to the section right away). Generally Webhook payloads at flexperto are permissive. There might be additional properties submitted, which are not documented on the payload type. flexperto neither guarantees their existence for every payload submitted, nor guarantees the type of these properties. For those properties listed, and which are marked as required on the specification, flexperto guarantees that they will always be present, and that their value will always be of the specified type. For those properties that are listed but not required as part of the specification, flexperto does not guarantee their presence, but if present, guarantees their value type.

Targets

Webhooks will only be delivered via TLS. Non https endpoints will either not be accepted or upon registration, or Webhooks will not be delivered. The url you provide must be DNS resolvable. The DNS resolved IP must not be a IANA IPv4 Special-Purpose Address (or IPv6 equivalent) or delivery will fail.

Delivery

When you receive a Webhook, you must respond with a status code that is greater than 199 and smaller than 399 (199 < statusCode < 399). A Webhook has to be responded to within 3 seconds. If any if these conditions are not given, flexperto will perform another delivery attempt. flexperto will perform up to 4 delivery attempts with an exponential backoff of 100ms. Therefore flexperto provides an at-least-once delivery guarantee (within 4 attempts of course). Flexperto does not provide an up-to-once guarantee. This means that in rare cases it is possilbe for you to receive the same webhook twice. Therefore please ensure that your implementation is idempotent. Flexperto performs delivery concurrently. It is possible that you receive multiple webhooks at the same time. Therefore please aim for your callback implementation to be atomic. Flexperto does not provide in-sequence/in-order guarantees. It is possible that you receive webhooks out of order (read as a failing delivery attempt, does not pause other deliveries). Continuously failing Webhooks will not cause flexperto to pause your subscription, but flexperto will be alerted about such cases and might approach you for verification. While statusCode 302/301 are accepted as a response callback, flexperto will not follow the redirects.

Reports

flexperto does maintain a backlog of the 50 latest delivery attempts of your subscription in the form of Reports. If you are observing unexpected retries or not receiving Webhooks at all, it is worth to take a look at the reports of your subscription. You can obtain them via

Security

Beyond of requiring TLS, flexperto does not provide an authentication mechanism for payload delivery between the flexperto platform and your systems. We therefore strongly recommend to implement one or all of these security mechanisms:

• Add a secret to the callback URL. Do not use URLs like my-site.com/callbacks/flexperto as they can be guessed easily. Instead embed a non-guessable path parameter (eg. my-site.com/callbacks/flexperto/F40mfum7pZC8DtdgGOYSijx26blP0HLs) for you to challenge

• Rotate the secret of the callback URL regularly. Using the API you can easily create a new subscription with the same topic but a different embedded path-parameter. Use this technique to regularly change the secret (be advised though that when you delete the old subscription, and there are still webhooks in-flight, those will be re-delivered upon failure up to 3 times anyways).

• Only allow requests originating from flexperto IP-Addresses. These are listed as part of the flexperto system requirements.

Linking to Expert Profiles

TBD