How to fetch follow ups for a dealer

This endpoint allows you to retrieve follow-ups for a dealer with pagination, filtering, sorting, and grouping capabilities. You can fetch follow-ups in batches using filters such as task type, assignee, follow-up state, and date ranges.

To use this endpoint, you first need your credentials. If you don't already have one, please head over to the Authentication and Authorization page to see how you can request for credentials from us.

Request

HTTP request

POST  https://api.mykaarma.com/leads/followup/dealer/{dealerUUID}/list

Parameters

Required path parameters:

Parameter Name	Value	Description
`dealerUUID`	`string`	Unique identifier for the dealer

Authorization

This request requires authorization. Include your credentials in the authorization header.

Request Body

Property Name	Type	Required	Description
`dealerDepartmentUUID`	`string`	Yes	Unique identifier of the dealer's department
`filterData`	`object`	Yes	Filter criteria for follow-ups. Send an empty object `{}` to fetch without filters
`customerUUID`	`string`	No	Fetch follow-ups only for this customer
`fromInsertDate`	`string`	No	Start of the insert date range (format: `yyyy-MM-dd'T'HH:mm:ssZ`, e.g. `2024-05-01T00:00:00+0000`). Must be sent together with `toInsertDate`
`toInsertDate`	`string`	No	End of the insert date range. Must be sent together with `fromInsertDate`
`fromDueDate`	`string`	No	Start of the due date range. Must be sent together with `toDueDate`
`toDueDate`	`string`	No	End of the due date range. Must be sent together with `fromDueDate`
`fromOptInDate`	`string`	No	Start of the opt-in date range
`toOptInDate`	`string`	No	End of the opt-in date range
`entriesToBeSkipped`	`integer`	No	Number of entries to skip for offset-based pagination (default: 0)
`entriesLimitToBeFetched`	`integer`	No	Maximum number of entries to fetch (default: 50)
`lastFollowUpUUID`	`string`	No	UUID of the last follow-up received in the previous page, for cursor-based pagination. If sent, `followUpPaginationData` is also required
`followUpPaginationData`	`object`	No	Details of the last follow-up received in the previous page. Required when `lastFollowUpUUID` is sent
`filterViewGroupByType`	`string`	No	Groups the results. One of: `CUSTOMER`, `ASSIGNEE`, `DUE_DATE`, `INSERT_DATE`, `TASK_TYPE`
`filterViewSortByType`	`string`	No	Field to sort the results by. One of: `TASK_TYPE`, `CUSTOMER`, `TASK`, `INSERT_DATE`, `DUE_DATE`, `ASSIGNEE` (default: `DUE_DATE`)
`sortOrder`	`string`	No	Sort direction. One of: `ASCENDING`, `DESCENDING` (default: `ASCENDING`)

Filter Data Object

The filterData object is required, but all of its fields are optional. An empty object {} applies no filters.

Property Name	Type	Description
`followUpStatusList`	`array`	Filter by communication status of the follow-up. Values: `SELECT_ALL`, `CALLED`, `NOT_CALLED`, `EMAILED`, `NOT_EMAILED`, `TEXTED`, `NOT_TEXTED`, `WHATSAPPED`, `NOT_WHATSAPPED`
`followUpStateList`	`array`	Filter by the state of the follow-up. Values: `SELECT_ALL`, `NOT_STARTED`, `SCHEDULED`, `COMPLETE`
`assigneesUUIDList`	`array`	Filter by the UUIDs of the users the follow-ups are assigned to
`followUpSourceUUIDList`	`array`	Filter by task type UUIDs (e.g. the UUID of the Declined Services or No Show task type)
`scheduledApptStatusList`	`array`	Filter by appointment scheduling status. Values: `SELECT_ALL`, `SCHEDULED`, `NOT_SCHEDULED`

Follow-up Pagination Data Object

When using cursor-based pagination, send the lastFollowUpUUID along with followUpPaginationData populated from the last follow-up of the previous page.

Property Name	Type	Description
`latestCustomerFName`	`string`	Customer first name of the last follow-up received
`latestCustomerLName`	`string`	Customer last name of the last follow-up received
`latestInsertDate`	`string`	Insert date of the last follow-up received (format: `yyyy-MM-dd'T'HH:mm:ssZ`)
`latestDueDate`	`string`	Due date of the last follow-up received (format: `yyyy-MM-dd'T'HH:mm:ssZ`)
`latestAssigneeFName`	`string`	Assignee first name of the last follow-up received
`latestAssigneeLName`	`string`	Assignee last name of the last follow-up received
`latestTaskType`	`string`	Task type of the last follow-up received
`latestTaskName`	`string`	Task name of the last follow-up received

