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.
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.
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/