Channel Partner Reporting - Analytics API

For partners who would prefer to receive their reporting programmatically, we offer an Analytics API for you to receive lead-level reporting on funnel metrics.

Please see Engine's API Reference for technical instructions on how to ping Engine's Analytics API and for more specific explanations of expected responses.

The analytics API has 3 endpoints:

Endpoints

1. Lead Events

The Lead Events endpoint will return info and timestamps by lead, to highlight the current status of any given lead, and to give a sense of conversion rates at diferent stages of the funnel.

Request/Response Structure

Make a request to the following endpoint:

GET https://api.engine.tech/supplyAnalytics/leadEvents?timestamp={timestamp}

The request response will look something like the following:

{
  "shouldContinuePolling": true, // will be `true` if there is a more recent timestamp you can request for
  "nextUrl": "https://api.engine.tech/supplyAnalytics/leadEvents?timestamp=2024-09-01T11:00:00Z", // will be present with the subsequent timestamp to use, if `shouldContinuePolling` is true
  "data": [
    {
      "id": "5550066157addee59022a5e69b12f26feba5c6ff461210309a4fc846a38c404d",
      "leadUuid": {engineLeadUuid1},
      "leadCreatedAt": "2024-09-01T09:24:45Z",
      "eventType": "offerClicked",
      "eventCreatedAt": "2024-09-01T11:25:22Z",
      "financialInstitutionUuid": {financialInstitutionUuid1},
      "financialInstitutionName": {fiName1},
      "isTest": false
    },
    {
      "id": "faa7b339d89453e284e68e76d0c7b0600f04c276a895a3cbc720803164c45434",
      "leadUuid": {engineLeadUuid2},
      "leadCreatedAt": "2024-09-01T11:43:06Z",
      "eventType": "apiApproved",
      "eventCreatedAt": "2024-09-01T11:44:28Z",
      "financialInstitutionUuid": {financialInstitutionUuid2},
      "financialInstitutionName": {fiName2},
      "isTest": false
    }
  ]
}

Event Types to expect by product type

Loans

Top of funnel / mid funnel events

leadCreated - an Engine Lead UUID was registered in our data warehouse
appSubmitted - the lead submitted the form to check eligibility for offers
apiApproved- the lead was pre-qualified/pre-approved by the specified Financial Institution
apiRejected - the lead was rejected at prequal by the specified Financial Institution
offerClicked - the lead clicked on an offer from the specified Financial institution

Bottom of funnel / monetization events

funded - the lead funded a loan with the specified
lenderQualifiedLead - the lead converted into a HELOC product with the specified Financial Institution (only applicable to HELOC)

Fields that may sometimes, but will not always be present for Loans leads*:

applied - the lead applied with the specified Financial Institution on that FI's site
approved - the lead was approved (on hard pull) by the specified Financial Institution
listed - the loan was listed on an exchange/marketplace by the specified Financial Institution and is pending funding

*Some Financial Institutions report these events to Engine, while others do not, hence why these events may or may not be present in responses for leads

2nd Look Marketplace / Special Offers

leadCreated - an Engine Lead UUID was registered in our data warehouse
appSubmitted - the lead submitted the form to check eligibility for offers
offerClicked - the lead clicked on an offer from the specified Financial institution
conversion - the lead converted into a secondary offer with the specified Financial Institution

Fields that may sometimes, but will not always be present for 2LM funnel leads*:

apiApproved- the lead was pre-qualified/pre-approved by the specified Financial Institution
apiRejected - the lead was rejected at prequal by the specified Financial Institution

*As many offers in the 2nd Look Marketplace are static offers, leads who saw a static offer on their offer table will not show events of apiApproved or apiRejected, but may still have an offerClicked event

is_contacted - the specified Financial institution has contacted the lead post-offer-click and is pending a future conversion event
first_payment - the lead has made a first payment on an account with the specified Financial Institution post-conversion into that product

Savings

leadCreated - an Engine Lead UUID was registered in our data warehouse
appSubmitted - the lead submitted the form to check eligibility for offers
offerClicked - the lead clicked on an offer from the specified Financial institution
opened - the lead opened an account with the specified Financial Institution
funded - the lead funded the account they opened with the specified Financial Institution

Credit Cards

leadCreated - an Engine Lead UUID was registered in our data warehouse
appSubmitted - the lead submitted the form to check eligibility for offers
offerClicked - the lead clicked on an offer from the specified Financial institution

applied - the lead applied for a card with the specified Financial Institution on that FI's site
approved - the lead was approved for a card with the specified Financial Institution after applying

2. Lead Payouts

