How to search and create a customer

This document is designed to help you understand how you can first search for existing customers in myKaarma to avoid duplicates, and then create a new customer (along with vehicles and addresses) using a given request body.

To perform these actions, you first need your credentials. If you don't already have them, head over to the Authentication and Authorization page to see how you can request credentials from us. The process of searching for existing customers and, if none are found, creating a new customer is listed below.

Parameters

Required path parameters for process :

Parameter Name	Type	Description
departmentUUID	string	Unique identifier of dealer's department
customerUUID	string	Unique identifier of the customer

Scope

This process requires the following authorization scopes :

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

Process

To efficiently manage customer data and prevent duplicates in myKaarma, API partners should follow these steps:

Search for Customers :

Use the endpoint provided in the search customer documentation to search for existing customers.

Customer Search Guidelines for API Partners

• To effectively search for customers in the myKaarma system using the provided parameters (CustomerKey, VIN, PhoneNumber, or Email), follow these structured steps:

1. Construct the Search Term :

   Use one of the following formats for your searchTerm:

   • complete CustomerKey
   • last 8 characters of VIN
   • 10-digit PhoneNumber
   • Email Address (if phone is not available)

   Example search term:

                    DOM123 6C650709 9891361006 
   
                    DOM123 6C650709 john.doe@gmail.com

2. Execute the Search API Call : Use the following curl command to search for customers:

   example :

    curl -X GET "https://api.mykaarma.com/customer/v2/department/{{serviceSubscriberDealerDepartmentToken}}/customer/listMinimal?fieldsToBeSearched=vehicles.vin,communications.commValue,customerKey&maxResults={{maxResults}}&searchTerm={{searchterm}}&queryOperator=OR" 
    -H "accept: application/json" 
    -H "authorization: {{basic_auth_token}}"

3. Analyze API Response :

   • If you receive results:
     • If only one customer matches the customerKey, use that customer's UUID to update their information . Endpoint details at update customer
     • If multiple results are returned, proceed to the next step.
   • If no results are found, create a new customer using the create customer API Endpoint details at create customer .

4. Handling Multiple Results :

   If multiple customers are found in the response:

   • Check for Matching CustomerKey:
     • If a customer with the same customerKey is found, use their UUID for updates.
   • Check by Last Name and Contact Info:
     • Look for customers with the same last name and either phone number or email from your search term. Use any matching customer. Note only consider customers having null customerKey from the list .
   • Check by Last Name and VIN:
     • If no matches are found in the previous step, check for customers with the same last name and VIN. Optionally consider first names as well. Note only consider customers having null customerKey from the list .

By following this process, we ensure that customer duplicate entries are minimized in myKaarma system.