PP+ Lead API V2 Developer Guide

Modification History

All interface modifications (except corrections for typographical errors) should be accompanied by a change communication notice in accordance with the Dealer Facing Interface Documentation Enterprise Architecture (EA) Standard. The date on which the modifications are implemented, as well as the retirement of any previous format, is noted within that communication. Each Caterpillar application owner reserves the right to determine the date(s) on which an interface change is implemented as well as when previous versions of the interfaces are retired, as long as the advance notification of the change is provided in accordance with this standard.

This is a link to the location where all interface change communications are posted for review: Digital Integration Services Portal - DICE Communications

Glossary

CRM

Customer relationship management (CRM) is a technology for managing all your company’s relationships and interactions with customers and potential customers. A CRM system helps companies stay connected to customers, streamline processes, and improve profitability.

Leads

Leads generated by Caterpillar marketing ecosystem.

Dealer Management System

Dealer Management System is a bundled management information system containing software that supports all aspects of running a Dealership

JSON (JavaScript Object Notification)

JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML.

Salesforce

Salesforce is a CRM system that allows salespeople to track their sales, support people to track their cases, and the entire company’s employees to collaborate with each other.

Sales Lead Community

Community for dealers to Collaborate with Caterpillar ISRs on Sales Opportunities.

API

Application programming interface to download Marketing Opportunities on Sales Community and send updates for Marketing Opportunities that are acted upon by dealer in their CRM.

Ping Federate

OAuth 2.0 client credentials identity management service provider

Process Overview

Leads are generated via different resources. Deploying new technology-enabled Lead Distribution and Management processes can greatly improve speed-to-market. These can be pulled by dealers through an API.

This will pave the way to our blue dot vision of NextGen Lead Distribution and Management to help:

• Drive Growth & Efficiency
• Achieve Scalability & Flexibility
• Provide Enhanced Customer Experience
• Enable Faster Decision and Management Support

Dealers follow up on these opportunities and process them via their sales funnel process. Dealers are required to send updates back to Caterpillar through an API. This feedback is made available in the Caterpillar lead sales community built on Salesforce CRM.

This document will describe the API interface that will enable NextGen Lead Distribution and Management

https://cat.com is one of the sources of leads.

Process Flows

Prioritized Lead/Opportunity Process Flow

PP + SL V2 Process(Connected Dealer)

Dealer Mapping

This mapping will be entered in Dealer CRM Mapping Area. Following mapping are required

1. Rejection Reason
2. Disqualification Rason
3. Closed Lost Reason
4. Sales Stage

Interface Type and Transmission Method

This interface requires using REST API to GET Leads and POST opportunity sales funnel updates from dealer’s CRM.

Caterpillar Preferred Option

N/A

Related Interfaces

N/A

Email DICE_Sales@cat.com to contact the appropriate DICE Team Member for this interface.

Field Types and Definitions

The following list provides the references to element types that will be used in this document.

Caterpillar Opportunity Stages

General Comments & Definitions

Comments

This solution provides a simple REST Web service that enables pulling lead that have not been pulled earlier. The client will invoke the service at regular intervals of time and frequently to retrieve new leads, act on those and send feedback to Caterpillar

Process Summary:

1. CAT will engage Dealer to onboard Lead NextGen Lead Distribution and Management program.
2. Cat ECRM team receives request from CAT Marketing to setup dealer to access Lead API
3. Cat ECRM requests Client ID from CAT Identity Access Management (IAM) group
4. Corporate Identity Access Management creates Client ID for dealer in PingFederate environment (usually within 1 working day for QA and every Thursday for production)
5. Dealer connects to API’s frequently (recommended to make GET call every 15 minutes) to pull new Leads
6. Dealer connects to API’s and send updates to Leads in real time by POSTing the updates.

https://services-stg.cat.com/marketing/ecrm/leadManagement/v2/leads

https://services.cat.com/marketing/ecrm/leadManagement/v2/leads

Invoking the Service (GET)

The REST web service is designed for program-to-program integration technology. Access to the service can be broken into three steps.

Step 1 - Open a connection

Open a connection the OAuth service using the QA or Production URL.

QA URL - https://fedloginqa.cat.com/as/token.oauth2

Production URL

• https://fedlogin.cat.com/as/token.oauth2

