➖Trust

This section guides you on how to interact with our API to access bills and various documents of your users. You must have followed the steps in “Add a first user and connection” section.

Billing data

The Trust product exposes subscriptions and documents.

A "subscription" is a document container or group. The purpose may vary by connector, for example to isolate documents linked to a contract. When it is not relevant for a connector, we still simulate a single subscription matching the user account using profile information if available. For bank websites where we can return a RIB and statement documents, we create one subscription per bank account.

Subscriptions

We provide a view to the subscriptions of a user with /subscriptions endpoints:

GET /users/me/subscriptions
GET /users/me/connections/{connectionId}/subscriptions

{
  "subscriptions": [
    {
      "id": 12345,
      "label": "Contrat EZ4225",
      "number": "EZ42250022314",
      "subscriber": "Mr John Doe",
      …
    },
    …
  ]
}

Subscriptions are linked to a connection (they are deleted with the connection).

The subscriptions list reflect the set of subscriptions found when synchronizing with a provider, using a safe archiving rule:

• when a new subscription is discovered, it is added;

• when a subscription is no more found, it is marked with a deleted flag and is not listed by default, but it can still be accessed by its ID or with the ?all parameter.

Documents

We provide a view to the set of documents of a user with /documents endpoints:

GET /users/me/documents
GET /users/me/subscriptions/{subscriptionId}/documents

{
  "documents": [
    {
      "id": 56789,
      "name": "Facture Acme 023315",
      "type": "bill",
      "rdate": "2020-08-27",
      "url": "https://…",
      "thumb_url": "https://…",
      …
    },
    …
  ],
  "first_date": "2017-02-14",
  "last_date": "2020-09-15",
  "result_min_date": "2020-08-30",
  "result_max_date": "2020-09-30"
}

Documents are linked to a subscription (they are deleted with the subscription).

We provide access to raw files of documents with the url property, when such files are available on the website. The file format depends on the connector: most websites provide PDF files, if they don't we expose HTML files.

You can enable the force_pdf configuration key in your API to always generate a PDF version of files. Please note that this configuration takes effect on synchronization only and is not retroactive: any change will only apply to newly-discovered documents.

Captcha

Some websites ask for a captcha, especially for bills. Our system is able to resolve them for you automatically, but this feature is disabled by default. You can enable it by setting the captcha.enabled configuration key to 1. captcha.enabled is set to 0 by default.

If this key is disabled and the website requires captcha resolution, your connection will fall into the websiteUnavailable state. Our resolution system may fail to resolve a captcha for various reasons. As a result the connection would also fall into the websiteUnavailable state, but our background workers will automatically retry later.

We don’t provide a list of websites asking for a captcha since it is subject to change frequently.