Notifications for Lead Aggregators

Typical use case for a lead aggregator using the Ping / Callback API to provide notifications about the processing of a lead.

In this use case, Crediterium would submit an organic lead to a lead aggregator through an asynchronous request. During this exchange, Crediterium and the lead aggregator exchange opaque identifiers that allow tracking the specific transaction over time, for billing, performance and compliance purposes. Notice that the actual details of this interaction are outside the scope of the Ping / Callback API.

%%{init: { 'theme':'base', 'themeVariables': { 'primaryColor': '#BB2528', 'primaryTextColor': '#000', 'primaryBorderColor': '#7C0000', 'lineColor': '#F8B229', 'secondaryColor': '#006100', 'tertiaryColor': '#000', 'fontFamily': 'Raleway, Verdana, Arial', 'fontSize': '30px' } } }%% sequenceDiagram participant back as Crediterium participant prov as Aggregator back->>prov: Make async request note left of back: Provides opaque_id prov->>back: Ack request note right of prov: Provides transaction_id

After this point, the lead aggregator will run the lead through its ping tree to try and match with a suitable loan servicer. During this process, the following callback notifications could be generated via this API.

%%{init: { 'theme':'base', 'themeVariables': { 'primaryColor': '#BB2528', 'primaryTextColor': '#000', 'primaryBorderColor': '#7C0000', 'lineColor': '#F8B229', 'secondaryColor': '#006100', 'tertiaryColor': '#000', 'fontFamily': 'Raleway, Verdana, Arial', 'fontSize': '30px' } } }%%sequenceDiagram participant back as Crediterium participant prov as Aggregator note over back, prov: Notifications must include opaque_id and transaction_id opt Lead is sent to the ping tree prov-->>back: Notify action=started, outcome=pending end alt Lead purchased prov->>back: Notify action=completed, outcome=success else Lead discarded prov-->>back: Notify action=completed, outcome=fail end

For the most basic use case, the lead aggregator would send a callback notification when the lead is actually purchased, providing additional information to Crediterium such as the price that the lead sold for. Expanded use cases would also send notifications when the lead actually entered the ping tree, and when the lead exited the ping tree without being purchased.

This open process provides the most flexibility regarding the various lead processing scenarios found in practice.

Example Requests

The following is an example request for signalling the beginning of the ping tree processing for a lead.

curl "https://sandbox.ping.api.crediterium.net/v1/notification" \
  -X POST \
  --header "Content-Type: application/json" \
  --include \
  --data '{"key":"9fd7ef8f-8d09-466a-95c4-dddd865a7e9b","transaction_id":1,"action":"started","outcome":"pending"}'

HTTP/1.1 201 Created
Server: nginx/1.14.2
Date: Fri, 17 Mar 2023 23:21:10 GMT
Transfer-Encoding: chunked
Connection: keep-alive
Content-Range: */*
Content-Location: /v1/

The example below would signal the sale of a lead offered to the aggregator. In this case, the lead was sold so the price is indicated in the request.

curl "https://sandbox.ping.api.crediterium.net/v1/notification" \
  -X POST \
  --header "Content-Type: application/json" \
  --include \
  --data '{"key":"9fd7ef8f-8d09-466a-95c4-dddd865a7e9b","transaction_id":2,"action":"completed","outcome":"success","revenue":42}'

HTTP/1.1 201 Created
Server: nginx/1.14.2
Date: Fri, 17 Mar 2023 23:04:50 GMT
Transfer-Encoding: chunked
Connection: keep-alive
Content-Range: */*
Content-Location: /v1/

Alternatively, the request below would signal the lead exiting the ping tree without finding a matching buyer.

curl "https://sandbox.ping.api.crediterium.net/v1/notification" \
  -X POST \
  --header "Content-Type: application/json" \
  --include \
  --data '{"key":"9fd7ef8f-8d09-466a-95c4-dddd865a7e9b","transaction_id":3,"action":"completed","outcome":"fail"}'

HTTP/1.1 201 Created
Server: nginx/1.14.2
Date: Fri, 17 Mar 2023 23:04:50 GMT
Transfer-Encoding: chunked
Connection: keep-alive
Content-Range: */*
Content-Location: /v1/