Step 2 – Provide authentication

Set the Header and Body key and value information of the request. The basic credentials are the Client ID and secret provided to the dealer as a Base64 encoded ASCII string.

 Header (key: value)
 Content-Type: application/x-www-form-urlencoded
 Authorization: Basic \<credentials\>
 Body (key: value)
 grant_type: client_credentials
 scope: manage:all

The Body content type may need to be set to x-www-form-urlencoded manually depending on your application.

Step 3 – Execute the Fed Login POST request

Executing the POST request successfully will return a JSON object containing the access token.

{"access_token": “eyJhbtpZCI…”, "token_type": "Bearer", "expires_in": 3599}

All access tokens expire in 60 minutes. HTTPS 200 (OK) is sent to the client when the operation is successful. The connection is released at the end of the operation. The REST service provides only JSON responses.

Step 4 – Execute the GET request

Invoking the Service (POST)

Step 4 – Execute the POST request

** Available only with the use of test credentials which are available upon request see “Testing Procedure”

Error Architecture, Error Codes, and Error Messages

Possible responses:

Error messages are returned as JSON objects indicating the issue to be resolved. The list of possible error messages is below.

{"message": "Invalid access token."}

{"message": "Invalid request header."}

{"message": "You are not authorized to perform that action."}

Elements, Characteristics, Operator Symbols

All character sets (Double byte, Eastern European, etc.) are supported in this interface.

Array Sizes

N/A

Currency Considerations

N/A

Regional Considerations

None

Layouts

Layout Comments

N/A

Layout Types / General API Information

Response JSON – Leads object

This end point provides latest snapshot of the lead with all current values.

Request JSON – Leads object

Sample POST body for Scenario: Lead Status = Rejected and rejectedReasonComments is not required

 [
   {
     "leadId": "00Q1W00001SmV5oUAF",
     "dealerLeadId": "A123VSDFDFF",
     “customerPreviouslyKnown”: “Yes”,
     “customerContacted”: “No”,
     "dealerCustomerNumber ": "AO12CD",
     "leadStatus": "Rejected",
     "rejectedReasonWhy": "Bad Contact Information",
     "currencyIsoCode":"USD"
   }
]

Sample POST body for Scenario: Lead Status = Rejected and rejectedReasonComments is required due to value of rejectedReasonWhy

 [
   {
     "leadId": "00Q1W00001SmV5oUAF",
     "dealerLeadId": "A123VSDFDFF",
     “customerPreviouslyKnown”: “Yes”,
     “customerContacted”: “No”,
     "dealerCustomerNumber ": "AO12CD",
     "leadStatus": "Rejected",
     "rejectedReasonWhy": " For Another Dealer ",
     "rejectedReasonComments": " Incorrectly routed to our dealership",
     "currencyIsoCode":"USD"
   }
]

OR

[
   {
       "leadId": "00Q1W00001SmV5oUAF",
       "dealerLeadId": "A123VSDFDFF",
       “customerPreviouslyKnown”: “Yes”,
       “customerContacted”: “No”,
       "dealerCustomerNumber ": "123433",
       “dealerOpportunityId”: null,
       "targetDate":null,
       "probabilityOfClosurePercentage":null,
       "rating":null,
       "dealerSalesRep":"JOHN DOE",
       "opportunityAmount": 0,
       "leadStatus":"Rejected",
       "rejectedReasonWhy": " For Another Dealer ",
       "rejectedReasonComments": " Incorrectly routed to our dealership",
       "currencyIsoCode":"USD",
       “comments”: null
    }
]

Sample POST body for Scenario: Lead Status = Accepted

 [
   {
     "leadId": "00Q1W00001SmV5oUAF",
     "dealerLeadId": "A123VSDFDFF",
     “customerPreviouslyKnown”: “Yes”,
     “customerContacted”: “Yes”,
     “dateContacted”: “2020-04-19”
     "dealerCustomerNumber ": "123433",
     "dealerSalesRep":"JOHN DOE",
     "leadStatus": "Accepted",
     "currencyIsoCode ":"CNY"
   }
]

