Page Comparison

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:

...

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

...

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:

...

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:

...

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:

...

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 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 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:

...

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

curl '{baseurl}/communication/subscriptions/subscriptions/{subscriptionId}/reports' \
    -X GET \
    -H 'api-key: {api-key}'

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:

...

Linking to Expert Profiles

TBD