Activities (2.2.5)

Introduction

The activities API can be used to send and retrieve CRM activities to the DMS.

Definitions

An activity is a task (something to take action on and only has a start date) or an event (happened in the past, has a start and end date) captured against a customer in the DMS.

HTTP header parameters

  • x-onbehalf-of
    The user (id) of the user who is actually using this resource. This user Id should be known in the receiving system. This user ID will be used in the backend system for auditing reasons.

  • correlation-id
    A unique identifier value (GUID) that is attached to requests and messages that allow reference to a particular transaction or event chain. This ID might be required in case a support case is logged.

Changes in this version:

[2.2.5]

  • Added specificationOfInterest model for GET and POST sales activities response

[2.2.4]

  • Added specificationOfInterest model for SalesActivityCreateRequest

[2.2.3]

  • Removed swaggerhub urls

[2.2.2]

  • Server URLs changed to Keyloop
  • Added 'WALK_IN', 'MANUFACTURER_LEAD' to Origin

[2.2.1]

  • Change to Keyloop
  • Updated mail address
  • Remove reference to vehicle-data in vehicle/makeId

[2.2.0]

  • Added 'campaign' details
  • Added 'previousActivityId'
  • Added new GET 'related-activities' endpoint

[2.1.0]

  • Add Sales activity search endpoint
  • Added 'duration' as a new field
  • Added new types 'CUSTOMER_CONTACT', 'GENERAL_SALES_ACTIVITY', 'OTHER'

[2.0.0]

  • Redesign of activities API
  • Removed LEAD related dmsLink (Use LEADS API instead), use 'CustomerId' only
  • Added oAuth for activity apis.
  • Allow split in Sales and Aftersales activities

Activities

Activity methods

Get activity types

Endpoint to retrieve the available activity types for a certain activity group

Authorizations:
OAuth2
query Parameters
activityGroup
required
string (Activity group code)
Value: "SALESACTIVITIES"
Example: activityGroup=SALESACTIVITIES

Specifies the activity group for which the activity types should be retrieved

  • SALESACTIVITIES - Available activity types for the Sales activity group

Responses

Response samples

Content type
application/json
{
  • "activityGroup": "SALESACTIVITIES",
  • "activityTypes": [
    ]
}

Sales activity actions

Sales activity action methods

Create Sales Activity

Endpoint to create a new sales activity for an existing customer or contact record.

Authorizations:
OAuth2
header Parameters
x-on-behalf-of
string

The user (id) of the user who is actually using this resource. This user Id should be known in the receiving system.

Request Body schema: application/json

Create sales activity request

object (Activity classification object)

Object for the classification of the activity.

origin
string or null (Origin)
Enum: "CUSTOMER" "CALL_CENTRE" "CAMPAIGN" "EMAIL" "EXHIBITION" "POS" "RECOMMENDATION" "PHONE" "SOCIAL_MEDIA" "SHOWROOM" "WEBSITE" "OTHER" "WALK_IN" "MANUFACTURER_LEAD"

Origin of the activity.

notes
string (Activity notes)

Notes relating to the activity describing the activity content are actions to take on this.

startDateTime
required
string <date-time> (Activity start date and timestamp)

Activity start timestamp (UTC Time in ISO-8601 Format)

endDateTime
string or null <date-time> (Activity end date and timestamp)

Activity end timestamp (UTC Time in ISO-8601 Format) Used only in case of an activity that happened in the past and is closed (ie. an event)

duration
integer <int32> (Activity duration (minutes))

Activity duration (in minutes)

previousActivityId
string (Previous Activity Id)

The previousActivityId is used to identify if an activity has been followed-up. It is intended to define the relation between the two activities. A new activity chain will be created when this value is not supplied.

customerId
required
string (Customer Id)

Resource that is linked from DMS

object (Vehicle object)

This object is optional and is only used when the DMS supports vehicle links relating to an activity.

object (Specification Of Interest)

This object is optional and is only used when the DMS supports vehicle links relating to an activity. Specification of interest( Or vehicle of Interest) is the addition/visibility of a vehicle of interest that can be associated to each new sales activity thread/chain from EnquiryMax to activityAPI and in turn downstream DMS.

object (Assigned to DMS user)

The user (id) assigned to this activitye. This user Id should be known in the receiving system.

object (Campaign details)

Campaign details for this activity

object (ExternalReference)

External reference ID for this activity

Responses

Request samples

Content type
application/json
{
  • "classification": {
    },
  • "origin": "CUSTOMER",
  • "notes": "Customer has made an enquiry relating to a offer, get back in touch after a week.",
  • "startDateTime": "2019-02-20T12:34:01.194Z",
  • "endDateTime": "2019-02-20T12:52:08.232Z",
  • "duration": 60,
  • "previousActivityId": "e17179d7-5697-4693-8d36-bb1def8c7c89",
  • "customerId": "781aa0d6-a540-4e4d-a121-2997bcb0b9bd",
  • "vehicle": {
    },
  • "specificationOfInterest": {
    },
  • "assignedTo": {
    },
  • "campaign": {
    },
  • "externalReference": {}
}

Response samples

Content type
application/json
{
  • "activity": {
    },
  • "links": {
    }
}

Sales activity queries

Sales activity query methods

Search Sales Activity

Endpoint to search for sales activities using the fiter cirteria specified witin the query parameters - at least one search parameter must be specified.

Authorizations:
OAuth2
query Parameters
customerId
string
assignedToId
string
fromStartDateTime
string <date>
toStartDateTime
string <date>
page
integer >= 1
Default: 1
Examples:
  • page=1 - Example of for page query parameter
  • page=10 - Example of for page query parameter

A non-zero integer representing the page of the results

pageSize
integer >= 50
Default: 50
Examples:
  • pageSize=50 - Example of for pageSize query parameter
  • pageSize=500 - Example of for pageSize query parameter

A non-negative, non-zero integer indicating the maximum number of results to return at one time

Responses

Response samples

Content type
application/json
{
  • "salesActivities": [
    ],
  • "totalItems": 4,
  • "totalPages": 1,
  • "links": {
    }
}

Get sales activity by ID

Endpoint to retrieve the details of the activity identified from the /sales-activities endpoint

Authorizations:
OAuth2
path Parameters
activityId
required
string

A unique id that identifes an individual activity resource.

Responses

Response samples

Content type
application/json
{
  • "activity": {
    },
  • "links": {
    }
}

Get related sales activities by activityId

Endpoint to retrieve the related sales activities identified from the /sales-activities/{activityId} endpoint

Authorizations:
OAuth2
path Parameters
activityId
required
string

A unique id that identifes an individual activity resource.

Responses

Response samples

Content type
application/json
{
  • "salesActivities": [
    ],
  • "totalItems": 4,
  • "totalPages": 1,
  • "links": {
    }
}