Sample POST body for Scenario: Lead Status = Disqualified and Customer was contacted

 [
   {
     "leadId": "00Q1W00001SmV5oUAF",
     "dealerLeadId": "A123VSDFDFF",
     “customerPreviouslyKnown”: “Yes”,
     “customerContacted”: true,
     “dateContacted”: ”2020-04-19”
     "dealerCustomerNumber ": "123433",
     "dealerSalesRep":"JOHN DOE",
     "leadStatus": "Disqualified",
     “disqualifiedReasonWhy” : “No budget”,
     "currencyIsoCode ":"CNY"
   }
]

OR

[
   {
       "leadId": "00Q1W00001SmV5oUAF",
       "dealerLeadId": "A123VSDFDFF",
       “customerPreviouslyKnown”: “Yes”,
       “customerContacted”: “No”,
       "dealerCustomerNumber ": "123433",
       “dealerOpportunityId”: null,
       "targetDate":null,
       "probabilityOfClosurePercentage":null,
       "rating":null,
       "dealerSalesRep":"JOHN DOE",
       "opportunityAmount": 0,
       "leadStatus":"Disqualified",
       "currencyIsoCode":"USD",
       “disqualifiedReasonWhy”: “No budget”,
       “comments”: null
    }
]

Sample POST body for Scenario: Lead Status = Disqualified and disqualifiedReasonWhy is Other or End-user, end-use or end-destination may be restricted or Lead Already Known”

[
   {
     "leadId": "00Q1W00001SmV5oUAF",
     "dealerLeadId": "A123VSDFDFF",
     “customerPreviouslyKnown”: “Yes”,
     “customerContacted”: true,
     “dateContacted”: ”2020-04-19”
     "dealerCustomerNumber ": "123433",
     "dealerSalesRep":"JOHN DOE",
     "leadStatus": "Disqualified",
     “disqualifiedReasonWhy” : “Other”,
     “disqualifiedReasonComments” : “After discussing with customer requirements couldn’t be met”,
     "currencyIsoCode ":"CNY"
   }
]

Sample POST body for Scenario: Opportunity Stages = Qualification

[
    { 
       "leadId": "00Q1W00001SmV5oUAF",
       "dealerLeadId": "A123VSDFDFF",
       “dealerOpportunityId”: “B23445232ASSDDV”,
       “customerPreviouslyKnown”: “Yes”,
       “customerContacted”: “No”,
       "dealerCustomerNumber ": "123433",
       "targetDate": “2021-09-23”,
       "probabilityOfClosurePercentage":10,
       "rating":"Low",
       "dealerSalesRep":"JOHN DOE",
       "opportunityAmount":1999.45,
       "leadStatus":" Accepted ",
       "currencyIsoCode":"USD"
      }
]

Sample POST body for Scenario: Opportunity Stages = Develop Solution

[
    { 
       "leadId": "00Q1W00001SmV5oUAF",
       "dealerLeadId": "A123VSDFDFF",
       “dealerOpportunityId”: “B23445232ASSDDV”,
       “customerPreviouslyKnown”: “Yes”,
       “customerContacted”: “No”,
       "dealerCustomerNumber ": "123433",
       "targetDate": “2021-09-23”,
       "probabilityOfClosurePercentage":35,
       "rating":"Medium",
       "dealerSalesRep":"JOHN DOE",
       "opportunityAmount":1999.45,
       "leadStatus":" Accepted ",
       "currencyIsoCode":"USD"
      }
]

Sample POST body for Scenario: Opportunity Stages = Proposal/Negotiation

[
    { 
       "leadId": "00Q1W00001SmV5oUAF",
       "dealerLeadId": "A123VSDFDFF",
       “dealerOpportunityId”: “B23445232ASSDDV”,
       “customerPreviouslyKnown”: “Yes”,
       “customerContacted”: “No”,
       "dealerCustomerNumber ": "123433",
       "targetDate": “2021-09-23”,
       "probabilityOfClosurePercentage":70,
       "rating":"High",
       "dealerSalesRep":"JOHN DOE",
       "opportunityAmount":1999.45,
       "leadStatus":" Accepted",
       “quoteSentDate”: “2020-08-18”,
       “quoteId”: “12AS223”,
       "currencyIsoCode":"USD"
      }
]

