How to get a list of Customers

This document is designed to help you understand how you can fetch a list of Customers with search parameters customizations. The endpoint enables user to get a list of customers that contains a particular string ({{searchTerm}}) in multiple fields({{fieldsToBeSearched}}) like ID, firstName, communications etc. and one can control to combine the results from the searchTerm being present in different fieldsToBeSearched by AND or OR. The list contains an array of objects which contains a sub-object named customer which contains all the customer information and a sub-object named vehicles which contains all the vehicles owned by the customer.
To get a customer list, 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 endpoint mentioned below can help you with getting a customer list and customize the search parameters :-

Parameters Used

Parameter Name	Description	Required	Default Value
{{fieldsToBeSearched}}	Fields in which {{searchTerm}} will be searched for and matching customers will be fetched . set of fields are fname, lname, company, customerKey, communications.commValue,vehicles.vin .Mutiple values must be passed as comma separated example : fname,lname,vehicles.vin	False	---
{{maxResults}}	Size of customer list that will be returned. Could be any number from 1 to 100	False	100
{{searchTerm}}	String that will be looked for in the {{fieldsToBeSearched}} and its presence in all the fields. Maximum length of this search term is 30	True	---
{{serviceSubscriberDepartmentToken}}	UUID of service subscriber	True	---
{{basic_auth_token}}	Authorization: Basic generate using username password	True	---

Scope

1. The service subscriber needs to have the following scope - customer.search

Endpoint

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

Response

{
  "errors": [
    {
      "errorCode": 0,
      "errorTitle": "string",
      "errorMessage": "string"
    }
  ],
  "warnings": [
    {
      "warningCode": 0,
      "warningTitle": "string",
      "warningMessage": "string"
    }
  ],
  "matchingCustomers": [
    {
      "id": 0,
      "fname": "string",
      "lname": "string",
      "customerKey": "string",
      "uuid": "string",
      "company": "string",
      "dealerId": 0,
      "communications": [
        {
          "commValue": "string",
          "commType": "string",
          "commLabel": "string",
          "preferred": true,
          "id": 0
        }
      ],
      "vehicles": [
        {
          "model": "string",
          "year": "string",
          "make": "string",
          "engine": "string",
          "bodyStyle": "string",
          "trim": "string",
          "vin": "string",
          "id": 0,
          "isValid": true,
          "uuid": "string",
          "vehicleKey": "string",
          "imageUrl": "string"
        }
      ],
      "secondaryCustomerData": [
        {
          "fname": "string",
          "lname": "string",
          "customerKey": "string",
          "guid": "string",
          "customerId": 0
        }
      ]
    }
  ]
}

Quick summary of getCustomer response fields

Parameter Name	Description
id	Unique identifier used by mykaarma to uniquely identify each customer in mykaarma databases. This value should not be used by and vendor and in near future would always be null
fname	firstName of the customer
lname	lastName of the customer
customerKey	Unique identifier used by DMS to uniquely identify each customer, used by mykaarma to lookup customers in DMS databases for various purposes like updation, deletion, booking appointment etc.
uuid	Unique identifier used by mykaarma in addition to id, used for uniquely identifying customers over API calls(for read, write, update, delete purposes) without revealing their database id that is customerId
company	company name of the customer provided if the customer is a BUSINESS customer
dealerId	Unique identifier used by mykaarma to uniquely identify each dealer in mykaarma databases This value should not be used by and vendor and in near future would always be null
communications.commValue	The value of customer communciation can be a phone number or an email address
communications.commLabel	It tells the type of phone or email example cell, home, work etc.
communications.preferred	It is a boolean value which tells which phone and which email is preferred for use by a customer, only one phone and one email can have isPreferred true for a customer
communications.id	Unique identifier used by mykaarma to uniquely identify each customer communication in mykaarma databases. This value should not be used by and vendor and in near future would always be null
communications.commType	describes the type of communciation P for Phone and E for email
vehicles.id	Unique identifier used by mykaarma to uniquely identify each vehicle in mykaarma databases. This value should not be used by and vendor and in near future would always be null
vehicles.vehicleKey	Unique identifier used by DMS to uniquely identify each vehicle, used by mykaarma to lookup vehicles in DMS databases for various purposes like updation, deletion, booking appointment etc.
vehicles.vehicleUuid	Unique identifier used by mykaarma in addition to vehicles.id, used for uniquely identifying vehicles over API calls(for read, write, update, delete purposes) without revealing their database id that is vehicles.id
vehicles.year	the year when the vehicle was manufactured
vehicles.make	the brand of the vehicle
vehicles.engine	engine description of the vehicle
vehicles.trim	trim description of the vehicle
vehicles.model	model of the vehicle
vehicles.vin	VIN of the vehicle
vehicles.isValid	Indicates whether the customer currently owns the vehicle.
secondaryCustomerData	Field used internally by mykaarma . Not to be used by any vendor.