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 | False | set of fields like firstName, lastName, ID etc. |
{{maxResults}} | Size of customer list that will be returned. Could be any number from 1 to 100 | False | 100 |
{{queryOperator}} | Combine the search results by searching for the {{searchTerm}} in different {{fieldsToBeSearched}} by AND or OR | False | AND |
{{searchPreference}} | Which entity search is preferred Customer or Vehicle | False | Customer |
{{searchTerm}} | String that will be looked for in the {{fieldsToBeSearched}} and its presence in either all the fields or at least one field controlled by {{queryOperator}} decides whether or not the customer result will be returned in the response list. 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
- The service subscriber needs to have the following scope -
customer.search
Endpoint
curl -X GET "https://api.mykaarma.com/customer/v2/department/{{serviceSubscriberDealerDepartmentToken}}/customer/list?fieldsToBeSearched={{fieldsToBeSearched}}&maxResults={{maxResults}}&queryOperator={{queryOperator}}&searchPreference={{searchPreference}}&searchTerm={{searchterm}}"
-H "accept: application/json"
-H "authorization: {{basic_auth_token}}"
Response
{
"errors": [
{
"errorCode": 0,
"errorMessage": "string",
"errorTitle": "string"
}
],
"matchingCount": 0,
"matchingCustomers": [
{
"customer": {
"addresses": [
{
"addressType": "string",
"city": "string",
"country": "string",
"line1": "string",
"line2": "string",
"position": {
"altitude": 0,
"id": 0,
"latitue": 0,
"longitude": 0
},
"state": "string",
"zip": "string"
}
],
"bestTimeToContact": {
"endTime": "string",
"startTime": "string"
},
"company": "string",
"customerId": "string",
"customerKey": "string",
"customerUuid": "string",
"emails": [
{
"emailAddress": "string",
"isPreferred": true,
"label": "string",
"okToEmail": true
}
],
"firstName": "string",
"id": 0,
"isBusiness": true,
"lastName": "string",
"phoneNumbers": [
{
"isPreferred": true,
"label": "string",
"okToCall": true,
"okToText": true,
"phoneNumber": "string"
}
],
"preferredCommunication": "string",
"preferredLocale": "string"
},
"vehicles": [
{
"brandId": 0,
"estimatedMileage": "string",
"id": 0,
"imageUrl": "string",
"isValid": true,
"vehicleEngine": "string",
"vehicleKey": "string",
"vehicleMake": "string",
"vehicleModel": "string",
"vehicleTrim": "string",
"vehicleUuid": "string",
"vehicleYear": "string",
"vin": "string"
}
]
}
],
"warnings": [
{
"warningCode": 0,
"warningMessage": "string",
"warningTitle": "string"
}
]
}
Quick summary of getCustomer response fields
| Parameter Name | Description |
|---|---|
addresses.addressType | Enum with possible values COMMON, PRIMARY, BILLING, OTHER and tells type of address |
customerId | Unique identifier used by mykaarma to uniquely identify each customer in mykaarma databases |
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. |
customerUuid | Unique identifier used by mykaarma in addition to customerId, used for uniquely identifying customers over API calls(for read, write, update, delete purposes) without revealing their database id that is customerId |
emails.label | It tells the type of email example personal |
phoneNumbers.label | It tells the type of phone example cell, home, work etc. |
isPreferred | 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 |
isBusiness | Boolean value which tells whether the customer is an INDIVIDUAL customer or a BUSINESS customer |
preferredCommunication | String which tells which mode of communication is preferred by the customer to be contacted |
vehicles.id | Unique identifier used by mykaarma to uniquely identify each vehicle in mykaarma databases |
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 |