Sample Request

curl --location 'https://api.mykaarma.com/leads/followup/dealer/{dealerUUID}/list' \
--header 'accept: application/json' \
--header 'authorization: <your-credentials>' \
--header 'Content-Type: application/json' \
--data '{
    "dealerDepartmentUUID": "dealer-department-uuid",
    "entriesToBeSkipped": 0,
    "entriesLimitToBeFetched": 10,
    "filterData": {}
}'

Sample Request - With Filters

curl --location 'https://api.mykaarma.com/leads/followup/dealer/{dealerUUID}/list' \
--header 'accept: application/json' \
--header 'authorization: <your-credentials>' \
--header 'Content-Type: application/json' \
--data '{
    "dealerDepartmentUUID": "dealer-department-uuid",
    "entriesToBeSkipped": 0,
    "entriesLimitToBeFetched": 10,
    "fromDueDate": "2024-05-01T00:00:00+0000",
    "toDueDate": "2024-05-31T23:59:59+0000",
    "filterViewSortByType": "DUE_DATE",
    "sortOrder": "ASCENDING",
    "filterData": {
        "followUpStateList": ["NOT_STARTED"],
        "followUpSourceUUIDList": ["task-type-uuid"]
    }
}'

Pagination

If entriesLimitToBeFetched is not provided, a default limit of 50 is applied
Use entriesToBeSkipped and entriesLimitToBeFetched together for offset-based pagination
For cursor-based pagination, send the lastFollowUpUUID and followUpPaginationData from the last follow-up of the previous page
Fetch follow-ups in batches using filters such as task type to send messages efficiently

Date ranges

from and to dates must always be sent as a pair, and the from date must not be after the to date. Sending only one of them returns a validation error.

Response

{
    "statusCode": 200,
    "error": null,
    "warnings": null,
    "followUpsList": [
        {
            "uuid": "follow-up-uuid",
            "dealerUuid": "dealer-uuid",
            "dealerDepartmentUuid": "department-uuid",
            "customerUuid": "customer-uuid",
            "customerFName": "John",
            "customerLName": "Doe",
            "address": null,
            "phoneNumber": {
                "communicationValue": "**********",
                "commType": "TEXT",
                "optOutStatus": "OPTED_IN",
                "timeOfChange": "2024-07-26T20:29:44.000+00:00",
                "canSendOptinRequest": false
            },
            "emailAddress": {
                "communicationValue": "****************",
                "commType": "EMAIL",
                "optOutStatus": null,
                "timeOfChange": null,
                "canSendOptinRequest": null
            },
            "source": {
                "uuid": "task-type-uuid",
                "dealerUuid": "dealer-uuid",
                "taskName": "Declined Service",
                "taskDisplayName": "Declined Service",
                "taskDescription": "Declined Services Task Type"
            },
            "vehicle": {
                "id": 329048323,
                "uuid": "vehicle-uuid",
                "vehicleKey": null,
                "isValid": true,
                "vin": "1GBHK34K07E528181",
                "make": "Chevrolet",
                "model": "Silverado 3500 HD",
                "year": "2007",
                "lastMileage": null
            },
            "dealerOrder": {
                "dealerOrderUuid": "order-uuid",
                "orderNumber": "202405162",
                "orderType": "RO",
                "orderDate": "2024-05-16 08:00:00.0",
                "createdDate": "2024-05-16 01:31:26.0",
                "closeDate": "2024-05-16 01:32:18.0",
                "orderStatus": "C",
                "invoiceURL": "https://payment-files.mykaarma.com/...",
                "daUuid": null,
                "daFName": null,
                "daLName": null
            },
            "assignee": {
                "uuid": "user-uuid",
                "fname": "Chetan",
                "lname": "Rawat"
            },
            "taskName": "Air Conditioner/Heater Recommendation, Fluid Leak Repair Recommendation",
            "lastVisitedDate": null,
            "declineInfo": {
                "dmsID": 9,
                "hasReturned": null,
                "mpiUUID": "mpi-uuid",
                "declines": [
                    {
                        "declinedServiceID": null,
                        "opcode": null,
                        "opcodeDescription": null,
                        "internalName": "Air Conditioner/Heater Recommendation",
                        "internalDescription": "Air Conditioner Refrigerant Recharge and Leak Test",
                        "displayName": "Air Conditioner/Heater Recommendation",
                        "displayDescription": "Air Conditioner Refrigerant Recharge and Leak Test",
                        "type": "DeclinedRecommendation",
                        "source": "SERVICECART",
                        "recommendationUUID": "recommendation-uuid",
                        "amount": 253.0,
                        "status": null
                    }
                ],
                "mpiLink": "scct.mkvwa42.com/p/lsfkjeorijrdes.html"
            },
            "dueDate": "2024-05-30T18:29:59.000+00:00",
            "insertDate": "2024-05-15T18:30:00.000+00:00",
            "textModeCurrentStatus": null,
            "emailModeCurrentStatus": null,
            "textMessageUuid": null,
            "textMessageFollowupStatus": null,
            "emailMessageUuid": "email-message-uuid",
            "emailMessageFollowupStatus": "Complete",
            "callMessageUuid": null,
            "callMessageFollowupStatus": null,
            "followedUpStatus": "Complete",
            "isValid": true,
            "appointments": null,
            "noShowAppointmentInfo": null
        }
    ]
}

