Repair Orders (1.31.1)

Introduction

The Repair Order API is a resource that can be used to read, write and modify Keyloop Repair Order data.

This resource is typically used to achieve outcomes within aftersales activities such as vehicle inspections, estimation, servicing and repair.

Repair Order Domain Hierarchy

The Repair Order domain obeys the following hierarchy;

  • Repair Order A Repair Order is the primary object within the Repair Order domain

    • Repair Order Job A Repair Order may contain one or more Repair Order Jobs

      • Repair Order Item A Repair Order Job may contain one or more Repair Order Items

Definitions

The following definitions are pertinent to the usage of this API.

  • "Repair Orders" are the artifact within Keyloop systems which capture all information related to an individual job in the aftersales environment.

  • "Repair Order Jobs" or "Jobs" are a container within a Repair Order into which Repair Order Items can be placed. Repair Order Jobs are typically used to group together the components (Parts, Labor etc.) required to achieve a common outcome.

  • "Repair Order Items" or "Items" are the individual components that are added to Repair Orders in order to achieve the expected outcome for the customer. There are different types of Repair Order Items, such as Labor, Parts & Notes.

  • "Menus" are pre-defined lists of Repair Order Items, usually defined by manufacturers, that indicate the expected Repair Order Items required to achieve a specific outcome.

  • "Labor Items" are the physical activities required to achieve a specific outcome, which must be completed by a Human Resource (e.g. Vehicle Technician).

  • "Parts Items" are the physical components required to achieve a specific outcome.

  • "Notes Items" are non-normalized descriptions that can be added to capture additional information pertinent to the outcome that cannot be communicated using other items such as Parts & Labor.

  • The contactAdvisor is usually the advisor who has customer-facing responsibilities for the Repair Order. This may differ from the advisor to whom the Repair Order is currently assigned, which is defined by the assignedAdvisor object.

  • The listPrice is the list price of the item, excluding any discounts.

  • The orderPrice is the selling price of the item, including any discounts.

Change history

[1.31.1]

  • Removed ap2 from server list (FEATURE)

[1.31.0]

  • Amend contact property to map to ContactDetails schema to include customer and address property for GET/repair-orders/{repairOrderId} (FEATURE)

[1.30.0]

  • Added CREDITED status to RepairOrderStatus, PartLineStatus, LaborLineStatus, NotesLineStatus and FeesLineStatus enumeration list schema (FEATURE)

[1.29.0]

  • Added address property, amended Contact schema to add customer property to RepairOrderSimple schema for GET/repair-orders (FEATURE)

[1.28.2]

  • Added payerAccount field to POST/repair-orders, PATCH/repair-orders/{repairOrderId}/details (FEATURE)

[1.28.1]

  • Renamed operationId to UpdateRepairOrderItems for endpoint PATCH /repair-orders/{repairOrderId}/items (FEATURE)
  • Renamed operationId to DeleteRepairOrderItems for endpoint DELETE /repair-orders/{repairOrderId}/items (FEATURE)
  • Removed partdId from PartUpdate schema
  • Renamed itemId to itemIds in itemIdParam schema

[1.28.0]

  • Added new endpoint PATCH /repair-orders/{repairOrderId}/items, enabling repair order items to be updated (FEATURE)
  • Added new endpoint DELETE /repair-orders/{repairOrderId}/items, enabling repair order items to be deleted (FEATURE)
  • Added ItemsUpdate, LaborUpdate, PartUpdate, FeeUpdate, NotesUpdate and itemIdParam models (FEATURE)

[1.27.1]

  • Typo corrected and re-worded text in change history section
  • Added serviceTypes,customerWaiting properties to Details schema
  • Removed nullable from Skill
  • Added linkReference to Menu schema

[1.27.0]

  • Added new DROP_OFF enum value to BookingOptionType

[1.26.3]

  • Changed consumer value from internal to dms.external

[1.26.2]

  • Rename properties of Skill schema (FEATURE)

[1.26.1]

  • updatehistory amend to RepairOrder model (FEATURE)
  • userId property added to ServiceAdvisor schema

[1.26.0]

  • Added skill to Labor schema. (FEATURE)
  • Added linePayer and serviceTypes to POST/repair-orders, POST/repair-orders/{repairOrderId}/jobs and POST/repair-orders/{repairOrderId}/multipleJobs
  • Repair Order API Realignment (FEATURE)
  • Added updateHistory property to RepairOrder schema
  • Example text corrected for jobs property (FEATURE)
  • Added customerPurchaseOrderNumber, payerAccount, completedDateTime, closedDateTime to details schema
  • Added feeType and linkReference to FeeCreate schema
  • Added updateHistory to RepairOrder model
  • Added details and resources property to RepairOrderSimple schema
  • RepairOrderStatus enumerations updated with CANCELLED value

[1.25.2]

  • Deleted example text for parts, fees schema (FEATURE)

