How to Get Dealer Information

Overview

This guide explains how to retrieve dealer information — including core details, time zone, and physical address — using two myKaarma Manage API endpoints together. To get this data, 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.

---

What is Dealer Information?

A Dealer in myKaarma represents a physical automotive dealership location. Each dealer has core metadata (name, UUID, time zone) and a physical address. These are returned by separate endpoints and are joined using the dealer UUID.

---

API 1 — Dealer List

Retrieves core dealer details for a set of dealer UUIDs, including name, and time zone.

Method: POST URL: https://api.mykaarma.com/manage/v2/dealer/list

---

Required Parameters

Parameter	Type	Purpose	Required
dealerUuids	Set\<String>	The dealer UUIDs for which to fetch information	Yes

---

Authorization

Required scope: manage.dealer.read at the MultiDealer level

---

Example Request

curl -X POST \
  'https://api.mykaarma.com/manage/v2/dealer/list' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic {{base64_credentials}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "dealerUuids": ["dealer-uuid-001", "dealer-uuid-002"]
  }'

---

Response Structure

The API returns a dealers map keyed by dealer UUID. Each value is a dealer object containing full dealer metadata. The response is wrapped in the standard envelope with errors, warnings, and apiRequestId fields.

{
  "errors": [
    {
      "errorCode": 0,
      "errorTitle": "string",
      "errorMessage": "string"
    }
  ],
  "warnings": [
    {
      "warningCode": 0,
      "warningTitle": "string",
      "warningMessage": "string"
    }
  ],
  "apiRequestId": "string",
  "dealers": {
    "dealer-uuid-001": {
      "name": "Sample Chevrolet",
      "uuid": "dealer-uuid-001",
      "timeZone": "US/Central",
      "phoneNumber": "2145551234",
      "phoneCountryCode": "1",
      "emailID": "info@samplechevrolet.com",
      "website": "https://www.samplechevrolet.com",
      "departments": [
        {
          "name": "Service",
          "uuid": "dept-uuid-001"
        }
      ],
      "businessContactFirstName": "John",
      "businessContactLastName": "Smith"
    }
  }
}

Dealer object fields

Field	Type	Description
name	String	Dealer display name
uuid	String	Dealer UUID — used as the map key and to join with the address list
timeZone	String	Dealer local time zone (see Supported Time Zones)
phoneNumber	String	Primary phone number
phoneCountryCode	String	Country dialing code for the phone number
emailID	String	Primary contact email address
website	String	Dealer website URL
departments	Array\<Department>	List of departments belonging to this dealer (see Department object fields)
businessContactFirstName	String	First name of the primary business contact
businessContactLastName	String	Last name of the primary business contact

Department object fields

Field	Type	Description
name	String	Department name (e.g. Service, Sales)
uuid	String	Department UUID

---

Supported Time Zones

The timeZone field uses IANA time zone identifiers. The following values are supported:

Region	Supported values
United States	US/Pacific, US/Mountain, US/Central, US/Eastern, US/Hawaii, US/Alaska, US/Atlantic, US/Arizona
US Territories	America/Puerto_Rico, Pacific/Guam
Middle East / Gulf	Asia/Riyadh, Asia/Dubai, Asia/Kuwait, Asia/Qatar, Asia/Muscat, Asia/Bahrain, Asia/Amman, Asia/Beirut

---

API 2 — Dealer Address List

Retrieves the physical address for a set of dealer UUIDs. Use the same UUIDs from API 1 to join the responses.

Method: POST URL: https://api.mykaarma.com/manage/v2/dealer/address/list

---

Required Parameters

Parameter	Type	Purpose	Required
dealerUuids	Set\<String>	The dealer UUIDs for which to fetch addresses	Yes

---

Authorization

Required scope: manage.dealer.read at the MultiDealer level

---

Example Request

curl -X POST \
  'https://api.mykaarma.com/manage/v2/dealer/address/list' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic {{base64_credentials}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "dealerUuids": ["dealer-uuid-001", "dealer-uuid-002"]
  }'

---

Response Structure

The API returns a dealerAddressMap object keyed by dealer UUID. Each value contains the full address — street, city, state, ZIP, country, phone, and geographic coordinates.

{
  "dealerAddressMap": {
    "dealer-uuid-001": {
      "line1": "123 Main St",
      "line2": "Suite 100",
      "city": "Dallas",
      "zip": "75201",
      "zipExt": "1234",
      "phone": "2145551234",
      "stateCode": "TX",
      "stateDescription": "Texas",
      "countryCode": "US",
      "country": "United States",
      "latitude": 32.7767,
      "longitude": -96.7970,
      "altitude": 131.0
    },
    "dealer-uuid-002": {
      "line1": "456 Ocean Ave",
      "line2": null,
      "city": "San Diego",
      "zip": "92101",
      "zipExt": null,
      "phone": "6195551234",
      "stateCode": "CA",
      "stateDescription": "California",
      "countryCode": "US",
      "country": "United States",
      "latitude": 32.7157,
      "longitude": -117.1611,
      "altitude": null
    }
  },
  "errors": [
    {
      "errorCode": 0,
      "errorTitle": "string",
      "errorMessage": "string"
    }
  ],
  "warnings": [
    {
      "warningCode": 0,
      "warningTitle": "string",
      "warningMessage": "string"
    }
  ],
  "apiRequestId": "string"
}

Address object fields

Field	Type	Description
line1	String	Street address line 1
line2	String	Street address line 2 (optional)
city	String	City name
zip	String	ZIP or postal code
zipExt	String	ZIP+4 extension (optional)
phone	String	Dealership phone number
stateCode	String	State or province code (e.g. TX, CA)
stateDescription	String	Full state or province name
countryCode	String	ISO country code (e.g. US)
country	String	Country name
latitude	Double	Latitude coordinate
longitude	Double	Longitude coordinate
altitude	Float	Altitude in meters (optional)

---

Combining the Two Responses

To build a complete dealer record with both metadata and address:

1. Call POST /manage/v2/dealer/list with your dealerUuids
2. Call POST /manage/v2/dealer/address/list with the same dealerUuids
3. Both responses are maps keyed by dealer UUID — look up the same UUID in each to combine them