Response Fields

Field	Type	Description
`statusCode`	`integer`	HTTP status code (200 for success)
`error`	`object`	Error details if the request failed
`warnings`	`array`	Warning messages if any
`followUpsList`	`array`	List of follow-up objects

Follow-up Object Key Fields

Field	Type	Description
`uuid`	`string`	Unique identifier of the follow-up task
`dealerUuid`	`string`	Unique identifier of the dealer
`dealerDepartmentUuid`	`string`	Unique identifier of the dealer's department
`customerUuid`	`string`	Unique identifier of the customer for whom the task belongs
`customerFName`	`string`	Customer's first name
`customerLName`	`string`	Customer's last name
`address`	`object`	Customer's address details
`phoneNumber`	`object`	Customer's primary cell details
`emailAddress`	`object`	Customer's primary email details
`source`	`object`	The task type information (e.g., Declined Services, No Show)
`vehicle`	`object`	Vehicle details
`dealerOrder`	`object`	Details of the dealer order if the task is generated from it (present in the case of declined services)
`assignee`	`object`	Details of the user the task is assigned to
`followedupBy`	`object`	Details of the user who completed the follow-up
`taskName`	`string`	Task name
`lastVisitedDate`	`string`	Date of the customer's last visit
`declineInfo`	`object`	Details of the recommendations that are declined by the customer in the MPI
`dueDate`	`string`	Due date of the task (in UTC)
`insertDate`	`string`	Insert date of the task (in UTC)
`textMessageFollowupStatus`	`string`	Status if the follow-up is completed through text
`emailMessageFollowupStatus`	`string`	Status if the follow-up is completed through email
`callMessageFollowupStatus`	`string`	Status if the follow-up is completed through call
`whatsappMessageFollowupStatus`	`string`	Status if the follow-up is completed through WhatsApp
`followedUpStatus`	`string`	Status if the follow-up is completed through any of the modes
`isValid`	`boolean`	Indicates if the follow-up is valid
`appointments`	`array`	List of appointments scheduled for the customer
`noShowAppointmentInfo`	`object`	Information of the appointment through which the no show follow-up was created (only in the case of no show or missed appointment)
`specialOrderInfo`	`object`	Information of the special order part if the task is generated from it (only in the case of special order parts follow-ups)

Error Responses

Validation failures return a 400 status code with an error object describing the problem.

Error	Cause
`MISSING_DEALER_DEPARTMENT_UUID`	`dealerDepartmentUUID` is missing in the request body
`MISSING_FILTER_DATA`	`filterData` is missing in the request body (send `{}` if no filters are needed)
`INVALID_DATE_COMBINATION`	A `from`/`to` date is sent without its pair, or the `from` date is after the `to` date
`MISSING_COMPLETE_PAGINATION_INFO`	`lastFollowUpUUID` is sent without `followUpPaginationData`
`INVALID_REQUEST`	The request body is missing or malformed

Request​

HTTP request​

Parameters​

Authorization​

Request Body​

Filter Data Object​

Follow-up Pagination Data Object​

Sample Request​

Sample Request - With Filters​

Response​

Response Fields​

Follow-up Object Key Fields​

Error Responses​