Introduction

Welcome to the Claire Customer Communication API !

This API is used to fetch data and handle all actions related to communication with customers.

We currently have the following communications available:

• Online check-in: Similar to airlines check-in, this communication is sent to the customer prior to his appointment
• Desk check-in: Used by receptionist with counter tablet, to allow the customer to check-in on site
• Keylocker check-in: For locations with Claire keylockers, to allow the customer to check-in while dropping his key
• Diagnose overview: Once the car has been checked by a mechanic, the receptionist can send this communication to ask the customer what is approved, what is not, and what needs more information
• Repair overview: Once the car is ready, the receptionist can send this communication to confirm what was done and what was not

More detail to be found in each section of this documentation.

Communication channels

We currently support two channels of communication with customers:

• Email
• SMS

More will be added in the future.

Authentication

Endpoints aimed at customers to read, upload attachments and answer communications use a communication key in the payload as authentication.

A communication key is unique, and valid through the whole appointment life-cycle, from check-in to repair overview, it does not change for each communication sent for an appointment.

This is done to ensure that a customer see the last communication available no matter from which Email/SMS he clicked.

Claire do not send these keys to anyone but the customer to guarantee that a communication was read and answered by the targeted customer.

When the dealer wants to control sending or displaying the communications, these keys are sent to the dealer through the webhook service, and the responsability to not leak or use these keys instead of the customer rest on them, see more below.

Endpoints aimed at receptionist use claire authentication tokens as all other services aimed at them.

Third party control

Notifying customers

It is possible for a dealer to send the communications links themselves, contact Claire support to activate this feature.

Communication keys will be sent to the dealer when the customer need to be notified, using the Claire webhook service.

Once enabled the dealer is responsible for communicating the link to the customer, and liable to not use the key themselves.

The links to be communicated to the customer are:

• https://comm.clairedev.nl/#!/COMMUNICATION_KEY on the development environment
• https://mycarcheck.pro/#!/COMMUNICATION_KEY on the production environment

Custom frontend

It is also possible for the dealer to use it's own frontend, in which case, they must not pre-fetch the communication themselves and later on have the customer read it from their system.

Instead, they must ensure that the communication is fetched when the customer read the communication.

Claire is not responsible for incorrect information shown to the receptionist if the dealer fail to ensure this.

If the dealer wish to augment the features available in the frontend of a communication, or store the communication data, two infrastructures are possible:

• Fetch the communication from the frontend code, and call the dealer backend as well after that when needed
• Set up a proxy backend between the frontend and Claire backend. This proxy backend must be used by the dealer frontend only to guarantee it's called when the customer read the communication

The same options are possible when uploading attachments or answering communications.

Endpoints responses

When a call to an endpoint succeed, this API reponds with HTTP 200 and return the following body

{"data":{"seeEachEndpoint":"forTheDataReturnedHere"}}

When a call to an endpoint is done with invalid payload or parameters, or when a validation error occur, or when an expected error occur, this API reponds with HTTP 200 and return the following body:

{"errors":["error 1", "error 2", "error N"]}

See the Errors section for when other HTTP code are returned.

Global communication endpoints

These endpoints are to be used no matter what the current Communication Status is.

They respond and act accordingly to the current status of the communication.

Read communication

curl "API_BASE/v1/communication/read"

This endpoint will prepare any data needed for the current communication status, mark the communication as read if a customer key is used, and return the communication data to be displayed. This is a general endpoint, to be used when the customer or receptionist want to read the communication, no matter what the current status of the communication is (check-in, diagnose, repair...). Do not use this endpoint with a customer key to retrieve the communication for internal purpose, as the communication will be marked as read by the customer and shown as such in the appointment detail page in the Claire dashboard.

HTTP Request

POST /v1/communication/read

The request Body payload is:

{
    "key": ""
}

The request JSON response is:

{
    "created_on": "0001-01-01T00:00:00Z",
    "updated_on": "0001-01-01T00:00:00Z",
    "customer_communication_id": 0,
    "receptionist_key": "",
    "status": 0,
    "correct_phone": "",
    "correct_email": "",
    "customer_id": null,
    "appointment_id": 0,
    "car_id": 0,
    "receptionist_id": null,
    "dealer_location_id": 0,
    "note": "",
    "user_key": null,
    "customer": null,
    "appointment": null,
    "car": null,
    "receptionist": null,
    "results": null,
    "check_in_remarks": null,
    "customcom_remarks": null,
    "check_in_results": null,
    "agreements": null,
    "events": null,
    "is_receptionist": false,
    "settings": null
}

Request schema

Response schema

This endpoint return an object of type CustomerCommunication, please refer to the JSON response column on the right, or to the Models and Enumeration section for more details.

Upload a remark attachment.

curl "API_BASE/v1/communication/upload_attachment"

When the customer want to upload an attachment while writing a remark, this endpoint is used to upload it. The attachment URL returned can then be used when submitting the answer in the 'remarks.attachments'. A maximum of 10 files can be attached to one communication and each file are limited to 32Mb.

HTTP MultiPart Request

POST /v1/communication/upload_attachment

The request parts are:

--XXX
Content-Disposition: form-data; name=

...
--XXX
Content-Disposition: form-data; name=

...--XXX--

The request JSON response is:

{
    "url": ""
}

This request must be a multipart/form-data content-type with valid boundary for each part

Request parts schema

Response schema

This endpoint return an object with the following fields, please refer to the JSON response column on the right for an example.

Diagnose-Overview

Answer a diagnose overview communication

curl "API_BASE/v1/diagnose_overview/answer"

When the customer read a diagnose overview communication, he is expected to answer it, using this endpoint.