[1.25.1]

  • Updated reference of common to common.v1.1.10.yaml (FEATURE)
  • Reverted labor and Notes properties for Menu schema

[1.25.0]

  • Repair Order API Realignment (FEATURE)
  • DiscountCreate, Discount schema merged to single schema Discount
  • Added linkReference property to PartCreate and LaborCreate schema
  • Added workStartedDateTime, workCompletedDateTime and linkReference properties to Job schema
  • Added menuType property to Menu schema
  • Changed Discount schema in Menu schema
  • Added updateHistory and linkReference properties to Part Schema
  • Added laborDepartmentType, updateHistory and linkReference properties to Labor schema
  • Added updateHistory property to Notes schema
  • Added updateHistory and linkReference properties to Fee schema
  • Added takeOwnership and advisorId properties to CheckInDetails schema
  • Added vehicleMileage property to DetailsUpdate schema
  • Added new endpoint 'check-out' to Repair Orders Actions section, to check-out vehicle

[1.24.0]

  • Removed swaggerhub urls
  • Fixed validation errors (removed JobSimple schema, among other changes)

[1.23.0]

  • Added new end point to create multiple jobs for a repair order(FEATURE)
  • Update Jira references and contact details

[1.22.0]

  • Added JobCreate Schema to RepairOrderCreate (FEATURE)
  • Replaced JobSimple with Job in RepairOrder Schema (FEATURE)
  • Updated Servers links to Keyloop

[1.21.0]

  • Revert FeeCreate PriceCreate schema back to Price (SW)

[1.20.0]

  • Added OAuth2 to for AddMenuToJob and AddItemsToJob end points

[1.19.0]

  • Add nullable property for jobConditionCode

[1.18.0]

  • Add new endpoint /jobs/{jobid}/items to allow adding multiple items to a job in one go. (FEATURE)

[1.17.0]

  • Add ItemPriceCreate to remove discount split from menuLaborCreate and menuPartCreate (FEATURE)

[1.16.0]

  • Add phone number to Repair Order search filter (FEATURE)

[1.14.0]

  • Added VHC distinction, categorization in GetRepairorder and GetRepairorderJob. Added vehicle specification codes in Get Repair Order under Vehicle section as referenceData (FEATURE)

[1.13.0]

  • Added contactAdvisorId to createRepairOrder and updateRepairOrderDetails end points request body. This will allow user to update Advisor on top of the repair order. (FEATURE)

    [1.12.1]

  • Added nullable property to DueInDateTime and DueOutDateTime objects. (EPIC)

    [1.12.0]

  • Additional Onhold Statuses in RepairOrderAPI (EPIC MIDWARE-2148)

    [1.11.0]

  • Added RepairOrderType to RepairOrder and RepairOrderSimple objects. (EPIC)

    [1.10.1]

  • Changed LaborLineStatus enum value from 'HALTED' to 'ONHOLD'. (EPIC)

    [1.10.0]

  • Added oAuth for Repair Order update apis. (EPIC)

    [1.9.0]

  • Added Part, Labor, Notes and Fees line statuses and added TechnicianDetails to Labor. (EPIC)
  • Removed common price object from Add labor and Add part end points. Added new price models locally for Add part and labor API's. (EPIC)

    [1.8.0]

  • Added new endpoints for update Details, Appointment and Planning (EPIC).
  • Modified 'DetailsUpdate' to allow contact details update as well as 'CustomerId', 'CompanyId' and 'VehicleId', added new schema definitions for these and added references (EPIC).

    [1.7.4]

  • Add Parts and Labour Pricing (MIDWARE-1811)

    [1.7.3]

  • Added Labor Description in Add Labor (MIDWARE-1792)

    [1.7.2]

  • Added x-onbehalf-of for user authentication

    [1.7.1]

  • Modified 'RepairOrderSimple' object 'contact' tag from 'ContactSearch' Shared object to 'Contact' Shared object.

    [1.7.0]

  • Added new endpoint or Add Fees to Job Added new endpoint or Add Fees to Job (EPIC).

    [1.6.1]

  • Added new query parameter 'reference' to find repair orders.
  • Added additionalProperties as 'fasle' for each object.
  • Removed Subscription end-point and PublicKey end-point. If, someone want's to implement this end-points in future please refer 1.6.0 version.

    [1.6.0]

  • PublicKey end-point

    [1.5.0]

  • Subscription end-point

    [1.4.1]

  • Updated missing tag descriptions

    [1.4.0]

  • Added CustomerWaiting flag to Details schema Appointment and checkin structure.
  • Check-In post call(/repair-orders/{repairOrderId}/check-in) related changes
  • customerSignature and damage are removed with respective schemas
  • made "checkInDateTime" only as mandatory field.

Repair Orders

Create, modify and retrieve Repair Order data

Create Repair Order

