How to create or update a customer (search for duplicates)

For saving a customer using mykaarma's deduplication logic, this document explains how to create or update a customer without performing a client-side search. This is the recommended approach for appointment creation and most integration workflows. By setting the searchForDuplicate parameter to true in the request body (the default value is false), the system automatically searches for an existing customer using the Customer Matching Logic. If a matching customer is found, the existing customer record will be updated. If no matching customer is found, a new customer record will be created.

To create a customer , 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 for credentials from us. The following endpoint allows you to create a customer and customize the request body as needed. :-

Parameters

Path parameters

Parameter Name	Value	Description	Required
departmentUUID	String	Unique identifier of dealer department	Yes

Authorization

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

Scope

This request requires the following authorization scopes:

Scope	Level	Description
customer.update	DealerDepartment	Authorizes client to create customer for provided user's dealer department

Endpoint

curl -X POST "https://api.mykaarma.com/customer/v2/department/{{departmentUUID}}/customer"
-H "Authorization: {{basic_auth_token}}"
-H "Content-Type: application/json"
-d '{
  "customer": {
    "customerKey": "string",
    "firstName": "string",
    "lastName": "string",
    "company": "string",
    "isBusiness": true,
    "addresses": [
      {
        "line1": "string",
        "line2": "string",
        "city": "string",
        "zip": "string",
        "addressType": "string",
        "type": "Enum",
        "country": "string",
        "isValid": true,
        "isPreferred": true,
        "state": "string"
      }
    ],
    "preferredLocale": "string",
    "customerUuid": "string",
    "emails": [
      {
        "emailAddress": "string",
        "label": "string",
        "okToEmail": true,
        "isPreferred": true
      }
    ],
    "phoneNumbers": [
      {
        "phoneNumber": "string",
        "label": "string",
        "okToCall": true,
        "okToText": true,
        "isPreferred": true
      }
    ]
  },
  "vehicles": [
    {
      "vin": "string",
      "vehicleYear": "string",
      "vehicleMake": "string",
      "vehicleModel": "string",
      "estimatedMileage": "string",
      "vehicleKey": "string",
      "vehicleTrim": "string",
      "licensePlate": "string",
      "color": "string",
      "vehicleUuid": "string",
      "vehicleEngine": "string",
      "isValid": true
    }
  ],
  "validateVin": true,
  "searchForDuplicate": true
}'

Response

{
  "errors": [
    {
      "errorCode": 0,
      "errorTitle": "string",
      "errorMessage": "string"
    }
  ],
  "warnings": [
    {
      "warningCode": 0,
      "warningTitle": "string",
      "warningMessage": "string"
    }
  ],
  "customerUuid": "string",
  "customerId": "string"
}

Request Body

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.

Response Object Explanation

{{customerUuid}} uuid of the customer which was created/updated .

{{errors}} An array of error objects detailing issues encountered during customer creation or update.

{{warnings}} An array of warning objects providing non-critical alerts encountered during customer creation or update.

{{errors.errorCode}} Code indicating the specific error encountered during customer creation or update; refer to the API reference for a list of possible error codes.

{{errors.errorTitle}} Title describing the specific error encountered during customer creation or update; refer to the API reference for detailed descriptions.

{{errors.errorMessage}} Detailed message describing the specific error encountered during customer creation or update; refer to the API reference for more information.