HTTP Request

POST /v1/diagnose_overview/answer

The request Body payload is:

{
    "key": "",
    "results": null,
    "remarks": null,
    "correct_phone": null,
    "correct_email": null,
    "agreement_ids": null,
    "customer_name": ""
}

The request JSON response is:

This endpoint do not return anything, only the HTTP status code matters.

Request schema

Response schema

This endpoint do not return anything, only the HTTP status code matters.

Online-Checkin

Customer answers a sent CustomCommunication

curl "API_BASE/v1/online_checkin/answer"

When the customer read an online check-in communication, he is expected to answer it, using this endpoint.

HTTP Request

POST /v1/online_checkin/answer

The request Body payload is:

{
    "key": "",
    "results": null,
    "remarks": null,
    "correct_phone": null,
    "correct_email": null,
    "agreement_ids": null,
    "customer_name": "",
    "preferred_communication_channel": null,
    "drop_in_acses_locker": false
}

The request JSON response is:

{
    "keylocker_pin": null,
    "acses_pin": "",
    "acses_locker_name": ""
}

Request schema

Response schema

This endpoint return an object with the following fields, please refer to the JSON response column on the right for an example.

ACSES KeyLockers that are available to the Customer

curl "API_BASE/v1/online_checkin/is_acses_available"

If a Location has ACSES KeyLockers enabled and there is a LockerCell available in any LockerSystem. The Customer will be prompted to drop their keys in the Locker.

HTTP Request

POST /v1/online_checkin/is_acses_available

The request Body payload is:

{
    "key": ""
}

The request JSON response is:

{
    "available": false
}

Request schema

Response schema

This endpoint return an object with the following fields, please refer to the JSON response column on the right for an example.

Models and Enumerations

Enumerations

AppointmentNoteType Enumeration

BarCode Enumeration

CheckInResultStatus Enumeration

ChecklistType Enumeration

CommunicationChannelID Enumeration

CommunicationEventType Enumeration

CommunicationLayoutID Enumeration

CommunicationReceiverStatus Enumeration

CommunicationResultStatus Enumeration

CommunicationStatus Enumeration

DBBStatus Enumeration

DMSID Enumeration

DeskCommunicationEventType Enumeration

DeskCommunicationStatus Enumeration

HeadingPosition Enumeration

InterventionElementStatus Enumeration

InterventionElementType Enumeration

KeyLockerCommunicationEventType Enumeration

KeyLockerCommunicationStatus Enumeration

KeylockerPinRequestType Enumeration

LandingPageID Enumeration

LanguageCode Enumeration

MCCStatus Enumeration

PinOrderStatusID Enumeration

PinStatusID Enumeration

PinTypeID Enumeration

QuestionElementTemplate Enumeration

QuestionResultStatus Enumeration

RoleID Enumeration

SMSGateway Enumeration

Season Enumeration

SnoozeDepartmentID Enumeration

SnoozeStatusID Enumeration

SnoozeTypeID Enumeration

StatusIdentifier Enumeration

TyreLocation Enumeration

TyrePosition Enumeration

TyreTeamChannelID Enumeration

UserStatusID Enumeration

VersionTier Enumeration

WarrantyTypeID Enumeration

Models

ACL Model

AnswerItem Model

Appointment Model

AppointmentNote Model

AppointmentNoteAttachment Model

AppointmentStatus Model

AppointmentStatusHistory Model

Brand Model

Car Model

CarAttachment Model

CarLeadPrediction Model

CarNote Model

CarNoteAttachment Model

CarTyres Model

Check Model

CheckInAgreedIntervention Model

CheckInAttachment Model

CheckInDeclinedIntervention Model

CheckInRemark Model

CheckInResult Model

Checklist Model

ChecklistTemplate Model

CommunicationAgreement Model

CommunicationEvent Model

CommunicationLayout Model

CommunicationReceiver Model

CommunicationResult Model

CommunicationSetting Model

Customer Model

CustomerCommunication Model

DMSAppointmentNote Model

DMSCarNote Model

DNSRecord Model

Dealer Model

DealerLocation Model

DeskAgreedIntervention Model

DeskCommunication Model

DeskCommunicationEvent Model

DeskDeclinedIntervention Model

DiagnoseOverviewAgreedIntervention Model

DiagnoseOverviewAgreedResult Model

DiagnoseOverviewAttachment Model

DiagnoseOverviewContactResult Model

DiagnoseOverviewDeclinedResult Model

DiagnoseOverviewRemark Model

Domain Model

Feature Model

FinalCheckImage Model

FinalCheckVideo Model

FormFile Model

Intervention Model

InterventionElement Model

KeyLockerAgreedIntervention Model

KeyLockerCommunication Model

KeyLockerCommunicationEvent Model

KeyLockerCommunicationReceiver Model

KeyLockerRemark Model

MCCDealerLocationCode Model

Pin Model

Question Model

QuestionElement Model

QuestionGroup Model

QuestionOption Model

QuestionResult Model

QuestionResultImage Model

QuestionResultVideo Model

Role Model

Snooze Model

Tag Model

Timeslot Model

TruckTyres Model

Tyre Model

TyreReplacement Model

UnfinishedCheck Model

User Model

Version Model

Changelog

This section contains changes related to the CustomCom service. Changes will be included if:

• A new endpoint is added
• A new field is added to an existing endpoint
• Field description changes
• A field is deprecated

Initial release - 03.11.2022.

The following endpoints are included with initial release:

• /v1/communication/read
• /v1/communication/upload_attachment
• /v1/online_checkin/answer
• /v1/diagnose_overview/answer

Errors

The Claire Automotive Support APIs uses the following error codes: