> For the complete documentation index, see [llms.txt](https://even-financial.gitbook.io/developer-center/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://even-financial.gitbook.io/developer-center/channel-partner-reporting/report-options/channel-partner-reporting-analytics-api.md).
# Channel Partner Reporting - Analytics API
For partners who would prefer to fetch their reporting programmatically, we offer an Analytics API for you to receive lead-level reporting on funnel metrics.
{% hint style="info" %}
Please see [Engine's API Reference](https://engine.tech/docs/api-reference/#engine-by-moneylion-api-analytics) for technical instructions on how to ping Engine's Analytics API and for more specific explanations of expected responses.
{% endhint %}
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
{% hint style="info" %}
\*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
{% endhint %}
**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
{% hint style="info" %}
\*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
{% endhint %}
* `isContacted` - the specified Financial institution has contacted the lead post-offer-click and is pending a future conversion event
* `salesQualified` - the Financial Institution has validated the lead and determined that lead meets their qualification criteria
* `firstPayment` - 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}",
},
```
{% hint style="info" %}
Please note that the /leadEvents endpoint does not currently report on deleted funding/monetization events as of 10/1/24.
{% endhint %}
###
### 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:
* [Appending Client Tags for hosted Partner Page or Embed integrations](https://engine.tech/developer-center/loans-integrations/hosted/partner-pages-embeds/client-tags)
* [Appending Client Tags for Native API Integrations](https://engine.tech/developer-center/loans-integrations/api/client-tags)
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 - Lead Flow
#### Supply Analytics API calls with responses
Supply Analytics - API Calls
##
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://even-financial.gitbook.io/developer-center/channel-partner-reporting/report-options/channel-partner-reporting-analytics-api.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
