How to save a lead

This document is designed to help you understand how you can save a lead in myKaarma. To use this endpoint, you first need your credentials. If you don't already have one, head over to the Authentication and Authorization page to see how you can request credentials from us.

Parameters Used

Path parameters

Parameter Name	Description	Required
`{{dealerUuid}}`	Unique token issues by the myKaarma for the dealership for which leads is being saved.	True

Authorization

Parameter Name	Description	Required
`{{basic_auth_token}}`	Authorization: Base64 encoded string using Service Subscriber Username and password	Yes

Scope

Scope Name	Scope Level
`lead.write`	`Dealer Level`

Request Body

Request Body object

{
  "customer": {
    "uuid": "",
    "customerKey": "",  
    "firstName": "",  
    "lastName": "",  
    "company": "",  
    "isBusiness": false,  
    "addresses": [  
      {  
        "line1": "",  
        "line2": "",  
        "city": "",  
        "zip": "",  
        "addressType": "P",  
        "type": "Enum[COMMON, PRIMARY, BILLING]",  
        "country": "",  
        "isValid": true,  
        "isPreferred": true,  
        "state": ""  
      }  
    ],  
    "preferredLocale": "en-us",  
    "emails": [  
      {  
        "emailAddress": "",  
        "label": "",  
        "okToEmail": true,  
        "isPreferred": true  
      }  
    ],  
    "phoneNumbers": [  
      {  
        "phoneNumber": "",  
        "label": "",  
        "okToCall": true,  
        "okToText": true,  
        "isPreferred": true  
      } 
    ]
  },
  "vehicle": {
    "uuid": "",
    "trackingId": "",
    "topic": "",
    "description": "",
    "vin": "",  
    "vehicleYear": "",  
    "vehicleMake": "",  
    "vehicleModel": "",  
    "estimatedMileage": "",  
    "vehicleKey": "",  
    "vehicleTrim": "",  
    "licensePlate": "",  
    "color": "",  
    "vehicleEngine": ""
  },
  "dealerDetails": {
    "name": "",
    "code": "",
    "source": "MMC"
  },
  "services": [
    {
      "name": "",
      "code": "",
      "type": "",
      "dueDate": ""
    }
  ],
  "status": "NEW",
  "lastContactDate": "",
  "leadId": "",
  "leadType": "RECALL"
}

Quick summary of request body object fields

This payload consists of myKaarma Customer object with Vehicles associated with it. You can find the field references for Customer and Vehicle in respective links. Rest of the fields are explained below:

Parameter Name	Description	Required	Default Value
`dealerDetails.name`	Name of the dealership for which lead is associated	No	---
`dealerDetails.code`	Code issued by the OEM	No	---
`dealerDetails.source`	The source of the lead, which can be either `MMC` or `BMW_SPARC`	Yes	---
`customer.uuid`	UUID of customer(issued by myKaarma) which is associated with the lead	No	---
`vehicle.uuid`	UUID of vehicle(issued by myKaarma) of vehicle associated with the lead	No	---
`vehicle.trackingId`	Tracking ID of the Vehicle	No	---
`vehicle.topic`	Topic associated with the Vehicle	No	---
`vehicle.description`	Service description	No	---
`services`	List of communication codes/opcodes associated with the lead	Yes	---
`services.code`	The specific code or opcode for the service	Yes	---
`services.name`	The name associated with the service code	Yes	---
`services.type`	The type of service being provided	No	---
`services.dueDate`	The due date for the service, formatted as `yyyy-MM-dd`	No	---
`status`	Should be set to NEW	Yes	New
`lastContactDate`	Last contacted date for the lead in UTC format `yyyy-MM-dd HH:mm:ssZ`. Pass in current date if the caller is not sure about the field	Yes	---
`leadId`	The unique ID associated with the lead present in the third-party system (vendor)	No	---
`leadType`	The type of lead being saved in myKaarma, currently supporting `RECALL` or `SERVICE_DEMAND`	Yes	---

Endpoint

curl -X POST "https://api.mykaarma.com/leads/v3/dealers/{{dealerUuid}}/leads" 
-H "accept: application/json" 
-H "authorization: Basic {{basic_auth_token}}" 
-H "Content-Type: application/json" 
--d '{
    "customer": {
        "uuid": "{{test_customer_uuid}}",
        "customerKey": "{{test_customer_key}}",  
        "firstName": "{{test_customer_first_name}}",  
        "lastName": "{{test_customer_last_name}}",  
        "company": "",  
        "isBusiness": true,  
        "addresses": [  
          {  
            "line1": "{{test_address_line1}}",  
            "line2": "",  
            "city": "{{test_address_city}}",  
            "zip": "{{test_address_zip}}",  
            "addressType": "P",  
            "type": "PRIMARY",  
            "country": "{{test_address_country}}",  
            "isValid": true,  
            "isPreferred": true,  
            "state": "{{test_address_state}}"  
          }  
        ],  
        "preferredLocale": "en-us",    
        "emails": [  
          {  
            "emailAddress": "{{test_customer_email}}",  
            "label": "{{test_email_label}}",  
            "okToEmail": true,  
            "isPreferred": true  
          }  
        ],  
        "phoneNumbers": [  
          {  
            "phoneNumber": "{{test_customer_phone_number}}",  
            "label": "{{test_phone_label}}",  
            "okToCall": true,  
            "okToText": true,  
            "isPreferred": true  
          }  
        ]
    },
    "vehicle": {
        "uuid": "{{test_vehicle_uuid}}",
        "trackingId": "2-I509U2C",
        "topic": "WITH_CONTRACT",
        "description": "Maintenance management with accepted user agreements",
        "vin": "{{test_vehicle_vin}}",  
        "vehicleYear": "{{test_vehicle_year}}",  
        "vehicleMake": "{{test_vehicle_make}}",  
        "vehicleModel": "{{test_vehicle_model}}",  
        "estimatedMileage": "{{test_vehicle_mileage}}",  
        "vehicleKey": "{{test_vehicle_key}}",  
        "vehicleTrim": "{{test_vehicle_trim}}",  
        "licensePlate": "{{test_vehicle_license}}",  
        "color": "{{test_vehicle_color}}",  
        "vehicleEngine": "{{test_vehicle_engine}}"
    },
    "dealerDetails": {
        "name": "Test Imports LLC",
        "code": "{{test_dealer_code}}",
        "source": "MMC"
    },
    "services": [
        {
            "name": "MBVANS - AS - CC - Maintenance - Service A",
            "code": "MBVANS - AS - CC - Maintenance - Service A",
            "type": "business",
            "dueDate": "2025-06-01"
        }
    ],
    "status": "NEW",
    "lastContactDate": "2024-06-08 11:00:00Z",
    "leadId": "US000000111199002",
    "leadType": "RECALL"
}'

Response

Response Object (http status code other than 4XX)

{
  "error": 
    {
      "errorCode": "",
      "errorDescription": "",
      "errorUID": ""
    }
  ,
  "requestId": "",
  "message": "QUEUED",
  "status": "Success",
  "statusCode": 0,
  "warnings": [
    {
      "warningCode": "",
      "warningDescription": ""
    }
  ]
}

Response Object (http status code 4XX)

{
    "timestamp": "yyyy-MM-ddTHH:mm:ss.SSSZ",
    "status": 400,
    "error": "Bad Request",
    "message": "",
    "path": ""
}

Response Object Explanation

{{requestId}} request id of the lead which is going to be created or updated; this is not the actual lead's pointer in myKaarma - this is just the pointer to the request that was sent - lead will be saved asynchronously in myKaarma's backend.

{{message}} which tells whether the lead is QUEUED or UNPROCESSED

{{status}} which tells whether the lead was successfully received by myKaarma or not

Decision tree

Lead Creation Logic

Customer Matching Logic Find Here.

Parameters Used​

Path parameters​

Authorization​

Scope​

Request Body​

Request Body object​

Quick summary of request body object fields​

Endpoint​

Response​

Response Object (http status code other than 4XX)​

Response Object (http status code 4XX)​

Response Object Explanation​

Decision tree​