Sample POST body for Scenario: Opportunity Stage = Closed Won

  [ 
    {  
       "leadId": "00Q1W00001SmV5oUAF",
       "dealerLeadId": "A123VSDFDFF",
       “dealerOpportunityId”: “B23445232ASSDDV”,
       “customerPreviouslyKnown”: “Yes”,
       “customerContacted”: “No”,
       "dealerCustomerNumber ": "123433",
       "targetDate": “2021-09-23”,
       "probabilityOfClosurePercentage":100,
       "rating":"High",
       "dealerSalesRep":"JOHN DOE",
       "opportunityAmount":1999.45,
       "leadStatus":" Accepted",
       “quoteSentDate”: “2020-08-18”,
       “quoteId”: “12AS223”,
       "currencyIsoCode":"USD"
       “primaryClosedReason”: “Warranty Term (Term/Rate/Scope)”,
       “secondayClosedReason”: “Deal was closed with additional discount”,
       “closedReasonComments”: “Customer negotiated for additional discount”
      }
]

Sample POST body for Scenario: Opportunity Stage = Closed No Deal

[ 
    {  
       "leadId": "00Q1W00001SmV5oUAF",
       "dealerLeadId": "A123VSDFDFF",
       “dealerOpportunityId”: “B23445232ASSDDV”,
       “customerPreviouslyKnown”: “Yes”,
       “customerContacted”: “No”,
       "dealerCustomerNumber ": "123433",
       "targetDate": “2021-09-23”,
       "probabilityOfClosurePercentage":0,
       "rating":"low",
       "dealerSalesRep":"JOHN DOE",
       "opportunityAmount":1999.45,
       "leadStatus":" Accepted",
       "currencyIsoCode":"USD"
       “closedNoDeal”: 1,
       “quoteSentDate”: “2020-08-18”,
       “quoteId”: “12AS223”,
       “primaryClosedReason”: “Products/Parts Not in Cat Network”,
       “secondayClosedReason”: “Products were not available within CAT Network since they were discontinued”
      }
]

Sample POST body for Scenario: Opportunity Stage = Closed Lost

 [
     {"
       "leadId": "00Q1W00001SmV5oUAF",
       "dealerLeadId": "A123VSDFDFF",
       “dealerOpportunityId”: “B23445232ASSDDV”,
       “customerPreviouslyKnown”: “Yes”,
       “customerContacted”: “No”,
       "dealerCustomerNumber ": "123433",
       "targetDate": “2019-09-23”,
       "probabilityOfClosurePercentage":0,
       "rating":"low",
       "dealerSalesRep":"JOHN DOE",
       "opportunityAmount":1999.45,
       "leadStatus": " Accepted",
       "currencyIsoCode": "USD"
       “closedNoDeal”: 0,
       “quoteSentDate”: “2020-08-18”,
       “quoteId”: “12AS223”,
       “primaryClosedReason”: “Competitive Financial (Term/Rates/Scope)”,
       “secondayClosedReason”: “None”,
      }
]

The primary key for a Leads is:

leadId

Transmission/Media Type

• Mailbox
• Web service
• LU6.2
• XML
• API
• PC to Client
• Web Download/SIFT
• CD

Testing Procedures

For testing with Caterpillar QA environment:

You must have valid Client ID credentials for QA environment. Contact ECRM team for help.

In addition to System Integration testing, following tests should be completed by the consumer of the API

• Load testing
  • Ability to make consecutive GET calls until all PSEs are ingested and GET call returns 0 leads (Note: Since Lead API GET call will only deliver 100 leads, this capability is required to make sure that dealers can pull all leads if the number of leads exceed 100).
• Dealer error handling
  • Any response code received other than 200 OK or 204 No Content,
    • Retry mechanism should make API call at least 5 times before failing.
    • After Retry failure, it is recommended to trigger an email alert to dealer CRM team to review the error including error details and take necessary actions to fix the error.

Testing Coordination

• Testing can be performed without Caterpillar DICE Team assistance
• Testing requires coordination with the Caterpillar ECRM team

Testing Comments

• Use Postman to test the interface process before deploying more advanced applications using the Partner API.

Who To Contact

For scheduling your testing needs, please contact you assigned Program Manager

Testing will be coordinated by ECRM deployment team

Test Configuration

N/A

Production Information

Production Comment

Production Endpoints:

You must have valid Client ID credentials for PROD environment. Contact ECRM team for help.

Production Configuration

N/A