Skip to main content

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 NameTypeDescription
departmentUUIDstringUnique identifier of dealer's department
customerUUIDstringUnique identifier of the customer

Scope​

This process requires the following authorization scopes :

ScopeLevelDescription
customer.searchDealerDepartmentAuthorizes client to search for customers for provided user's dealer department
customer.updateDealerDepartmentAuthorizes 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.

Evaluate Search Results:

  • If the search returns an empty list, it indicates that no matching customers exist in the system. In this case, you can proceed to create a new customer using the endpoint detailed in the create customer documentation.

  • If the search returns a non-empty list, it suggests that there are potential matches. It is recommended to use the UUID of the best matching customer (typically the first customer in the list) to update their information. This can be done using the endpoint described in the update customer documentation.

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

Customer Search Guidelines for API Partners​

Decision Tree

To effectively search for customers, utilize the search endpoint with the appropriate fieldsToBeSearched parameter based on the available information:

  1. Customer Key :

    If you have the customer's DMS unique key, search using fieldsToBeSearched set to customerKey .

    example : 

    curl -X GET "https://api.mykaarma.com/customer/v2/department/{{serviceSubscriberDealerDepartmentToken}}/customer/listMinimal?fieldsToBeSearched=customerkey&maxResults={{maxResults}}&searchTerm={{searchterm}}" 
    -H "accept: application/json" 
    -H "authorization: {{basic_auth_token}}"

  1. Phone Number or Email :

    For searching by phone number or email (including partial values), set fieldsToBeSearched to communications.commValue.

    example : 

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

  1. Vehicle VIN :

    If you have the Vehicle Identification Number (VIN), search using fieldsToBeSearched set to vehicles.vin .

    example : 

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

  1. Last Name :

    To search by the customer's last name, use fieldsToBeSearched set to lname.

    example : 

    curl -X GET "https://api.mykaarma.com/customer/v2/department/{{serviceSubscriberDealerDepartmentToken}}/customer/listMinimal?fieldsToBeSearched=lname&maxResults={{maxResults}}&searchTerm={{searchterm}}" 
    -H "accept: application/json" 
    -H "authorization: {{basic_auth_token}}"

  1. First Name :

    To search by the customer's first name, use fieldsToBeSearched set to fname.

    example : 

    curl -X GET "https://api.mykaarma.com/customer/v2/department/{{serviceSubscriberDealerDepartmentToken}}/customer/listMinimal?fieldsToBeSearched=fname&maxResults={{maxResults}}&searchTerm={{searchterm}}" 
    -H "accept: application/json" 
    -H "authorization: {{basic_auth_token}}"

  2. First Name and Last Name :

    To search by the customer's first name or last name use fieldsToBeSearched set to fname,lname.

    example : 

    curl -X GET "https://api.mykaarma.com/customer/v2/department/{{serviceSubscriberDealerDepartmentToken}}/customer/listMinimal?fieldsToBeSearched=fname,lname&maxResults={{maxResults}}&searchTerm={{searchterm}}" 
    -H "accept: application/json" 
    -H "authorization: {{basic_auth_token}}"

  1. Search Field Unknown If you do not know the field of search term then the you may not pass the fieldsToBeSearched parameter in the request.

    example : 

     curl -X GET "https://api.mykaarma.com/customer/v2/department/{{serviceSubscriberDealerDepartmentToken}}/customer/listMinimal?maxResults={{maxResults}}&searchTerm={{searchterm}}" 
     -H "accept: application/json" 
     -H "authorization: {{basic_auth_token}}"

NOTE If you do have a valid DMS unique customerKey, and you did not find any matching results in the search by customerKey - you should go ahead and select only the results with empty customerKey from the search response AND create a new Customer if no match is found. This is in accordance to the fact that we do not allow updating of customerKey via Customer Update endpoint.