Re-Optimization API

Attention: SAP Field Service Management documentation is now available at the SAP Help Portal. On 31 December 2020, docs.coresystems will no longer be available. Until that time, documentation will NOT be updated in docs.coresystems.

1.1 Overview

The Re-Optimization API can be used to asynchronously reschedule assigned jobs in an autonomous and optimized manner.

The rescheduling makes use of the optimization plugin framework, providing a number of standard plugins which can be used to determine the optimization criteria.

The optimization process can be further customized using the supported request options.

1.1.1 Swagger

You can find the Swagger UI with API definitions and tests for the EU environment here:


Note: For all other environments replace eu in with the appropriate cluster. (See Supported Clusters section below.)

1.2 Access

The Re-Optimization 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 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

Method URL
POST https://{cluster}

1.3.1 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.2 Body

The following properties are accepted by the request body:

Attention: please note that:

  1. Only activities are supported by this API, service calls cannot be rescheduled using this service
  2. The property keys - for example, activityIds and partitioningStrategy - are case sensitive. The wrong field name will cause a 400 error
  3. The addition of new properties will also cause a 400 error
Property Type Description Required
activityIds Array of strings The IDs of activities to be considered for re-optimization Required
optimisationPlugin String The name of optimization plugin to be used for optimization Required
start ISO 8601 DateTime string Activities will only be scheduled at or after this time Required
end ISO 8601 DateTime string Activities will only be scheduled before this time Required
partitioningStrategy Partitioning strategy configuration Criteria for partitioning large volumes of data (see Optional


  "activityIds": [
     "Activity 1",
     "Activity 2",
     "Activity 3"
  "optimizationPlugin": "Best",
  "start": "2019-08-11T22:00:00Z",
  "end": "2019-08-12T22:00:00Z",
  "partitioningStrategy": {
    "skills": [
      "Workcenter A",
      "Workcenter B"
} Data Partitioning

Requests with a large number of activities may take a significant amount of time to re-optimize. To improve the performance of such requests, as well as facilitate certain business requirements, data can be partitioned to allow multiple smaller scheduling sessions to be triggered in a single request. The partitioning strategy property of the request allows the consumer to configure the partitioning parameters.

Attention: in order to make use of skills-based data partitioning, the consumer must ensure to maintain the required skills and corresponding requirements both for technicians and activities respectively.

Partitioning Strategy Type Description
skills Array of strings Allows grouping activities by mutually exclusive skills. Each activity must have one of the provided skills assigned in order to be scheduled. Each technician must also have one of the skills assigned to be considered for optimization. No activity or technician can have more than one of the skills assigned.

1.4 Response

1.4.1 Success Response

Status Description
202 Accepted The request was accepted and is being processed asynchronously.


  "result": true

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.
409 Confict Another re-optimization is already in progress.
500 Internal Server Error An unexpected error occured while processing request. See error body for more details.


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