Creates a new Repair Order for an existing Customer and Vehicle.

  • A valid customerId and vehicleId must be provided in the request. These can be obtained using the 'Find Customer' and 'Find Vehicle' resources.

  • A request to this endpoint will not result in the creation of new Customer or Vehicle records in the DMS

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

Information required to create a new Repair Order

vehicleId
required
string

A unique id that identifies a vehicle in the DMS.

customerId
string

A unique id that identifies a customer in the DMS.

customerId is used when the customer in question is an individual or 'private' vehicle owner.

companyId
string

A unique id that identifies a customer in the DMS.

companyId is used when the customer in question is an organization, rather than an individual or 'private' owner.

object (DetailsSimple)

Details Model (Simple)

object (Contact)

Contact person

contactAdvisorId
string (Contact Advisor)

Contact advisor id

object (AppointmentSimple)

Appointment Model (Simple)

Array of objects (JobCreate)

Collection of jobs that are performed to the vehicle. Single job represents a logical work that needs to be performed at the same time (10'000km service, oil change, change of something)

Responses

Request samples

Content type
application/json
{
  • "vehicleId": "00000000-0000-0000-0000-000000000000",
  • "customerId": "00000000-0000-0000-0000-000000000000",
  • "companyId": "00000000-0000-0000-0000-000000000000",
  • "details": {
    },
  • "contact": {
    },
  • "contactAdvisorId": "1234",
  • "appointment": {
    },
  • "jobs": [
    ]
}

Response samples

Content type
application/json
{
  • "repairOrderId": "00000000-0000-0000-0000-000000000000",
  • "status": "CREATED",
  • "type": "WARRANTY",
  • "details": {
    },
  • "vehicle": {
    },
  • "customer": {
    },
  • "company": {
    },
  • "contact": {
    },
  • "resources": {
    },
  • "appointment": {
    },
  • "planning": {
    },
  • "jobs": [
    ],
  • "updateHistory": {
    },
  • "links": [
    ]
}

Find Repair Orders

Returns a list of Repair Orders that match the parameters provided.

  • At least one query parameter must be provided for the request to successfully return results > * All paramaters support partial search requests unless indicated otherwise
Authorizations:
OAuth2
query Parameters
contactName
string

Refines the search results by the Contact Name associated with the Repair Order

licensePlate
string

Refines search results by vehicle license plate(s).

phone
string

Phone filter

status
Array of strings (Repair order status)
Items Enum: "CREATED" "ONHOLD" "CHECKEDIN" "WORKSTARTED" "WORKCOMPLETED" "CHECKEDOUT" "CLOSED" "CANCELLED" "CREDITED"
Example: status=CREATED

Specifies the Repair Order status(es) that should be included in the search

  • CREATED - the default status for new Repair Orders
  • ONHOLD -
  • CHECKEDIN - the customer has handed over their vehicle to the workshop
  • WORKSTARTED - work has begun on the Vehicle
  • WORKCOMPLETED - all work is completed on the vehicle
  • CHECKEDOUT - the vehicle has been handed back to the customer
  • CLOSED - the Repair Order is closed and can no longer be modified
  • CREDITED - one or more of the invoices relating to the repair order has been partially or fully credited
dueInDateFrom
string <date>

Refines search results by the date the Vehicle is booked in for repair. Can be combined with the dueInDateTo parameter to query a date range

dueInDateTo
string <date>

Refines search results by the date the Vehicle is booked in for repair. Can be combined with the dueInDateFrom parameter to query a date range

reference
string

Refines search results by the DMS internal reference id for repair orders.

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
{
  • "repairOrders": [
    ],
  • "totalItems": 4,
  • "totalPages": 1,
  • "links": {
    }
}

Get Repair Order

Retrieves a Repair Order including a summary of associated Repair Order Jobs.

  • Detailed information about a specific job including a breakdown of items can be obtained using the 'Get Repair Order Job' resource and a valid jobId
Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

A unique id that identifies an individual Repair Order, which may differ from the reference users will be familiar with. A repairOrderId can be obtained using the 'Find Repair Orders' resource.

Responses

Response samples

Content type
application/json
{
  • "repairOrderId": "00000000-0000-0000-0000-000000000000",
  • "status": "CREATED",
  • "type": "WARRANTY",
  • "details": {
    },
  • "vehicle": {
    },
  • "customer": {
    },
  • "company": {
    },
  • "contact": {
    },
  • "resources": {
    },
  • "appointment": {
    },
  • "planning": {
    },
  • "jobs": [
    ],
  • "updateHistory": {
    },
  • "links": [
    ]
}

Repair Orders: Jobs

Create, retrieve and delete Repair Order Jobs

Create Repair Order Jobs

Creates Repair Order Jobs on an existing Repair Order.

Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

A unique id that identifies an individual Repair Order, which may differ from the reference users will be familiar with. A repairOrderId can be obtained using the 'Find Repair Orders' resource.

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

Repair order job

description
string

A description of the Repair Order Job.

The contents of description will typically be visible on the Repair Order for DMS users and customers.

linkReference
string

Identifier of job for external use

Array of objects (ClassificationItem)

A list of classification items for repair order job.

serviceTypes
Array of strings (Service Type)
Items Enum: "BODYSHOP" "INTERNAL" "MOT" "RECOVERY" "SCHEDULED_MAINTENANCE" "SERVICE" "UNSCHEDULED_MAINTENANCE" "WARRANTY"

The service type(s) associated with the job

Array of objects (MenuCreate)

A pre-defined list of Repair Order Items, usually defined by manufacturers, that indicates the expected Repair Order Items required to achieve a specific outcome.

Array of objects (LaborCreate)

The physical activities required to achieve a specific outcome, which must be completed by a Human Resource (e.g. Vehicle Technician)

Array of objects (PartCreate)

The physical components required to achieve a specific outcome.

Array of objects (NotesCreate)

Non-normalized notes that can be added to capture additional information pertinent to the outcome, that cannot be communicated using other items such as Parts & Labor.

Array of objects (FeeCreate)

Fee Items

Responses

Request samples

Content type
application/json
{
  • "description": "Replace worn front N/S brake disc + pads",
  • "linkReference": "1",
  • "classificationItem": [
    ],
  • "serviceTypes": [
    ],
  • "menus": [
    ],
  • "labor": [
    ],
  • "parts": [
    ],
  • "notes": [
    ],
  • "fees": [
    ]
}

Response samples

Content type
application/json
{
  • "jobId": "00000000-0000-0000-0000-000000000000",
  • "description": "Replace worn front N/S brake disc + pads",
  • "serviceTypes": [
    ],
  • "workStartedDateTime": "2021-07-16T00:00:00.000Z",
  • "workCompletedDateTime": "2021-07-16T00:00:00.000Z",
  • "linkReference": "1",
  • "isVhc": true,
  • "vhcDetails": {
    },
  • "menus": [
    ],
  • "labor": [
    ],
  • "parts": [
    ],
  • "notes": [
    ],
  • "fees": [
    ],
  • "links": [
    ]
}

Create Multiple Repair Order Jobs

Creates Multiple Repair Order Jobs on an existing Repair Order.

Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

A unique id that identifies an individual Repair Order, which may differ from the reference users will be familiar with. A repairOrderId can be obtained using the 'Find Repair Orders' resource.

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

Repair order jobs create

Array of objects (JobCreate)

Responses

Request samples

Content type
application/json
{
  • "jobsCreate": [
    ]
}

Response samples

Content type
application/json
{
  • "jobs": [
    ]
}

Get Repair Order Job

Retrieves a specific Repair Order Job.

Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

A unique id that identifies an individual Repair Order, which may differ from the reference users will be familiar with. A repairOrderId can be obtained using the 'Find Repair Orders' resource.

jobId
required
string

A unique id that identifies the Repair Order Job. Can be obtained using the 'Get Repair Order' resource

Responses

Response samples

Content type
application/json
{
  • "jobId": "00000000-0000-0000-0000-000000000000",
  • "description": "Replace worn front N/S brake disc + pads",
  • "serviceTypes": [
    ],
  • "workStartedDateTime": "2021-07-16T00:00:00.000Z",
  • "workCompletedDateTime": "2021-07-16T00:00:00.000Z",
  • "linkReference": "1",
  • "isVhc": true,
  • "vhcDetails": {
    },
  • "menus": [
    ],
  • "labor": [
    ],
  • "parts": [
    ],
  • "notes": [
    ],
  • "fees": [
    ],
  • "links": [
    ]
}

Delete Repair Order Jobs

Deletes Repair Order Jobs from a Repair Order.

  • Jobs cannot be deleted if any of their constituent items have already had time clocked against them
Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

A unique id that identifies an individual Repair Order, which may differ from the reference users will be familiar with. A repairOrderId can be obtained using the 'Find Repair Orders' resource.

jobId
required
string

A unique id that identifies the Repair Order Job. Can be obtained using the 'Get Repair Order' resource

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.

Responses

Response samples

Content type
application/json
{
  • "correlationId": "48fb4cd3-2ef6-4479-bea1-7c92721b988c",
  • "message": "Invalid request",
  • "details": [
    ],
  • "links": [
    ]
}

Repair Orders: Items

Add and manage Repair Order Items

Add Labor

Adds Labor Items to the Repair Order.

  • Labor Items are identified by the laborCode, which must be used in conjunction with a valid brandCode.

  • Must be combined with a jobId to specify which Repair Order Job the Parts Item should be added to

Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

A unique id that identifies an individual Repair Order, which may differ from the reference users will be familiar with. A repairOrderId can be obtained using the 'Find Repair Orders' resource.

jobId
required
string

A unique id that identifies the Repair Order Job. Can be obtained using the 'Get Repair Order' resource

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

Information required to add a new Labor Item

laborCode
string

A unique id that identifies pre-defined Labor Tasks within Keyloop systems. The laborCode object is brand-specific and must be used in conjunction with a brandCode.

brandCode
string

A unique id that identifies the Brand with which the laborCode is associated.

description
string

Description for Labor Tasks.

allowedTimeInMinutes
integer <int32>

Flat rate labor allowance (standard time) time in minutes issued by the provider. This is the time how long (in average) it should take to perform the labor operation.

linePayer
string (Line Payer)
Enum: "CUSTOMER" "DEALER" "WARRANTY" "CONTRACT" "OTHER"

The party responsible for paying for the Item.

object (PriceCreate)

Price details to use while create anything related to money.

linkReference
string

Identifier of labor for external use

Responses

Request samples

Content type
application/json
{
  • "laborCode": "LABOR1",
  • "brandCode": "DEALER",
  • "description": "Labor Description",
  • "allowedTimeInMinutes": 1,
  • "linePayer": "CUSTOMER",
  • "price": {
    },
  • "linkReference": "1"
}

Response samples

Content type
application/json
{
  • "itemId": "00000000-0000-0000-0000-000000000000",
  • "status": "CREATED",
  • "sequenceNumber": 1,
  • "notes": "Requires disassembly of wheel-arch to allow sufficient access",
  • "laborCode": "LABOR1",
  • "brandCode": "DEALER",
  • "allowedTimeInMinutes": 90,
  • "description": "Replace front brake disc",
  • "laborDepartmentType": "MOBILESERVICE",
  • "skill": {
    },
  • "discount": {
    },
  • "linePayer": "CUSTOMER",
  • "listPrice": {
    },
  • "orderPrice": {
    },
  • "updateHistory": {
    },
  • "technician": {
    },
  • "linkReference": "1"
}

Add Parts

Adds Parts Items to the Repair Order.

  • Parts Items are identified using the partId. If the partId is not known, it can be obtained using the 'Find Parts' resource

  • Must be combined with a jobId to specify which Repair Order Job the Parts Item should be added to

Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

A unique id that identifies an individual Repair Order, which may differ from the reference users will be familiar with. A repairOrderId can be obtained using the 'Find Repair Orders' resource.

jobId
required
string

A unique id that identifies the Repair Order Job. Can be obtained using the 'Get Repair Order' resource

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

Repair order job part item

partId
string

A unique id that identifies a Part in the DMS.

brandCode
string

The part's brand code, used with the part code to find the partId. This can be retrieved using the /parts/brands end-point.

partCode
string

The part's code, used with the brand code to find the partId

linePayer
string (Line Payer)
Enum: "CUSTOMER" "DEALER" "WARRANTY" "CONTRACT" "OTHER"

The party responsible for paying for the Item.

quantity
number <double>

The quantity of the Part.

Each Part has a default unitOfMeasure, which indicates the 'real' value of the numerical quantity field.

object (PriceCreate)

Price details to use while create anything related to money.

linkReference
string

Identifier of part for external use

Responses

Request samples

Content type
application/json
{
  • "partId": "00000000-0000-0000-0000-000000000000",
  • "brandCode": "BRAND",
  • "partCode": "8765432",
  • "linePayer": "CUSTOMER",
  • "quantity": 1,
  • "price": {
    },
  • "linkReference": "1"
}

Response samples

Content type
application/json
{
  • "itemId": "00000000-0000-0000-0000-000000000000",
  • "status": "OPEN",
  • "sequenceNumber": 1,
  • "notes": "Brake disc may take 500km to wear in. Customer is advised to take extra caution.",
  • "partId": "00000000-0000-0000-0000-000000000000",
  • "brandCode": "BRAND",
  • "partCode": "8765432",
  • "unitOfMeasure": {
    },
  • "quantity": 1,
  • "description": "Front brake disc",
  • "discount": {
    },
  • "linePayer": "CUSTOMER",
  • "listPrice": {
    },
  • "orderPrice": {
    },
  • "updateHistory": {
    },
  • "linkReference": "1"
}

Add Notes

Adds Notes to the Repair Order to capture additional information relevant to the Job.

  • Must be combined with a jobId to specify which Repair Order Job the Notes should be added to
  • Multiple notes can be added to a single Job
  • Notes have no value, and cannot have time entries captured against them
  • Care should be taken as Notes may appear on customer-facing documentation
Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

A unique id that identifies an individual Repair Order, which may differ from the reference users will be familiar with. A repairOrderId can be obtained using the 'Find Repair Orders' resource.

jobId
required
string

A unique id that identifies the Repair Order Job. Can be obtained using the 'Get Repair Order' resource

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

Repair order notes item

notes
string

Notes or comments that add additional context.

Responses

Request samples

Content type
application/json
{
  • "notes": "Vehicle cleaning not required"
}

Response samples

Content type
application/json
{
  • "itemId": "00000000-0000-0000-0000-000000000000",
  • "status": "CREATED",
  • "sequenceNumber": 1,
  • "notes": "Vehicle cleaning not required",
  • "updateHistory": {
    }
}

Add Fees

Adds Fee Items to the Repair Order.

  • Fee Items are identified by the feeCode.

  • Must be combined with a jobId to specify which Repair Order Job the Fee Item should be added to

Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

A unique id that identifies an individual Repair Order, which may differ from the reference users will be familiar with. A repairOrderId can be obtained using the 'Find Repair Orders' resource.

jobId
required
string

A unique id that identifies the Repair Order Job. Can be obtained using the 'Get Repair Order' resource

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

Information required to add a new Fee Item

feeCode
string

A unique id that identifies pre-defined Fees within Keyloop systems. Not required if using a 'feeType'

feeType
string (FeeType)
Enum: "Other" "Environmental" "OilDisposal" "ThirdPartyLaborCost" "SmallMaterialCostsOnLabor" "SmallMaterialCostsOnParts"

A fee type which will be mapped in the DMS to a 'feeCode'

description
string

A description of the fee item.

The contents of description will typically be visible on the Repair Order for DMS users and customers.

linePayer
string (Line Payer)
Enum: "CUSTOMER" "DEALER" "WARRANTY" "CONTRACT" "OTHER"

The party responsible for paying for the Item.

quantity
number

Quantity for fee item.

object (Price)

This is common Price section that is used always when anything money related information is handled.

notes
string

Notes or comments that add additional context.

linkReference
string

Identifier of fee for external use

Responses

Request samples

Content type
application/json
{
  • "feeCode": "ENVFEE",
  • "feeType": "Environmental",
  • "description": "Environmental Fee",
  • "linePayer": "CUSTOMER",
  • "quantity": 1,
  • "orderPrice": {
    },
  • "notes": "Required to be collected as per regulatory",
  • "linkReference": "1"
}

Response samples

Content type
application/json
{
  • "itemId": "00000000-0000-0000-0000-000000000000",
  • "status": "CREATED",
  • "sequenceNumber": 1,
  • "notes": "Environmental fee is added automatically",
  • "feeCode": "ENVFEE",
  • "feeType": "Environmental",
  • "description": "Environmental Fee",
  • "quantity": 1,
  • "discount": {
    },
  • "linePayer": "CUSTOMER",
  • "orderPrice": {
    },
  • "updateHistory": {
    },
  • "linkReference": "1"
}

Add menus

Add menu to the Repair Order Job

Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

A unique id that identifies an individual Repair Order, which may differ from the reference users will be familiar with. A repairOrderId can be obtained using the 'Find Repair Orders' resource.

jobId
required
string

A unique id that identifies the Repair Order Job. Can be obtained using the 'Get Repair Order' resource

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

Information required to add a new menu

menuCode
string

A unique code that identifies the Menu.

brandCode
string

A unique id that identifies the Brand with which the menuCode is associated.

description
string

Description of menu.

linePayer
string (Line Payer)
Enum: "CUSTOMER" "DEALER" "WARRANTY" "CONTRACT" "OTHER"

The party responsible for paying for the Item.

menuType
string (MenuType)
Enum: "DMS_DEFINED" "FIXED" "ITEMISED"

A type of menu.
Enum value to be used :
* 'DMS_DEFINED' - use in the request when brandCode AND menuCode are supplied. This value lets the DMS to define the MenuType.
* 'FIXED' - use when menuComponents content and menuPrice are fixed.
* 'ITEMISED' - use when menuComponents content and menuprice are customer specific.

object (MenuPriceCreate)

Price details to use while create anything related to money.

object

Components are only required if a menuCode has not been supplied

linkReference
string

Identifier of menu for external use

Responses

Request samples

Content type
application/json
{
  • "menuCode": "MENU1",
  • "brandCode": "DEALER",
  • "description": "Menu description",
  • "linePayer": "CUSTOMER",
  • "menuType": "FIXED",
  • "menuPrice": {
    },
  • "menuComponents": {
    },
  • "linkReference": "1"
}

Response samples

Content type
application/json
{
  • "itemId": "00000000-0000-0000-0000-000000000000",
  • "sequenceNumber": 1,
  • "brandCode": "DEALER",
  • "menuCode": "MENU1",
  • "menuType": "FIXED",
  • "parts": [
    ],
  • "labor": [
    ],
  • "notes": [
    ],
  • "fees": [
    ],
  • "description": "Replace front brake disc",
  • "discount": {
    },
  • "linePayer": "CUSTOMER",
  • "listPrice": {
    },
  • "orderPrice": {
    },
  • "linkReference": "1"
}

Add items

Add multiple items to the Repair Order Job

Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

A unique id that identifies an individual Repair Order, which may differ from the reference users will be familiar with. A repairOrderId can be obtained using the 'Find Repair Orders' resource.

jobId
required
string

A unique id that identifies the Repair Order Job. Can be obtained using the 'Get Repair Order' resource

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

Information required to add a new menu

Array of objects (MenuCreate)

Menus included in this item list

Array of objects (LaborCreate)

Labor included in this item list

Array of objects (PartCreate)

Parts included in this item list

Array of objects (FeeCreate)

Fees included in this item list

Array of objects (NotesCreate)

Notes included in this item list

Responses

Request samples

Content type
application/json
{
  • "menus": [
    ],
  • "labor": [
    ],
  • "parts": [
    ],
  • "fees": [
    ],
  • "notes": [
    ]
}

Response samples

Content type
application/json
{
  • "menus": [
    ],
  • "parts": [
    ],
  • "labor": [
    ],
  • "notes": [
    ],
  • "fees": [
    ]
}

Update items

Update items in the Repair Order

Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

A unique id that identifies an individual Repair Order, which may differ from the reference users will be familiar with. A repairOrderId can be obtained using the 'Find Repair Orders' resource.

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

Information required to add a new menu

Array of objects (LaborUpdate)

Labor included in this item list.

Array of objects (PartUpdate)

Part included in this item list.

Array of objects (FeeUpdate)

Fees included in the item list.

Array of objects (NotesUpdate)

Notes included in this item list.

Responses

Request samples

Content type
application/json
{
  • "labor": [
    ],
  • "parts": [
    ],
  • "fees": [
    ],
  • "notes": [
    ]
}

Response samples

Content type
application/json
{
  • "correlationId": "48fb4cd3-2ef6-4479-bea1-7c92721b988c",
  • "message": "Invalid request",
  • "details": [
    ],
  • "links": [
    ]
}

Delete Items

Delete items in the Repair Order

Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

A unique id that identifies an individual Repair Order, which may differ from the reference users will be familiar with. A repairOrderId can be obtained using the 'Find Repair Orders' resource.

query Parameters
itemIds
required
Array of strings

Repair order item id

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.

Responses

Response samples

Content type
application/json
{
  • "correlationId": "48fb4cd3-2ef6-4479-bea1-7c92721b988c",
  • "message": "Invalid request",
  • "details": [
    ],
  • "links": [
    ]
}

Set Item Discount

Sets the discount for a Labor or Parts Item.

  • Setting a discount will overwrite any previous discount parameters set for the specified item
Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

A unique id that identifies an individual Repair Order, which may differ from the reference users will be familiar with. A repairOrderId can be obtained using the 'Find Repair Orders' resource.

jobId
required
string

A unique id that identifies the Repair Order Job. Can be obtained using the 'Get Repair Order' resource

itemId
required
string

Repair order item id

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

Discount to update

value
required
number <double>

Set the value to the amount you wish to deduct, using the 'type' to determine if a percentage or unit amount

currencyCode
string[A-Z]{3}

Currency code used when discount given is of GROSSVALUE type in ISO 4217.

type
required
string
Enum: "PERCENTAGE" "GROSSVALUE"

Use PERCENTAGE to deduct the 'value' as a precentage
Use GROSSVALUE to deduct the 'value' as an amount

description
string

Discount description

Responses

Request samples

Content type
application/json
{
  • "value": 10,
  • "currencyCode": "EUR",
  • "type": "PERCENTAGE",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "correlationId": "48fb4cd3-2ef6-4479-bea1-7c92721b988c",
  • "message": "Invalid request",
  • "details": [
    ],
  • "links": [
    ]
}

Repair Orders: Actions

Actions that achieve specific Repair Order outcomes

Check In Customer

Updates the status of the Repair Order, and allows certain data to be added, such as;

  • Vehicle mileage on arrival
  • Customer waiting preferences
  • Additional notes about the repair
Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

A unique id that identifies an individual Repair Order, which may differ from the reference users will be familiar with. A repairOrderId can be obtained using the 'Find Repair Orders' resource.

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 checkIn

notes
string

Additional notes for check-in

object (VehicleMileage)

Vehicle odometer reading

takeOwnership
boolean

Defines whether ownership of the Repair Order should be transferred to the current advisor. If False then the Repair Order will remain assigned to the current advisor.

customerWaiting
boolean

Defines whether the customer is waiting on-site for work to be completed. If True, then the customer will remain on-site.

advisorId
string

The Id of the Advisor who checked in the customer

checkInDateTime
string <date-time>

The date and time the vehicle was checked in.

Responses

Request samples

Content type
application/json
{
  • "notes": "Additional",
  • "checkInMileage": {
    },
  • "takeOwnership": true,
  • "customerWaiting": true,
  • "advisorId": "rca1",
  • "checkInDateTime": "2021-07-16T00:00:00.000Z"
}

Response samples

Content type
application/json
{
  • "repairOrderId": "00000000-0000-0000-0000-000000000000",
  • "status": "CREATED",
  • "type": "WARRANTY",
  • "details": {
    },
  • "vehicle": {
    },
  • "customer": {
    },
  • "company": {
    },
  • "contact": {
    },
  • "resources": {
    },
  • "appointment": {
    },
  • "planning": {
    },
  • "jobs": [
    ],
  • "updateHistory": {
    },
  • "links": [
    ]
}

Update repair order details

  • Updates the Repair Order details, such as Notes or Contact details
  • A valid customerId and vehicleId must be provided in the request. These can be obtained using the 'Find Customer' and 'Find Vehicle' resources.
Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

repairOrderId

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

Repair Order details

vehicleId
string (VehicleId)

A unique id that identifies a vehicle in the DMS.

customerId
string (CustomerId)

A unique id that identifies a customer in the DMS.

customerId is used when the customer in question is an individual or 'private' vehicle owner.

companyId
string (CompanyId)

A unique id that identifies a customer in the DMS.

companyId is used when the customer in question is an organization, rather than an individual or 'private' owner.

payerAccount
string (PayerAccount)

The account number for the person or organisation paying the invoice.

notes
string

Notes or comments that add additional context.

object (Contact)

Contact person

contactAdvisorId
string (Contact Advisor)

Contact advisor id

object (VehicleMileage)

Vehicle odometer reading

Responses

Request samples

Content type
application/json
{
  • "vehicleId": "00000000-0000-0000-0000-000000000000",
  • "customerId": "00000000-0000-0000-0000-000000000000",
  • "companyId": "00000000-0000-0000-0000-000000000000",
  • "payerAccount": "A12345",
  • "notes": "Vehicle cleaning not required",
  • "contact": {
    },
  • "contactAdvisorId": "1234",
  • "vehicleMileage": {
    }
}

Response samples

Content type
application/json
{
  • "correlationId": "48fb4cd3-2ef6-4479-bea1-7c92721b988c",
  • "message": "Invalid request",
  • "details": [
    ],
  • "links": [
    ]
}

Update repair order appointment details

Updates the Repair Order appointment details, such as;

  • Customer due-in and due-out dates
  • Customer waiting preferences
Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

repairOrderId

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

Appointment details

dueInDateTime
string or null <date-time> (DueInDateTime)

The date and time the vehicle is due to arrive at the workshop.

dueOutDateTime
string or null <date-time> (DueOutDateTime)

The date and time the vehicle is due to be collected.

customerWaiting
boolean

Defines whether the customer is waiting on-site for work to be completed. If True, then the customer will remain on-site.

Responses

Request samples

Content type
application/json
{
  • "dueInDateTime": "2019-03-20T00:00:00.000Z",
  • "dueOutDateTime": "2019-03-20T00:00:00.000Z",
  • "customerWaiting": true
}

Response samples

Content type
application/json
{
  • "correlationId": "48fb4cd3-2ef6-4479-bea1-7c92721b988c",
  • "message": "Invalid request",
  • "details": [
    ],
  • "links": [
    ]
}

Update repair order planning details

This endpoint is typically used by 3rd party planning applications to update the Repair Order planning details, such as;

  • Workshop planned-in and planned-out dates
Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

repairOrderId

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

Planning details

plannedIn
string <date-time>

The date and time the work is planned to start in the workshop.

plannedOut
string <date-time>

The date and time when the work is planned to finish in the workshop.

Responses

Request samples

Content type
application/json
{
  • "plannedIn": "2019-03-20T00:00:00.000Z",
  • "plannedOut": "2019-03-20T00:00:00.000Z"
}

Response samples

Content type
application/json
{
  • "correlationId": "48fb4cd3-2ef6-4479-bea1-7c92721b988c",
  • "message": "Invalid request",
  • "details": [
    ],
  • "links": [
    ]
}

Check Out Vehicle

Updates the status of the Repair Order, and allows certain data to be added, such as:

  • Vehicle mileage on departure
  • Additional notes about the repair
Authorizations:
OAuth2
path Parameters
repairOrderId
required
string

repairOrderId

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 checkOut

notes
string

Additional notes for check-out

object (VehicleMileage)

Vehicle odometer reading

advisorId
string

The Id of the Advisor who checked out the customer

checkOutDateTime
required
string <date-time>

The date and time the vehicle was checked out.

Responses

Request samples

Content type
application/json
{
  • "notes": "Additional",
  • "checkOutMileage": {
    },
  • "advisorId": "rca1",
  • "checkOutDateTime": "2021-07-16T00:00:00.000Z"
}

Response samples

Content type
application/json
{
  • "repairOrderId": "00000000-0000-0000-0000-000000000000",
  • "status": "CREATED",
  • "type": "WARRANTY",
  • "details": {
    },
  • "vehicle": {
    },
  • "customer": {
    },
  • "company": {
    },
  • "contact": {
    },
  • "resources": {
    },
  • "appointment": {
    },
  • "planning": {
    },
  • "jobs": [
    ],
  • "updateHistory": {
    },
  • "links": [
    ]
}