How to get the list of DealerAssociates in a department

This document is designed to help you understand how to retrieve the list of active DealerAssociates in a department, one page at a time. 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. Use the endpoint below to fetch a paginated list of active DealerAssociates for a given Department UUID. Each DealerAssociate is returned with minimal details: identifiers, name, email address and role.

Request

HTTP request

GET  https://api.mykaarma.com/manage/v2/department/{departmentUUID}/dealerAssociate/list?page={page}&resultSize={resultSize}

Parameters

Path parameter:

Parameter Name	Value	Description	Required
departmentUUID	String	Unique identifier of department	Yes

Query parameters:

Parameter Name	Value	Description	Required
page	Integer	Zero-based page number. Defaults to 0	No
resultSize	Integer	Number of DealerAssociates per page. Defaults to 25. Values above 100 are capped at 100	No

Authorization

This request requires the following authorization scopes:

Scope	Level	Description
manage.dealerassociate.minimal.read	Department	Authorises client to read minimal dealerassociate data for the department

Curl

curl -X 'GET' \
  'https://api.mykaarma.com/manage/v2/department/{departmentUUID}/dealerAssociate/list?page=0&resultSize=25' \
  -H 'accept: application/json' \
  -H 'Authorization: {{basic_auth_token}}'

This endpoint does not take a request body.

Pagination

• Only active DealerAssociates are returned. Inactive DealerAssociates are not included in the list or in totalElements.
• Results are returned in a fixed order, so the same page and resultSize return the same DealerAssociates across requests, as long as the department's DealerAssociates have not changed.
• To fetch all DealerAssociates, start with page=0 and keep incrementing page until it reaches totalPages.
• If resultSize is above 100, the response uses 100, and the resultSize field in the response shows 100.
• A page beyond the last page returns an empty dealerAssociates list.

Response

{
  "errors": [
    {
      "errorCode": 0,
      "errorTitle": "string",
      "errorMessage": "string"
    }
  ],
  "warnings": [
    {
      "warningCode": 0,
      "warningTitle": "string",
      "warningMessage": "string"
    }
  ],
  "apiRequestId": "string",
  "departmentUuid": "string",
  "page": 0,
  "resultSize": 0,
  "totalElements": 0,
  "totalPages": 0,
  "dealerAssociates": [
    {
      "uuid": "string",
      "userUuid": "string",
      "firstName": "string",
      "lastName": "string",
      "emailAddress": "string",
      "role": {
        "roleName": "string",
        "roleAcronym": "string"
      },
      "isValid": true
    }
  ]
}

Sample Response

Success

{
  "errors": [],
  "warnings": [],
  "apiRequestId": "b20f3c992ede64c934c28ddedf36655c",
  "departmentUuid": "69cda869306bb35ecb6c1fed25df6d3da63bd80d0ddc273ed2edc58576a96e04",
  "page": 0,
  "resultSize": 25,
  "totalElements": 2,
  "totalPages": 1,
  "dealerAssociates": [
    {
      "uuid": "9a3de39733b1f37273de6c6cc10bd4c7",
      "userUuid": "39025afdde045dc8b34d910ada652afb",
      "firstName": "John",
      "lastName": "Doe",
      "emailAddress": "john.doe@example.com",
      "role": {
        "roleName": "Service Advisor",
        "roleAcronym": "SA"
      },
      "isValid": true
    },
    {
      "uuid": "68bf1cdba314966e36a320ae5460818d",
      "userUuid": "546ff8031692d4c08cfdd4b9c71f5c36",
      "firstName": "Jane",
      "lastName": "Smith",
      "emailAddress": "jane.smith@example.com",
      "role": {
        "roleName": "Service Manager",
        "roleAcronym": "SM"
      },
      "isValid": true
    }
  ]
}

Response Object Explanation

Field	Type	Description
departmentUuid	String	Unique identifier of the department, as passed in the request
page	Integer	Zero-based page number of this response
resultSize	Integer	Page size used for this response, after capping at 100
totalElements	Long	Total number of active DealerAssociates in the department. null if the request had an invalid page or resultSize
totalPages	Integer	Total number of pages for the given resultSize. null if the request had an invalid page or resultSize
dealerAssociates	List<DealerAssociate>	DealerAssociates on this page. null if the request had an invalid page or resultSize
dealerAssociates.uuid	String	Unique identifier of the DealerAssociate
dealerAssociates.userUuid	String	Unique identifier of the user linked to the DealerAssociate
dealerAssociates.firstName	String	First name of the DealerAssociate
dealerAssociates.lastName	String	Last name of the DealerAssociate
dealerAssociates.emailAddress	String	Email address of the DealerAssociate
dealerAssociates.role.roleName	String	Name of the DealerAssociate's role
dealerAssociates.role.roleAcronym	String	Short form of the DealerAssociate's role
dealerAssociates.isValid	Boolean	Whether the DealerAssociate is active. Always true for this endpoint
errors	List<Error>	Error details, if the request failed
warnings	List<Warning>	Warning details, if any
apiRequestId	String	Unique identifier of the request

Errors

HTTP Status	Error Code	Error Title	When
200	100175	INVALID_PAGE_NUMBER	page is negative
200	100248	INVALID_PAGE_SIZE	resultSize is less than 1
401			Credentials are missing or invalid
403	100004	REQUEST_NOT_AUTHORIZED	Credentials do not have the manage.dealerassociate.minimal.read scope for this department
403	100017	INVALID_DEPARTMENT_TOKEN	No department exists with the given departmentUUID
403	100038	INVALID_REQUEST_DEALER_INVALID	The department's dealer is inactive

Important Note

• Invalid page and resultSize values return HTTP 200 with the error in errors. Always check errors before reading dealerAssociates.