Sharing Data via API

Glossary of Terms

Term	Definition
Partner	An external partner of Liberis
Client	An external client, about which the Partner shares data to enable generation of personalised Liberis offers.
Revenue Claim	Information about transaction(s) within a given time period (E.g.: For the month of January 202x this Partner Client made £30,000 revenue over 150 transactions.)

Overview

A Partner can share anonymised Client and Revenue Claim data through Partner Client Service and later receive related offers for each Client.

Workflow

High Level

The Partner sends anonymised Client data and Revenue Claim data to Liberis. We then process this information to understand which Clients are eligible for Liberis products and generate personalised offers for each Client. Finally, we share personalized offers that the Partner can use to execute campaigns.

Detailed e2e Workflow

POST: Creating Partner Clients

Partners can use the Create Partner Clients endpoint to send anonymised Client data that Liberis uses to check Clients' eligibility and create personalized offers for our products.

Request

When Partner Client Service receives the following request payload (an array of Clients) it returns a response that includes a status check URL. The Partner can use that URL to verify the status of each individual request sent to the Partner Client endpoint.

[
  {
    "partner_client_id": "1b7901db-4879-4616-8052-c73e29664bda",
    "client_start_date": "2024-04-23T13:44:03.585Z",
    "entity_type": "SoleTrader",
    "other_identifiers": [
      {
        "key": "MerchantId",
        "values": [
          "123456"
        ]
      }
    ]
  }
]

Response

If the initial request succeeds, the response will include a unique status ID and status check URL. Partners can use these to understand the status and condition of the request and the collection of Partner Client items sent in it.

{
  "status_check_id": "1b7901db-4879-4616-8052-c73e29664bda",
  "status_check_uri": "/api/v1/Clients/Status/1b7901db-4879-4616-8052-c73e29664bda"
}

You can send a GET request to the route in status_check_uri field to understand the status and condition of the request that was sent.

GET: Partner Client Status Check

Partners can use the Partner Client Status Check endpoint to view the status of each individual Partner Client they sent in the original Create Partner Client request.

Partners can omit this endpoint, but we recommend using it to understand the status of a Create Partner Client request. It also includes validation errors to if there was anything wrong with any of the individual Client data.

Request

GET {BaseUri}/api/v1/Clients/Status/1b7901db-4879-4616-8052-c73e29664bda

This endpoint can be filtered by specific states as needed

GET {BaseUri}/api/v1/Clients/Status/1b7901db-4879-4616-8052-c73e29664bda?state=failed

Allowed state values: Pending, Completed and Failed

Response

The response will indicate the status of the individual Clients from the original payload sent in the Create request.

Valid

[
  {
    "url": "/api/v1/Clients/1b7901db-4879-4616-8052-c73e29664bda",
    "data": {},
    "status": {
      "state": "Failed",
      "validation_errors": [
        "entityType is required"
      ]
    }
  }
]

Each item have a status and a data object containing the original item.

Additionally, if we have successfully saved the Client, the url will point to that Client.
We will also include a list of validation errors with the status of each Client that was invalid.

POST: Create Revenue Claims

The create Revenue Claims endpoint is used to send Partner Client Revenue Claim data which Liberis will use as part of an Eligibility Check for a given Partner Client.

These Revenue Claims drive the maximum offer value available for each Partner Client.

Request

The following request payload of an array of Revenue Claim data will return a response that includes a Revenue Claim status Uri so that each Partner can verify the status of each individual request sent to the Partner Client Service Revenue Claim endpoint.

[
  {
    "time_period": {
      "start_time": "2024-01-01T00:00:00Z",
      "end_time": "2024-01-01T00:00:00Z"
    },
    "total_amount": 100,
    "currency": "GBP",
    "transaction_count": 36,
    "industry_category": {
      "scheme": "MCC",
      "code": "1234"
    },
    "other_identifiers": [
      {
        "key": "MerchantId",
        "values": [
          "123456"
        ]
      }
    ]
  }
]

Response

{
  "status_check_id": "1b7901db-4879-4616-8052-c73e29664bda",
  "status_check_uri": "/api/v1/Clients/Status/1b7901db-4879-4616-8052-c73e29664bda"
}

You can send a GET request the value in the "status_check_uri" field to understand the status and condition of the related request that was sent

GET: Revenue Claims Status Check

The Partner Client Status Check endpoint is intended to inform a Partner of the related request status for each individual Partner Client that was sent as part of the payload in the original Create Revenue Claim request..

This is considered an optional call, although useful to understand the status of a Create Revenue Claim request i.e. Have some Revenue Claim items failed? If so, why?

Request

GET {BaseUri}/api/v1/Clients/Status/1b7901db-4879-4616-8052-c73e29664bda

This endpoint can be filtered by specific states as needed

GET {BaseUri}/api/v1/Clients/Status/1b7901db-4879-4616-8052-c73e29664bda?state=failed

Allowed state values: Pending, Completed and Failed

Response

A response will indicate the status condition of the Revenue Claim payload sent in a Create request

[
  {
    "url": "/api/v1/Clients/1b7901db-4879-4616-8052-c73e29664bda",
    "data": {},
    "status": {
      "state": "Failed",
      "validation_errors": [
        "entityType is required"
      ]
    }
  }
]