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 following server clusters:

  • EU
  • DE
  • US
  • AU
  • CN

Attention: please note that in China (CN), driving distances will only be calculated as Euclidean distances (straight line) due to legal limitations.


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

Attention: please note that:

  1. The property keys - for example, objectId and companyNames - are case sensitive. The wrong field name will cause a 400 error
  2. The addition of new properties will also cause a 400 error
Value Description Type Required
objectType The type of object to be matched, can either be ‘ACTIVITY’ or ‘SERVICECALL’ String Required
objectId The identifier of the object 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

Additional data options:

Value Description Type Required
useBlacklist The blacklist of resources should be fetched for the job. Should only be set to True if Company Type is Single Tenant Crowd. Blacklist functionality has no affect on in-house technicians. Default false Boolean Optional

Resources:

Value Description Type Required
includeInternalPersons Default true Boolean Optional
includeCrowdPersons Default false Boolean Optional
personIds Only consider technicians from this array. When the array is not present, all the technicians will be considered, up to a maximum of 100. When the array size exceeds 100, only technicians up to this limit are considered. 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"
    ]
  },
  "additionalDataOptions": {
    "useBlacklist": true
  }
}

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"
}