3.0.0

The service code REST API is used to create, update or delete service code definitions. Service codes are defined in a multilevel parent-child hierarchy. Service codes are an optional object that can be associated with an asset. A typical use case would be a technician recording problem, cause and resolution codes for an asset being repaired. However, the service code module is very generic and could be used in many different ways.

The service code API is a bit unique in that it allows adding all SubCodes (children and children of children) for a single parent in one API call rather than making a separate call for each individual level.

On this page:

Related pages:

Service Code Object

While technically there is no limit to the number of child service code levels, one must realize that there is practical limit based on usability and storage requirements of the mobile device.

Resource URL Summary

Retrieve the details of a specific Service Code

GET /seiapi/v3/trans/ServiceCode/${ServiceCodeID}

GET /seiapi/v3/trans/ServiceCode/${ServiceCodeID}/${ServiceCodeID}

GET /seiapi/v3/trans/ServiceCode/${ServiceCodeID}/${ServiceCodeID}/${ServiceCodeID}

Retrieve a list of all Service Codes

GET /seiapi/v3/trans/ServiceCode

Insert or Update the details of a specific Service Code

PUT /seiapi/v3/trans/ServiceCode/${ServiceCodeID}

PUT /seiapi/v3/trans/ServiceCode/${ServiceCodeID}/${ServiceCodeID}

PUT /seiapi/v3/trans/ServiceCode/${ServiceCodeID}/${ServiceCodeID}/${ServiceCodeID}

Update only supplied details of a specific Service Code

POST /seiapi/v3/trans/ServiceCode/${ServiceCodeID}

POST /seiapi/v3/trans/ServiceCode/${ServiceCodeID}/${ServiceCodeID}

POST /seiapi/v3/trans/ServiceCode/${ServiceCodeID}/${ServiceCodeID}/${ServiceCodeID}

Delete a specific Service Code

DELETE /seiapi/v3/trans/ServiceCode/${ServiceCodeID}

DELETE /seiapi/v3/trans/ServiceCode/${ServiceCodeID}/${ServiceCodeID}

DELETE /seiapi/v3/trans/ServiceCode/${ServiceCodeID}/${ServiceCodeID}/${ServiceCodeID}

API Specific Parameters

Parameter Description

${ServiceCodeID}

Identifies the Service Code Object.

Notice that the URL format supports directly accessing child codes.

HTTP Headers

This API uses the default ServiceMobility HTTP Headers.

API Specifics

Retrieve the details of a specific Service Code

This REST API will return a Service Code with the specified ID, or the specific hierarchy of IDs. The Service Code with the specified ID, or specific hierarchy of IDs, must already exist in the system.

The Service Code object returned will contain all child SubCodes starting at the level specified by the ${ServiceCodeID} value(s).

URL

GET /seiapi/v3/trans/ServiceCode/${ServiceCodeID}

GET /seiapi/v3/trans/ServiceCode/${ServiceCodeID}/${ServiceCodeID}

GET /seiapi/v3/trans/ServiceCode/${ServiceCodeID}/${ServiceCodeID}/${ServiceCodeID}

etc.

HTTP Request Body

This request does not require a request body.

HTTP Response Body

On success, an HTTP response code of 200 will be returned, and the response body will contain a Service Code Object including all child SubCodes. Otherwise, on error, the response body will contain a descriptive reason for the error.

JSON Format

 {
    "Code": "1",
    "Desc": {
        "en": "English description for code 1",
        "es": "Spanish description for code 1"
    },
    "SubCodes": [
        {
            "Code": "3",
            "Desc": {
                "en": "Engligh description for child code 3 of parent code 1",
                "es": "Spanish description for child code 3 of parent code 1"
            }
        }
    ]
}

Retrieve a list of all Service Codes

This REST API will return a list of all top-level Service Codes that exist in the system.

The Service Code objects returned will not contain any child SubCodes. Only the top-level Service Codes in the system will be returned.

URL

GET /seiapi/v3/trans/ServiceCode

HTTP Request Body

This request does not require a request body.

HTTP Response

On success, an HTTP response code of 200 will be returned, and the response body will contain a collection of Service Code Objects, excluding all child SubCodes.

It is possible for the returned collection to be empty if the system does not have any Service Codes.

HTTP Response Body

{
	"ServiceCodes" : [
		// A collection of zero or more Service Code Objects.
	]
}

Insert or Update the details of a specific Service Code

This REST API will insert a new Service Code Order with the specified ID, or the specific hierarchy of IDs, into the system, if a Service Code with the specified ID, or the specific hierarchy of IDs, does not already exist in the system.

If, however, the Work Order with the specified ID, or the specific hierarchy of IDs, does already exist in the system, then this REST API will update (i.e. replace) the already existing Service Code with the specified ID, or the specific hierarchy of IDs, with the details of the Service Code supplied in the HTTP Request Body.

If replacing an existing Service Code object, then the API will replace all child SubCodes starting at the level specified by the ${ServiceCodeID} value(s).

URL

PUT /seiapi/v3/trans/ServiceCode/${ServiceCodeID}

PUT /seiapi/v3/trans/ServiceCode/${ServiceCodeID}/${ServiceCodeID}

PUT /seiapi/v3/trans/ServiceCode/${ServiceCodeID}/${ServiceCodeID}/${ServiceCodeID}

etc.

HTTP Request Body

The HTTP request body must contain a valid Service Code Object.

Remember to include all required SubCodes.

HTTP Response

On success the API will return a status code of 200.

Update only supplied details of a specific Service Code

This REST API will update an existing Service Code with the information provided.

Any existing information not specified in the new request will remain unchanged.

The Service Code with the specified ID, or the specific hierarchy of IDs, must already exist in the system.

This API provides an easy and safe way to make updates to individual Service Codes or groups of Service Codes without having to provide the entire list, as any Service Codes that already exist, but are not specified in the POST call, are left unmodified, unlike the PUT method which would remove them.

URL

POST /seiapi/v3/trans/ServiceCode/${ServiceCodeID}

POST /seiapi/v3/trans/ServiceCode/${ServiceCodeID}/${ServiceCodeID}

POST /seiapi/v3/trans/ServiceCode/${ServiceCodeID}/${ServiceCodeID}/${ServiceCodeID}

etc.

HTTP Request Body

The HTTP request body must contain a valid Service Code Object.

HTTP Response

On success the API will return a response code of 200.

Delete a specific Service Code

This REST API will delete a Service Code and all of its child SubCodes with the specified ID, or the specific hierarchy of IDs, from the system. The Service Code with the specified ID, or specific hierarchy of IDs, must already exist in the system.

All child SubCodes will be deleted along with the specified Service Code.

URL

DELETE /seiapi/v3/trans/ServiceCode/${ServiceCodeID}

DELETE /seiapi/v3/trans/ServiceCode/${ServiceCodeID}/${ServiceCodeID}

DELETE /seiapi/v3/trans/ServiceCode/${ServiceCodeID}/${ServiceCodeID}/${ServiceCodeID}

etc.

HTTP Request Body

This request does not require a request body.

HTTP Response

On success an HTTP response code of 200 will be returned. The system will return HTTP response code 410 in case of non-existent Service Code Object.

Browser not supported