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

Parameter Name	Description	Required
{{dealerUuid}}	UUID of dealer which service subscriber is saving the leads for	True
{{authorization}}	Authorization: Basic generate using username password	True

Request Body

Request Body object

{
  "customer": {
    "uuid": ""
  },
  "vehicle": {
    "uuid": "",
    "trackingId": "",
    "topic": "",
    "description": ""
  },
  "dealerDetails": {
    "name": "",
    "code": "",
    "source": "MMC"
  },
  "services": [
    {
      "name": "",
      "code": "",
      "type": "",
      "dueDate": ""
    }
  ],
  "campaign": {
    "name": "",
    "code": ""
  },
  "status": "NEW",
  "lastContactDate": "",
  "leadId": "",
  "webId": "",
  "leadType": "RECALL"
}

Quick summary of request body object fields

Parameter Name	Description	Required	Default Value
{{dealerDetails.name}}	Vendor Dealership name.	False	---
{{dealerDetails.code}}	Vendor Dealership code.	False	---
{{dealerDetails.source}}	Source of the lead can be MMC.	True	---
{{customer.uuid}}	UUID of customer(issued by myKaarma) which is associated with the lead	True	---
{{vehicle.uuid}}	UUID of vehicle(issued by myKaarma) of vehicle associated with the lead	True	---
{{vehicle.trackingId}}	Tracking ID of the Vehicle	False	---
{{vehicle.topic}}	Topic associated with the Vehicle	False	---
{{vehicle.description}}	Service description	False	---
{{services}}	List of communication codes/opcodes associated with the lead	True	---
{{services.code}}	code/opcode	True	---
{{services.name}}	code name	False	---
{{services.type}}	service type	False	---
{{services.dueDate}}	service due date in format yyyy-MM-dd	False	---
{{campaign.name}}	name of the campaign applicable	False	---
{{campaign.code}}	campaign code	False	---
{{status}}	Should be set to NEW	True	---
{{lastContactDate}}	Last contacted date for the lead in UTC format yyyy-MM-dd HH:mm:ssZ.	True	---
{{leadId}}	ID associated with the lead	False	---
{{webId}}	Web ID associated with the lead	False	---
{{leadType}}	the type of lead which will b saved in mykaarma . Currently we only support RECALL, SERVICE_DEMAND	True	---

Scope

Scope Name	Scope Level
lead.write	Dealer Level

Endpoint

curl -X POST "https://api.mykaarma.com/leads/v2/dealer/{{dealerUuid}}" 
-H "accept: application/json" 
-H "authorization: Basic {{authorization}}" 
-H "Content-Type: application/json" 
--d '{
    "customer": {
        "uuid": "{{test_customer_uuid}}"
    },
    "vehicle": {
        "uuid": "{{test_vehicle_uuid}}",
        "trackingId": "2-I509U2C",
        "topic": "WITH_CONTRACT",
        "description": "Maintenance management with accepted user agreements"
    },
    "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": "2023-06-01"
        }
    ],
    "campaign": {
        "name": "MBVANS",
        "code": "A"
    },
    "status": "NEW",
    "lastContactDate": "2023-06-08 11:00:00Z",
    "leadId": "US000000111199002",
    "webId": "2-39484871796",
    "leadType": "RECALL"
}'

Response

Response Object (http status code other than 4XX)

{
  "error": 
    {
      "errorCode": "string",
      "errorDescription": "string",
      "errorUID": "string"
    }
  ,
  "isNewCreated": "boolean",
  "prospectUuid": "string"
  "statusCode": 0,
  "warnings": [
    {
      "warningCode": "string",
      "warningDescription": "string"
    }
  ]
}

Response Object (http status code 4XX)

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

Response Object Explanation

{{prospectUuid}} uuid of the lead which was created/updated . {{isNewCreated}} which tells whether the lead is a newly created lead or an existing one