Best Matching Technician API

1.1 Overview

The Best Matching Technician API enables customers to automatically find the best matching technician for an activity/service call. The process is plugin based and creates additional value for the customer through the possibility of customized plugins that fit specific business needs.

1.1.1 Swagger

You can find a swagger ui for api definitions and tests for eu environment here: https://eu.coresystems.net/optimization/api/v1/swagger-ui/#/Best-Matching-Technicians

Note: For all other environments replace “eu” in eu.coresystems.net with the appropriate environment


1.2 Access

The BMT API uses Oauth 2.0 for authentication. This token is then used in the Authorization header as the bearer.

Attention: In order to receive an access token, you must have ADMINISTRATOR or SUPERUSER privileges.

1.2.1 Get Access Token

The following example shows how to get the access token for a Cloud Account or a Company User:


Cloud Account


The following example is an example of authentication for a Coresystems Cloud account with access to all companies within the account:


POST https://auth.coresuite.com/api/oauth2/v1/token HTTP/1.1

Host et.dev.coresuite.com
Authorization Basic dGVzdDpzZWNyZXQ=
Content-Type application/x-www-form-urlencoded

grant_type=password&username=cym&password=passwordExample123


Company User


The following example of authentication for a company user, with access to companies controlled by existing subscription and permission settings:


POST https://auth.coresuite.com/api/oauth2/v1/token HTTP/1.1

Host et.dev.coresuite.com
Authorization Basic dGVzdDpzZWNyZXQ=
Content-Type application/x-www-form-urlencoded

grant_type=password&username=cym/manager&password=passwordExample123

1.2.1.1 Response

The following is an example of a typical response:

{
  "access_token": "77cf4834-a347-4849-839b-4518823a739e",
  "token_type": "bearer",
  "expires_in": 43199,
  "scope": "general",
  "cluster_url": "https://et.dev.coresuite.com",
  "account": "testaccount",
  "account_id" : 284,
  "user": "manager",
  "user_email": "test@coresystems.ch",
  "companies": [
    {
      "id": 957,
      "name": "SBODemoCH",
      "description": "OEC Computers (Schweiz)"
    }
  ],
 }

1.2.1.2 Error Response

{
  "error": "invalid_grant",
  "error_description": "Bad credentials"
}

1.2.2 Supported Clusters

Depending on the location of the account, requests will be made to one of the supported server clusters.

Attention: please note that the CN (China) cluster is currently NOT supported.


1.3 Request

POST https://{cluster}.coresystems.net/optimization/api/v1/jobs/{id}/best-matching-technicians

1.3.1 Path Parameters

Parameter Description
id The alphanumeric ID of the Job (activity or service call) for which to find technicians

1.3.2 Headers

Header Description Required
Authorization OAuth 2.0 bearer token Required
X-Request-Id Request identifier used for request tracing Required
X-Client-Id The alphanumerical ID associated with the client Required
X-Client-Version The version of the client making the request Required
X-Account-Id The integer ID of the account Required
X-Account-Name The string based name of the account Required
X-Company-Id The integer ID of the company Required
X-Company-Name The string based name of the company Required
X-User-Id The integer ID of the user Optional
X-User-Name The string based name of the user Optional

1.3.3 Body

Value Description Type Required
objectType The type of object to be matched, can either be ‘ACTIVITY’ or ‘SERVICECALL’ String Required
optimizationPlugin Name of plugin to be used. If no custom plugins are present, defaults to choose are: ‘Best’, ‘Nearest’ and ‘Quickest’ String Required
companyNames Array of companies of which resources are considered by matching Array/string Optional

Scheduling options:

Value Description Type Required
spanJobs Jobs will be spanned over non-working time. Default true Boolean Optional
computeDrivingTime Determines if driving times will be considered. Default true Boolean Optional
defaultDrivingTimeMinutes Default is 30 minutes Integer Optional
overlapBookings Determines if technicians with overlapping bookings will be considered. Default true Boolean Optional
maxResults Number of returned result. Default 10 Integer Optional
timezoneId Default time zone to be considered, if no location is present in activity. Must be of format ‘Europe/Berlin’. Default null String Optional

Resources:

Value Description Type Required
includeInternalPersons Default true Boolean Optional
includeCrowdPersons Default false Boolean Optional
personIds Only consider technicians from this array Array/string Optional

Example

{
  "objectType": "ACTIVITY",
  "optimizationPlugin": "string",
  "companyNames": [
    "string"
  ],
  "schedulingOptions": {
    "spanJobs": true,
    "computeDrivingTime": true,
    "defaultDrivingTimeMinutes": 30,
    "overlapBookings": true,
    "maxResults": 10,
    "timezoneId": "string"
  },
  "resources": {
    "includeInternalPersons": true,
    "includeCrowdPersons": true,
    "personIds": [
      "string"
    ]
  }
}

1.4 Response

1.4.1 Success Response

Status Description
200 OK The request executed successfully and the request body contains the results.

Body

{
  "results": [
    {
      "job": {
        "id": "string",
        "startDateTime": "string",
        "endDateTime": "string",
        "trip": {
          "durationInMinutes": 0,
          "distanceInMeters": 0
        }
      },
      "resource": "string",
      "matchingScore": 0,
      "matchingSkills": [
        "string"
      ],
      "missingSkills": [
        "string"
      ],
      "availability": "string",
      "resourceType": "PERSON"
    }
  ]
}

1.4.2 Error Response

Status Description
400 Bad Request Request was malformed. See error body for more details.
401 Unauthorized No Authorization header was provided or the OAuth token is invalid.
404 Not Found An activity / service call with the provided ID could not be found.
500 Internal Server Error An unexpected error occured while processing request. See error body for more details.

Body

{
  "error": "error_code",
  "error_description": "String description of the error"
}