The Lead Payouts endpoint will return info and timestamps by lead for any lead that has had a monetization event (the events signifying a monetization/payout differ by Product Type; please see Lead Events above). This will show the total of payouts you can expect, by lead, with timestamps for those payouts.

Request/Response Structure

Make a request to the following endpoint:

GET https://api.engine.tech/supplyAnalytics/leadPayouts?timestamp={timestamp}

The request response will look something like the following:

{
    "shouldContinuePolling": true, // will be `true` if there is a more recent timestamp you can request for
    "nextUrl": "https://api.evenfinancial.com/supplyAnalytics/leadPayouts?timestamp=2024-09-06T17:00:00Z", // will be present with the subsequent timestamp to use, if `shouldContinuePolling` is true
    "data": [
        {
            "leadUuid": {leadUuid1},
            "bookedAt": "2024-09-06T00:01:53Z",
            "payoutInCents": 2700,
            "uuid": {eventRecordUuid1},
            "financialInstitutionName": "Extra - SO",
            "financialInstitutionUuid": "075ce8d6-5f56-477c-b04f-a1fc1e000d33"
        },
        {
            "leadUuid": {leadUuid2},
            "bookedAt": "2024-09-05T00:01:54Z",
            "payoutInCents": 24372,
            "uuid": {eventRecordUuid2},
            "financialInstitutionName": "LendingClub - PL",
            "financialInstitutionUuid": "91d08be0-2a8c-4d28-b399-7e1b38e2522e"
        },
    ]

Deleted Payouts

On occasion, payouts may be deleted after creation. When applicable, you will see a deletedAt attribute present in that data object. If so, please take this into account - these will not be included in month-end invoices.

Here is an example of a response object with a present deletedAt timestamp:

{
    "leadUuid": {leadUuid},
    "bookedAt": "2024-09-03T13:06:26Z",
    "payoutInCents": 1000,
    "uuid": "37ec4dde-f305-4d9a-bd92-8f64df219ecb",
    "deletedAt": "2024-09-06T16:17:05.194783Z",
    "financialInstitutionName": "Current- Credit Builder- ML",
    "financialInstitutionUuid": "adfd5a89-ba31-47a1-b40e-4ba0bfb21db5"
},

This event would have initially been returned in a response to:

GET /supplyAnalytics/leadPayouts?timestamp={timestamp}, where timestamp is the timestamp where the monetization event was initially reported to / processed by Engine (here, it would have likely been on 9/3/24 or 9/4/24). This record had the same uuid as seen in this second deleted response.

The deleted payout would be returned in a request to:

GET /supplyAnalytics/leadPayouts?timestamp=2024-09-06T16%3A00%3A00Z

The payout associated with the uuid "37ec4dde-f305-4d9a-bd92-8f64df219ecb" in this case should be deleted from your records.

Reasons for deleted payouts

Payouts can be deleted

When a funded loan / conversion event is canceled within the specified timeframe
When a record was initially reported by a Financial Institution by mistake (i.e. duplicate record for the same event)
When a Channel Partner contract is updated with an effectiveAt date in the past

In the third scenario, you would see an simultaneous deletion and creation in the same response (the new created event would have a different uuid), for example:

 {
    "leadUuid": {leadUuid1},
    "bookedAt": "2024-09-03T13:06:26Z",
    "payoutInCents": 1000,
    "uuid": {eventRecordUuid1},
    "deletedAt": "2024-09-06T16:17:05.194783Z",
    "financialInstitutionName": "Current- Credit Builder- ML",
    "financialInstitutionUuid": "adfd5a89-ba31-47a1-b40e-4ba0bfb21db5"
},
{
    "leadUuid": "15335cb3-ee17-4ab3-8333-26b424b8c874",
    "bookedAt": "2024-09-03T13:06:26Z",
    "payoutInCents": 1200,
    "uuid": {eventRecordUuid2},
    "financialInstitutionName": "Current- Credit Builder- ML",
    "financialInstitutionUuid": "adfd5a89-ba31-47a1-b40e-4ba0bfb21db5"
},

This should be understood as, the payout denoted by eventRecordUuid1 is deleted and replaced by the payout denoted by eventRecordUuid2.

Comprehensive Example of Deleted Payout

In one call to /leadPayouts at a particular timestamp, you might get a response that includes:

{
    "leadUuid": "{lead_uuid_1}",
    "bookedAt": "{timestamp_1},
    "payoutInCents": {payout},
    "uuid": "{event_uuid_1}",
    "financialInstitutionName": "{fi_name_1}",
    "financialInstitutionUuid": "{fi_uuid_1}"
},

In a later call, you might get a response that includes:

{
    "leadUuid": "{lead_uuid_1}",
    "bookedAt": "{timestamp_1},
    "payoutInCents": {payout},
    "uuid": "{event_uuid_1}",
    "financialInstitutionName": "{fi_name_1}",
    "financialInstitutionUuid": "{fi_uuid_1}",
    "deletedAt": {timestamp_2}"
},

In that second response, you may or may not also get a replacement for the deleted payout (if due to a contract change):

{
    "leadUuid": "{lead_uuid_1}",
    "bookedAt": "{timestamp_1},
    "payoutInCents": {payout},
    "uuid": "{event_uuid_2}",
    "financialInstitutionName": "{fi_name_1}",
    "financialInstitutionUuid": "{fi_uuid_1}",
},

Please note that the /leadEvents endpoint does not currently report on deleted funding/monetization events as of 10/1/24.

3. Lead Client Tags

The Lead Events and Lead Payouts endpoints report on metrics broken out by Engine's Lead UUID, our identifier for each individual lead going through our ecosystem. Many partners prefer to analyze metrics according to their own identifier, which is why we provide the ability to append Client Tags to leads you send through Engine's marketplace. See these sections for instructions on appending Client Tags depending on your integration type:

Requests to the Lead Client Tags endpoint will return a mapping of Engine's Lead UUID to your own Client Tag. For example, if you append the Client Tag subId to your leads, responses from the Lead Client Tags endpoint will look something like this:

Request/Response Structure

GET https://api.engine.tech/supplyAnalytics/leadClientTags?timestamp={timestamp}

{
    "shouldContinuePolling": true, // will be `true` if there is a more recent timestamp you can request for
    "nextUrl": "https://api.engine.tech/supplyAnalytics/leadClientTags?timestamp=2024-01-10T03:00:00Z", // will be present with the subsequent timestamp to use, if `shouldContinuePolling` is true
    "data": [
        {
          "id": {engineDatabaseRecordUuid},
          "leadUuid": {engineLeadUuid}, // this is our lead UUID
          "key": "subId", // this is the name of your Client Tag
          "value": {yourSubId}, // this is the identifier for that particular Lead
          "createdAt": "2024-01-10T02:24:47Z"
        }
    ]
}

For a given timestamp in the request, a response will contain all Leads / Client Tags created during that time period of timestamp + 1 hour, each as an object in the data array.

Timing

Timestamps in requests

Timestamps in a request to an Analytics API endpoint will return records for that timestamp plus 1 hour (in UTC). Requests can be made up until the start of the most recent completed hour, e.g. if it is currently September 24, 2024, at 17:05 UTC, the most recent request you can make has a timestamp of "2024-09-24T16:00:00Z". That timestamp will return all records created betwee 16:00:00 UTC and 16:59:59.999 UTC.

Fields in Responses

Records are returned by the Supply Analytics API based on the timestamp of when the record was entered into Engine's Data Warehouse. This is particularly important to keep in mind for the /leadEvents and /leadPayouts endpoints:

For /leadEvents

Events are reported with an eventCreatedAt timestamp, which is when the record itself entered our data warehouse. Confusion can arise here due to the fact that a conversion/monetization event's timestamp is not necessary the eventCreatedAt timestamp - eventCreatedAt denotes the timestamp where the record was processed by Engine (which can occur 1-2 days after the event actually occurred, depending on FI reporting and processing lags). Please see the flow charts below for more details.

For /leadPayouts

Events are reported with a bookedAt field, which denotes when the event actually occurred. This typically does not match the timestamp of when the record was processed into Engine's data warehouse. E.g. a loan that funded on 9/15 at 17:30:00 UTC, might be reported to Engine on 9/16 at 15:30:00 UTC, and might processed into our data warehouse on 9/17 at 12:30:00 UTC (we typically process incoming reporting once daily). In this case, if you GET /leadPayouts?timestamp=2024-09-17T12%3A00%3A00Z, you will see the funded event with the attribute bookedAt:"2024-09-15T17:30:30Z". The bookedAt timestamp will not match the timestamp used to hit Engine's API, and that is by design. Please see the flow charts below for more details.

Identical response for a given request every time

Now that you know how the timestamp parameter functions when querying records, hopefully it is clear that a request to an Analytics API endpoint with a particular timestamp will return the same response every time, regardless of how far into the future you send the request.

Even when payouts are deleted, those deletions will be returned for the timestamp of the record's deletion, not for the timestamp of the record's creation - to reiterate, responses will always be the same, regardless of when the GET request is made.

Flow charts with examples

The following flow charts explain the timing principle of Analytics API responses more thoroughly with a hypothetical example:

Lead flow

Supply Analytics API calls with responses

PreviousChannel Partner Reporting - Looker NextHosted Integrations

Last updated 1 day ago