Service API v2

1.1 Overview

The Service API enables customers with external systems to make requests from a third-party application to SAP Field Service Management, where they can be planned and released to technicians.


1.1.1 Request Methods

The following methods are supported:

  Note Section
1.1.0.1 POST (create) a new service call and activities with sub-resources for it. 1.3
1.1.0.2 PATCH (partially update) an existing service call and/or activities and sub-resources. 1.4
1.1.0.3 GET information on a specific service call and related sub-resources 1.5
1.1.0.4 GET information on a specific activity and related sub-resources. 1.6
1.1.0.5 POST (create) service calls and optional activities and sub-resources in bulk. 1.7
1.1.0.6 PATCH (partially update) existing service calls and/or activities and sub-resources in bulk. 1.8

1.1.2 Service API in Swagger

To preview Service API functionality, you may use the SAP Service API Swagger implementation.


1.1.3 Postman Spec

The following file contains the supported methods and endpoints in JSON format which can be uploaded to Postman:


1.1.4 Physical Address Logic in Activities

1.1.4.1 Explicit Address

For GET, PUT, and PATCH responses, if an explicit address was created for the activity the address object will be embedded in the activity.

Explicit Address in Response

Activity {
    ...
    Address {
        city:,
        country:,
    }
    ...
}

1.1.4.2 Referenced Address

If address in only referenced from an activity (e.g. BP address is referenced) then the address object will be embedded in the activity with additional information.

Referenced Address

Activity {
    ...
    Address {
        source: "object type" // object type from which this address is coming from
        sourceId: "UUID", // UUID of address object
        city:,
        country:,
    }
    ...
}

1.1.4.3 Without Explicit Address

If the Address object is not provided inside the activity in a PUT or PATCH JSON request, the following will occur:

  Method Scenario
1.1.3.3.1 PUT Create an activity without explicitly creating address (there will be only one referenced from resolution logic).
1.1.3.3.2 PATCH If there was an address explicitly created previously, this address will be deleted and updated with the new address.

If the address object together with source and sourceId is provided inside the activity JSON request nothing will occur, as depicted in the following example:

Activity {
    ...
    Address {
        source: "object type" // object type from which this address is coming from
        sourceId: "UUID", // UUID of address object
        city:,
        country:,
    }
    ...
}

1.1.4.4 Without source and sourceId

If the Address object is provided inside the ativity JSON request without source and sourceId, the following scenarios will obtain:

  Scenario
1.1.4.4.1 If an explicit address already exists and it is the same address, no change will occur.
1.1.4.4.2 If an explicit address already exists, but it is different from that explicitly created for the activity, it will update.
1.1.4.4.3 If no explicit address exists, and the activity is not connected to a business partner address, a new address will be created and the activity linked to it.

1.1.5 Object Record Identification Logic

Please note that the the Service API v2 uses the following logic to determine if an activity, service call or linked resources (business partner, create person, contact, item, equipment, reserved materials, etc) already exist:

  • First check id
  • if it is not provided check code
  • if it is not provided check externalId

1.2 Access

The Service 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.2 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.3 Error Response

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

1.2.4 Supported Clusters

Depending on the location of the account, requets will be made to one of the following server clusters:

  • EU
  • DE
  • US
  • CN

Account information, including cluster assignment, are obtained from the Directory API.

This information is passed into requests made to the Service API as follows:

https://{cluster}.coresystems.net/api/service-management/v2/composite-tree/service-calls


1.3 POST Service Call with Optional Activities

Create a serviceCall with (optional) one or more Activity records.


1.3.1 Request

Method URL
POST https://{cluster}.coresystems.net/api/service-management/v2/composite-tree/service-calls

1.3.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-Name accountName The name of the account associated with ther request. Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-Name companyName The name of the company associated with the request. Required
X-User-Name userName The user namer. This is required only when using an OAuth token NOT associated with any user. Optional
account accountName Deprecated–will be removed soon. Use the X-Account-Name header instead. Deprecated
company companyName Deprecated, will be removed soon. Use the X-Company-Name header instead. Deprecated

1.3.3 Query Parameters

Query Parameter Value Description
autoCreateActivity true / false Optional. Default value = true. When true, a default activity record will be created, if no activity has been provided explicitly.

1.3.4 Request Body

The following are the values contained in a POST request:

Value Description Type Required
activities If applicable, the activity record/s associated with the serviceCall.
address The activity address.
city The city in which the activity is located. String
country The country in which the activity is located. String
source The source of the activity address (BUSINESSPARTNER, EQUIPMENT, SERVICECALL). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration.
sourceId The ID associated with the activity address source. String
state The state in which the activity is located. String
street The street in which the activity is located. String
streetNumber The streetnumber associated with the activity address. String
zipCode The zip code associated with the actrivity address. String
code The activity code. This value is automatically created by the system. String
contact The contact associated with the activity. String
id The contact ID associated with the activity. String
code The code associated with the activity contact. String
externalId If applicable, the external ID associated with the activity contact. String
createPerson If no record for the contact exists, a new person record will be created.
id The ID associated with the new person record. String
code The code associated with the new person record. String
externalId The external ID associated with the person responsible for creating the record. This value must be unique. String
dueDateTime The date/time at which the activity is due to be completed. DateTime
durationInMinutes The expected duration in minutes of the activity. Integer
earliestStartDate The earlest date on which the activity can occur. DateTime
equipment The equipment record associated with the activity.
id The ID of the equipment record associated with the activitiy. String
code The code of the equipment associated with the activity. String
externalId The external ID of the equipment associated with the activity. This value must be unique. String
externalId The external ID of the activity record. This value must be unique among all activity records. String
lastChanged The person responsible for last changing the record. String
remarks The  remarks associated with the activity. String
reservedMaterials The reserved materials associated with the activty. Array
externalId The externalId of the reserved material. This value must be unique among all reservedMaterial objects. String
id The ID of the reserved material. String
item The reserved material item. Required
id The ID assocaited with the reserved material item. String
code The code associated with the reserved material item String
externalId The external  ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String
moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided)
quantity The amount of reserved material items used for the activity. Integer Required
serialNumber The serial number of the reserved material item.
id The ID of the reserved material item managed by serial number. String
code The code of the reserved material item managed by serial number. String
externalId The external ID of the reserved material item managedd by serial number. This value must be unique. String
shipped If applicable, the amount of reserved material item that have stated "shipped", i.e. ordered but not yet available for usage. Integer
used The amount of reserved material item/s used during the course of the activity. Integer Required (defaults to 0 if not provided)
warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required
id The ID of the warehouse. String
code The code of the warehouse. String
externalId The external ID of the warehouse. This value must be unique. String
subject The subject of the activty. String Required
address The address of the service call.
city The city in which the service call is located. String
country The country in which the service call is located. String
source The source of the service call address (BUSINESSPARTNER, EQUIPMENT). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration
sourceId The ID associated with the service call address source. String
state The state in which the service call is located. String
street The street in which the service call is located. String
streetNumber The street number associated with the service call street address. String
zipCode The zip code associated with the service call address. String
businessPartner The business partner associated with the service call. A Business Partner general refers to the customer, but may also refer to a vendor, etc. Required
id The business partner ID. String
code The business partner code. String
externalId The external ID associated with the business partner. This value must be unique. String
code The service call code. This code is generated automatically by the system. String
Contact The contact associated with the service call.
id The ID associated with the service call contact. String
code The code associated with the service call contact. String
externalId The external ID associated with the service call contact. This value must be unique. String
createPerson The user responsible for creating the service call/activity. Optional
id The ID associated with the creator of the record. String
code The code associated with the new person record. String
externalId The external ID associated with the new person record. This value must be unique. String
dueDateTime The date/time at which the service call is due to be completed. DateTime
durationInMinutes The duration in minutes the service call is expected to last. Integer
earliestStartDateTime The earliest date/time on which the service call can be completed. DateTime
equipments The equipment record associated with the service call. Optional
id The ID of the equipment record associated with the service call. String
code The code associated with the service call equipment. String
externalId The external ID associated with the service call equipment. This value must be unique. String
externalId The external ID associated wth the service call record. This value must be unique among all serviceCall objects. String
lastChanged The person responsible for last changing the service call record. Integer
origin The origin of the service call (i.e. phone, online, etc). String Optional
priority The priority level associated with the service call (example: high, medium, low). String Required
problemType The problem  type associated with the service call (example: warranty, maintenance, etc.). String
remarks The remarks associated with the service call. String
reservedMaterials The reserved materials associated with the service call.
externalId The external  ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String
id The ID assocaited with the reserved material item. String
item The reserved material item. String Required
id The ID of the reserved material item. String
code The code of the reserved material item. String
externalId The external ID of the reserved material item. String
moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided)
quantity The quantity of reserved material. Integer Required
serialNumber If applicable, the reserved material managed by serial number.
id The ID of the reserved material item managed by serial number. String
code The code of the reserved material item managed by serial number. String
externalId The external ID of the reserved material item managed by serial number. String
shipped The amount of reserved material items with status "shipped"; i.e., ordered but not yet available for usage. Integer
used The amount of reserved material item/s used during the course of the service call. Integer Required (defaults to 0 if not provided)
warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required
id The ID of the warehouse. String
code The code of the warehouse. String
externalId The external ID of the warehouse. String
resolution The resolution status of the service call. String
responsibles The technician/s assigned to the service call.
id The ID associated with the responsibles assigned to the service call. String
code The code associated with the responsible assigned to the service call. String
externalId The external ID associated with the responsible assigned to the service call. String
status The current status of the service call. String Required
subject The subject of the service call. String Required

1.3.5 Response

Status Response
200 OK
401 Unauthorized
403 Forbidden

1.3.6 Example Response Body

{
  "activities": [
    {
      "address": {
        "city": "string",
        "country": "string",
        "source": "ACTIVITY",
        "sourceId": "string",
        "state": "string",
        "street": "string",
        "streetNumber": "string",
        "zipCode": "string"
      },
      "code": "string",
      "contact": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "createPerson": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "dueDateTime": "2019-04-09T09:15:03.638Z",
      "durationInMinutes": 0,
      "earliestStartDateTime": "2019-04-09T09:15:03.638Z",
      "equipment": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "externalId": "string",
      "id": "string",
      "lastChanged": 0,
      "remarks": "string",
      "reservedMaterials": [
        {
          "externalId": "string",
          "id": "string",
          "item": {
            "id": "string",
            "code": "string",
            "externalId": "string"
          },
          "moved": 0,
          "quantity": 0,
          "serialNumber": {
            "id": "string",
            "code": "string",
            "externalId": "string"
          },
          "shipped": 0,
          "used": 0,
          "warehouse": {
            "id": "string",
            "code": "string",
            "externalId": "string"
          }
        }
      ],
      "responsibles": [
        {
          "id": "string",
          "code": "string",
          "externalId": "string"
        }
      ],
      "status": "string",
      "subject": "string"
    }
  ],
  "address": {
    "city": "string",
    "country": "string",
    "source": "ACTIVITY",
    "sourceId": "string",
    "state": "string",
    "street": "string",
    "streetNumber": "string",
    "zipCode": "string"
  },
  "businessPartner": {
    "id": "string",
    "code": "string",
    "externalId": "string"
  },
  "code": "string",
  "contact": {
    "id": "string",
    "code": "string",
    "externalId": "string"
  },
  "createPerson": {
    "id": "string",
    "code": "string",
    "externalId": "string"
  },
  "dueDateTime": "2019-04-09T09:15:03.638Z",
  "durationInMinutes": 0,
  "earliestStartDateTime": "2019-04-09T09:15:03.638Z",
  "equipments": [
    {
      "id": "string",
      "code": "string",
      "externalId": "string"
    }
  ],
  "externalId": "string",
  "id": "string",
  "lastChanged": 0,
  "origin": "string",
  "priority": "string",
  "problemType": "string",
  "remarks": "string",
  "reservedMaterials": [
    {
      "externalId": "string",
      "id": "string",
      "item": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "moved": 0,
      "quantity": 0,
      "serialNumber": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "shipped": 0,
      "used": 0,
      "warehouse": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      }
    }
  ],
  "resolution": "string",
  "responsibles": [
    {
      "id": "string",
      "code": "string",
      "externalId": "string"
    }
  ],
  "status": "string",
  "subject": "string"
}

1.3.7 Response Values

Value Description Type Required
activities If applicable, the activity record/s associated with the serviceCall.
address The activity address.
city The city in which the activity is located. String
country The country in which the activity is located. String
source The source of the activity address (BUSINESSPARTNER, EQUIPMENT, SERVICECALL). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration.
sourceId The ID associated with the activity address source. String
state The state in which the activity is located. String
street The street in which the activity is located. String
streetNumber The streetnumber associated with the activity address. String
zipCode The zip code associated with the actrivity address. String
code The activity code. This value is automatically created by the system. String
contact The contact associated with the activity. String
id The contact ID associated with the activity. String
code The code associated with the activity contact. String
externalId If applicable, the external ID associated with the activity contact. String
createPerson If no record for the contact exists, a new person record will be created.
id The ID associated with the new person record. String
code The code associated with the new person record. String
externalId The external ID associated with the person responsible for creating the record. This value must be unique. String
dueDateTime The date/time at which the activity is due to be completed. DateTime
durationInMinutes The expected duration in minutes of the activity. Integer
earliestStartDate The earlest date on which the activity can occur. DateTime
equipment The equipment record associated with the activity.
id The ID of the equipment record associated with the activitiy. String
code The code of the equipment associated with the activity. String
externalId The external ID of the equipment associated with the activity. This value must be unique. String
externalId The external ID of the activity record. This value must be unique among all activity records. String
lastChanged The person responsible for last changing the record. String
remarks The  remarks associated with the activity. String
reservedMaterials The reserved materials associated with the activty. Array
externalId The externalId of the reserved material. This value must be unique among all reservedMaterial objects. String
id The ID of the reserved material. String
item The reserved material item. Required
id The ID assocaited with the reserved material item. String
code The code associated with the reserved material item String
externalId The external  ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String
moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided)
quantity The amount of reserved material items used for the activity. Integer Required
serialNumber The serial number of the reserved material item.
id The ID of the reserved material item managed by serial number. String
code The code of the reserved material item managed by serial number. String
externalId The external ID of the reserved material item managedd by serial number. This value must be unique. String
shipped If applicable, the amount of reserved material item that have stated "shipped", i.e. ordered but not yet available for usage. Integer
used The amount of reserved material item/s used during the course of the activity. Integer Required (defaults to 0 if not provided)
warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required
id The ID of the warehouse. String
code The code of the warehouse. String
externalId The external ID of the warehouse. This value must be unique. String
subject The subject of the activty. String Required
address The address of the service call.
city The city in which the service call is located. String
country The country in which the service call is located. String
source The source of the service call address (BUSINESSPARTNER, EQUIPMENT). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration
sourceId The ID associated with the service call address source. String
state The state in which the service call is located. String
street The street in which the service call is located. String
streetNumber The street number associated with the service call street address. String
zipCode The zip code associated with the service call address. String
businessPartner The business partner associated with the service call. A Business Partner general refers to the customer, but may also refer to a vendor, etc. Required
id The business partner ID. String
code The business partner code. String
externalId The external ID associated with the business partner. This value must be unique. String
code The service call code. This code is generated automatically by the system. String
Contact The contact associated with the service call.
id The ID associated with the service call contact. String
code The code associated with the service call contact. String
externalId The external ID associated with the service call contact. This value must be unique. String
createPerson The user responsible for creating the service call/activity. Optional
id The ID associated with the creator of the record. String
code The code associated with the new person record. String
externalId The external ID associated with the new person record. This value must be unique. String
dueDateTime The date/time at which the service call is due to be completed. DateTime
durationInMinutes The duration in minutes the service call is expected to last. Integer
earliestStartDateTime The earliest date/time on which the service call can be completed. DateTime
equipments The equipment record associated with the service call. Optional
id The ID of the equipment record associated with the service call. String
code The code associated with the service call equipment. String
externalId The external ID associated with the service call equipment. This value must be unique. String
externalId The external ID associated wth the service call record. This value must be unique among all serviceCall objects. String
lastChanged The person responsible for last changing the service call record. Integer
origin The origin of the service call (i.e. phone, online, etc). String Optional
priority The priority level associated with the service call (example: high, medium, low). String Required
problemType The problem  type associated with the service call (example: warranty, maintenance, etc.). String
remarks The remarks associated with the service call. String
reservedMaterials The reserved materials associated with the service call.
externalId The external  ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String
id The ID assocaited with the reserved material item. String
item The reserved material item. String Required
id The ID of the reserved material item. String
code The code of the reserved material item. String
externalId The external ID of the reserved material item. String
moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided)
quantity The quantity of reserved material. Integer Required
serialNumber If applicable, the reserved material managed by serial number.
id The ID of the reserved material item managed by serial number. String
code The code of the reserved material item managed by serial number. String
externalId The external ID of the reserved material item managed by serial number. String
shipped The amount of reserved material items with status "shipped"; i.e., ordered but not yet available for usage. Integer
used The amount of reserved material item/s used during the course of the service call. Integer Required (defaults to 0 if not provided)
warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required
id The ID of the warehouse. String
code The code of the warehouse. String
externalId The external ID of the warehouse. String
resolution The resolution status of the service call. String
responsibles The technician/s assigned to the service call.
id The ID associated with the responsibles assigned to the service call. String
code The code associated with the responsible assigned to the service call. String
externalId The external ID associated with the responsible assigned to the service call. String
status The current status of the service call. String Required
subject The subject of the service call. String Required

1.4 PATCH Service Call and Sub-resources

Partially update the serviceCall and associated activities and reserved materials.

Please note the following:

  Note
1.4.0.1 If no modification is desired, do not pass collection at all, or pass null.
1.4.0.2 If new elements are to be added, do not provide any kind of ID in their body or provide a non-existent ID.
1.4.0.3 If existing elements are to be modified, provide a valid ID along with the updated content.
1.4.0.4 PATCH requests use forceUpdate=true.

Example

Let’s assume Service Call has three Activities, and we want to update the one which has externalId = 1 and leave the rest intact:

"activities": [

   { "externalId": "1", "subject": "Updated subject"},

   { "externalId": "2"},

   { "externalId": "3"}

]

1.4.1 Request

Method URL
PATCH https://{cluster}.coresystems.net/api/service-management/v2/composite-tree/service-calls/{service-call-uid}

1.4.1.1 URL Parameters

Parameter Description Type Required
{service-call-uid} The ID of the service call record created via PATCH request you wish to update. String Required

1.4.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-Name accountName The name of the account associated with ther request. Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-Name companyName The name of the company associated with the request. Required
X-User-Name userName The user namer. This is required only when using an OAuth token NOT associated with any user. Optional
account accountName Deprecated–will be removed soon. Use the X-Account-Name header instead. Deprecated
company companyName Deprecated, will be removed soon. Use the X-Company-Name header instead. Deprecated

1.4.3 Request Body

The following are the values contained in a PATCH request:

Value Description Type Required
activities If applicable, the activity record/s associated with the serviceCall.
address The activity address.
city The city in which the activity is located. String
country The country in which the activity is located. String
source The source of the activity address (BUSINESSPARTNER, EQUIPMENT, SERVICECALL). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration.
sourceId The ID associated with the activity address source. String
state The state in which the activity is located. String
street The street in which the activity is located. String
streetNumber The streetnumber associated with the activity address. String
zipCode The zip code associated with the actrivity address. String
code The activity code. This value is automatically created by the system. String
contact The contact associated with the activity. String
id The contact ID associated with the activity. String
code The code associated with the activity contact. String
externalId If applicable, the external ID associated with the activity contact. String
createPerson If no record for the contact exists, a new person record will be created.
id The ID associated with the new person record. String
code The code associated with the new person record. String
externalId The external ID associated with the person responsible for creating the record. This value must be unique. String
dueDateTime The date/time at which the activity is due to be completed. DateTime
durationInMinutes The expected duration in minutes of the activity. Integer
earliestStartDate The earlest date on which the activity can occur. DateTime
equipment The equipment record associated with the activity.
id The ID of the equipment record associated with the activitiy. String
code The code of the equipment associated with the activity. String
externalId The external ID of the equipment associated with the activity. This value must be unique. String
externalId The external ID of the activity record. This value must be unique among all activity records. String
lastChanged The person responsible for last changing the record. String
remarks The  remarks associated with the activity. String
reservedMaterials The reserved materials associated with the activty. Array
externalId The externalId of the reserved material. This value must be unique among all reservedMaterial objects. String
id The ID of the reserved material. String
item The reserved material item. Required
id The ID assocaited with the reserved material item. String
code The code associated with the reserved material item String
externalId The external  ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String
moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided)
quantity The amount of reserved material items used for the activity. Integer Required
serialNumber The serial number of the reserved material item.
id The ID of the reserved material item managed by serial number. String
code The code of the reserved material item managed by serial number. String
externalId The external ID of the reserved material item managedd by serial number. This value must be unique. String
shipped If applicable, the amount of reserved material item that have stated "shipped", i.e. ordered but not yet available for usage. Integer
used The amount of reserved material item/s used during the course of the activity. Integer Required (defaults to 0 if not provided)
warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required
id The ID of the warehouse. String
code The code of the warehouse. String
externalId The external ID of the warehouse. This value must be unique. String
subject The subject of the activty. String Required
address The address of the service call.
city The city in which the service call is located. String
country The country in which the service call is located. String
source The source of the service call address (BUSINESSPARTNER, EQUIPMENT). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration
sourceId The ID associated with the service call address source. String
state The state in which the service call is located. String
street The street in which the service call is located. String
streetNumber The street number associated with the service call street address. String
zipCode The zip code associated with the service call address. String
businessPartner The business partner associated with the service call. A Business Partner general refers to the customer, but may also refer to a vendor, etc. Required
id The business partner ID. String
code The business partner code. String
externalId The external ID associated with the business partner. This value must be unique. String
code The service call code. This code is generated automatically by the system. String
Contact The contact associated with the service call.
id The ID associated with the service call contact. String
code The code associated with the service call contact. String
externalId The external ID associated with the service call contact. This value must be unique. String
createPerson The user responsible for creating the service call/activity. Optional
id The ID associated with the creator of the record. String
code The code associated with the new person record. String
externalId The external ID associated with the new person record. This value must be unique. String
dueDateTime The date/time at which the service call is due to be completed. DateTime
durationInMinutes The duration in minutes the service call is expected to last. Integer
earliestStartDateTime The earliest date/time on which the service call can be completed. DateTime
equipments The equipment record associated with the service call. Optional
id The ID of the equipment record associated with the service call. String
code The code associated with the service call equipment. String
externalId The external ID associated with the service call equipment. This value must be unique. String
externalId The external ID associated wth the service call record. This value must be unique among all serviceCall objects. String
lastChanged The person responsible for last changing the service call record. Integer
origin The origin of the service call (i.e. phone, online, etc). String Optional
priority The priority level associated with the service call (example: high, medium, low). String Required
problemType The problem  type associated with the service call (example: warranty, maintenance, etc.). String
remarks The remarks associated with the service call. String
reservedMaterials The reserved materials associated with the service call.
externalId The external  ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String
id The ID assocaited with the reserved material item. String
item The reserved material item. String Required
id The ID of the reserved material item. String
code The code of the reserved material item. String
externalId The external ID of the reserved material item. String
moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided)
quantity The quantity of reserved material. Integer Required
serialNumber If applicable, the reserved material managed by serial number.
id The ID of the reserved material item managed by serial number. String
code The code of the reserved material item managed by serial number. String
externalId The external ID of the reserved material item managed by serial number. String
shipped The amount of reserved material items with status "shipped"; i.e., ordered but not yet available for usage. Integer
used The amount of reserved material item/s used during the course of the service call. Integer Required (defaults to 0 if not provided)
warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required
id The ID of the warehouse. String
code The code of the warehouse. String
externalId The external ID of the warehouse. String
resolution The resolution status of the service call. String
responsibles The technician/s assigned to the service call.
id The ID associated with the responsibles assigned to the service call. String
code The code associated with the responsible assigned to the service call. String
externalId The external ID associated with the responsible assigned to the service call. String
status The current status of the service call. String Required
subject The subject of the service call. String Required

1.4.4 Response

Status Response
200 OK
204 No content
401 Unauthorized
403 Forbidden

1.4.5 Example Response Body

{
  "activities": [
    {
      "address": {
        "city": "string",
        "country": "string",
        "source": "ACTIVITY",
        "sourceId": "string",
        "state": "string",
        "street": "string",
        "streetNumber": "string",
        "zipCode": "string"
      },
      "code": "string",
      "contact": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "createPerson": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "dueDateTime": "2019-04-09T09:15:03.638Z",
      "durationInMinutes": 0,
      "earliestStartDateTime": "2019-04-09T09:15:03.638Z",
      "equipment": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "externalId": "string",
      "id": "string",
      "lastChanged": 0,
      "remarks": "string",
      "reservedMaterials": [
        {
          "externalId": "string",
          "id": "string",
          "item": {
            "id": "string",
            "code": "string",
            "externalId": "string"
          },
          "moved": 0,
          "quantity": 0,
          "serialNumber": {
            "id": "string",
            "code": "string",
            "externalId": "string"
          },
          "shipped": 0,
          "used": 0,
          "warehouse": {
            "id": "string",
            "code": "string",
            "externalId": "string"
          }
        }
      ],
      "responsibles": [
        {
          "id": "string",
          "code": "string",
          "externalId": "string"
        }
      ],
      "status": "string",
      "subject": "string"
    }
  ],
  "address": {
    "city": "string",
    "country": "string",
    "source": "ACTIVITY",
    "sourceId": "string",
    "state": "string",
    "street": "string",
    "streetNumber": "string",
    "zipCode": "string"
  },
  "businessPartner": {
    "id": "string",
    "code": "string",
    "externalId": "string"
  },
  "code": "string",
  "contact": {
    "id": "string",
    "code": "string",
    "externalId": "string"
  },
  "createPerson": {
    "id": "string",
    "code": "string",
    "externalId": "string"
  },
  "dueDateTime": "2019-04-09T09:15:03.638Z",
  "durationInMinutes": 0,
  "earliestStartDateTime": "2019-04-09T09:15:03.638Z",
  "equipments": [
    {
      "id": "string",
      "code": "string",
      "externalId": "string"
    }
  ],
  "externalId": "string",
  "id": "string",
  "lastChanged": 0,
  "origin": "string",
  "priority": "string",
  "problemType": "string",
  "remarks": "string",
  "reservedMaterials": [
    {
      "externalId": "string",
      "id": "string",
      "item": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "moved": 0,
      "quantity": 0,
      "serialNumber": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "shipped": 0,
      "used": 0,
      "warehouse": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      }
    }
  ],
  "resolution": "string",
  "responsibles": [
    {
      "id": "string",
      "code": "string",
      "externalId": "string"
    }
  ],
  "status": "string",
  "subject": "string"
}

1.4.6 Response Values

Value Description Type Required
activities If applicable, the activity record/s associated with the serviceCall.
address The activity address.
city The city in which the activity is located. String
country The country in which the activity is located. String
source The source of the activity address (BUSINESSPARTNER, EQUIPMENT, SERVICECALL). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration.
sourceId The ID associated with the activity address source. String
state The state in which the activity is located. String
street The street in which the activity is located. String
streetNumber The streetnumber associated with the activity address. String
zipCode The zip code associated with the actrivity address. String
code The activity code. This value is automatically created by the system. String
contact The contact associated with the activity. String
id The contact ID associated with the activity. String
code The code associated with the activity contact. String
externalId If applicable, the external ID associated with the activity contact. String
createPerson If no record for the contact exists, a new person record will be created.
id The ID associated with the new person record. String
code The code associated with the new person record. String
externalId The external ID associated with the person responsible for creating the record. This value must be unique. String
dueDateTime The date/time at which the activity is due to be completed. DateTime
durationInMinutes The expected duration in minutes of the activity. Integer
earliestStartDate The earlest date on which the activity can occur. DateTime
equipment The equipment record associated with the activity.
id The ID of the equipment record associated with the activitiy. String
code The code of the equipment associated with the activity. String
externalId The external ID of the equipment associated with the activity. This value must be unique. String
externalId The external ID of the activity record. This value must be unique among all activity records. String
lastChanged The person responsible for last changing the record. String
remarks The  remarks associated with the activity. String
reservedMaterials The reserved materials associated with the activty. Array
externalId The externalId of the reserved material. This value must be unique among all reservedMaterial objects. String
id The ID of the reserved material. String
item The reserved material item. Required
id The ID assocaited with the reserved material item. String
code The code associated with the reserved material item String
externalId The external  ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String
moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided)
quantity The amount of reserved material items used for the activity. Integer Required
serialNumber The serial number of the reserved material item.
id The ID of the reserved material item managed by serial number. String
code The code of the reserved material item managed by serial number. String
externalId The external ID of the reserved material item managedd by serial number. This value must be unique. String
shipped If applicable, the amount of reserved material item that have stated "shipped", i.e. ordered but not yet available for usage. Integer
used The amount of reserved material item/s used during the course of the activity. Integer Required (defaults to 0 if not provided)
warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required
id The ID of the warehouse. String
code The code of the warehouse. String
externalId The external ID of the warehouse. This value must be unique. String
subject The subject of the activty. String Required
address The address of the service call.
city The city in which the service call is located. String
country The country in which the service call is located. String
source The source of the service call address (BUSINESSPARTNER, EQUIPMENT). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration
sourceId The ID associated with the service call address source. String
state The state in which the service call is located. String
street The street in which the service call is located. String
streetNumber The street number associated with the service call street address. String
zipCode The zip code associated with the service call address. String
businessPartner The business partner associated with the service call. A Business Partner general refers to the customer, but may also refer to a vendor, etc. Required
id The business partner ID. String
code The business partner code. String
externalId The external ID associated with the business partner. This value must be unique. String
code The service call code. This code is generated automatically by the system. String
Contact The contact associated with the service call.
id The ID associated with the service call contact. String
code The code associated with the service call contact. String
externalId The external ID associated with the service call contact. This value must be unique. String
createPerson The user responsible for creating the service call/activity. Optional
id The ID associated with the creator of the record. String
code The code associated with the new person record. String
externalId The external ID associated with the new person record. This value must be unique. String
dueDateTime The date/time at which the service call is due to be completed. DateTime
durationInMinutes The duration in minutes the service call is expected to last. Integer
earliestStartDateTime The earliest date/time on which the service call can be completed. DateTime
equipments The equipment record associated with the service call. Optional
id The ID of the equipment record associated with the service call. String
code The code associated with the service call equipment. String
externalId The external ID associated with the service call equipment. This value must be unique. String
externalId The external ID associated wth the service call record. This value must be unique among all serviceCall objects. String
lastChanged The person responsible for last changing the service call record. Integer
origin The origin of the service call (i.e. phone, online, etc). String Optional
priority The priority level associated with the service call (example: high, medium, low). String Required
problemType The problem  type associated with the service call (example: warranty, maintenance, etc.). String
remarks The remarks associated with the service call. String
reservedMaterials The reserved materials associated with the service call.
externalId The external  ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String
id The ID assocaited with the reserved material item. String
item The reserved material item. String Required
id The ID of the reserved material item. String
code The code of the reserved material item. String
externalId The external ID of the reserved material item. String
moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided)
quantity The quantity of reserved material. Integer Required
serialNumber If applicable, the reserved material managed by serial number.
id The ID of the reserved material item managed by serial number. String
code The code of the reserved material item managed by serial number. String
externalId The external ID of the reserved material item managed by serial number. String
shipped The amount of reserved material items with status "shipped"; i.e., ordered but not yet available for usage. Integer
used The amount of reserved material item/s used during the course of the service call. Integer Required (defaults to 0 if not provided)
warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required
id The ID of the warehouse. String
code The code of the warehouse. String
externalId The external ID of the warehouse. String
resolution The resolution status of the service call. String
responsibles The technician/s assigned to the service call.
id The ID associated with the responsibles assigned to the service call. String
code The code associated with the responsible assigned to the service call. String
externalId The external ID associated with the responsible assigned to the service call. String
status The current status of the service call. String Required
subject The subject of the service call. String Required

1.5 GET Service Call and Sub-resources

Get the service call and its sub-resources.

1.5.1 Request

Method URL
GET https://{cluster}.coresystems.net/api/service-management/v2/composite-tree/service-calls/{service-call-uid}

1.5.1.1 URL Parameters

Parameter Description Type Required
{service-call-uid} The unique ID of the service call record created via POST request you wish to retrieve. String Required

1.5.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-Name accountName The name of the account associated with ther request. Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-Name companyName The name of the company associated with the request. Required
X-User-Name userName The user namer. This is required only when using an OAuth token NOT associated with any user. Optional
account accountName Deprecated–will be removed soon. Use the X-Account-Name header instead. Deprecated
company companyName Deprecated, will be removed soon. Use the X-Company-Name header instead. Deprecated

1.5.3 Response

Status Response
200 OK
401 Unauthorized
403 Forbidden
404 Not found

1.5.4 Example Response Body

{
  "activities": [
    {
      "address": {
        "city": "string",
        "country": "string",
        "source": "ACTIVITY",
        "sourceId": "string",
        "state": "string",
        "street": "string",
        "streetNumber": "string",
        "zipCode": "string"
      },
      "code": "string",
      "contact": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "createPerson": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "dueDateTime": "2019-07-05T07:10:57.449Z",
      "durationInMinutes": 0,
      "earliestStartDateTime": "2019-07-05T07:10:57.449Z",
      "equipment": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "externalId": "string",
      "id": "string",
      "lastChanged": 0,
      "plannedEndDate": "2019-07-05T07:10:57.449Z",
      "plannedStartDate": "2019-07-05T07:10:57.449Z",
      "remarks": "string",
      "reservedMaterials": [
        {
          "externalId": "string",
          "id": "string",
          "item": {
            "id": "string",
            "code": "string",
            "externalId": "string"
          },
          "moved": 0,
          "quantity": 0,
          "serialNumber": {
            "id": "string",
            "code": "string",
            "externalId": "string"
          },
          "shipped": 0,
          "used": 0,
          "warehouse": {
            "id": "string",
            "code": "string",
            "externalId": "string"
          }
        }
      ],
      "responsibles": [
        {
          "id": "string",
          "code": "string",
          "externalId": "string"
        }
      ],
      "sourceActivity": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "status": "string",
      "subject": "string",
      "type": "string"
    }
  ],
  "address": {
    "city": "string",
    "country": "string",
    "source": "ACTIVITY",
    "sourceId": "string",
    "state": "string",
    "street": "string",
    "streetNumber": "string",
    "zipCode": "string"
  },
  "businessPartner": {
    "id": "string",
    "code": "string",
    "externalId": "string"
  },
  "code": "string",
  "contact": {
    "id": "string",
    "code": "string",
    "externalId": "string"
  },
  "createPerson": {
    "id": "string",
    "code": "string",
    "externalId": "string"
  },
  "dueDateTime": "2019-07-05T07:10:57.449Z",
  "durationInMinutes": 0,
  "earliestStartDateTime": "2019-07-05T07:10:57.449Z",
  "equipments": [
    {
      "id": "string",
      "code": "string",
      "externalId": "string"
    }
  ],
  "externalId": "string",
  "id": "string",
  "lastChanged": 0,
  "origin": "string",
  "priority": "string",
  "problemType": "string",
  "remarks": "string",
  "reservedMaterials": [
    {
      "externalId": "string",
      "id": "string",
      "item": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "moved": 0,
      "quantity": 0,
      "serialNumber": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "shipped": 0,
      "used": 0,
      "warehouse": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      }
    }
  ],
  "resolution": "string",
  "responsibles": [
    {
      "id": "string",
      "code": "string",
      "externalId": "string"
    }
  ],
  "status": "string",
  "subject": "string",
  "type": "string"
}

1.5.5 Response Values

The following values may be included in a GET Service Call response:

Value Description Type Required
activities If applicable, the activity record/s associated with the serviceCall.
address The activity address.
city The city in which the activity is located. String
country The country in which the activity is located. String
source The source of the activity address (BUSINESSPARTNER, EQUIPMENT, SERVICECALL). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration.
sourceId The ID associated with the activity address source. String
state The state in which the activity is located. String
street The street in which the activity is located. String
streetNumber The streetnumber associated with the activity address. String
zipCode The zip code associated with the actrivity address. String
code The activity code. This value is automatically created by the system. String
contact The contact associated with the activity. String
id The contact ID associated with the activity. String
code The code associated with the activity contact. String
externalId If applicable, the external ID associated with the activity contact. String
createPerson If no record for the contact exists, a new person record will be created.
id The ID associated with the new person record. String
code The code associated with the new person record. String
externalId The external ID associated with the person responsible for creating the record. This value must be unique. String
dueDateTime The date/time at which the activity is due to be completed. DateTime
durationInMinutes The expected duration in minutes of the activity. Integer
earliestStartDate The earlest date on which the activity can occur. DateTime
equipment The equipment record associated with the activity.
id The ID of the equipment record associated with the activitiy. String
code The code of the equipment associated with the activity. String
externalId The external ID of the equipment associated with the activity. This value must be unique. String
externalId The external ID of the activity record. This value must be unique among all activity records. String
lastChanged The person responsible for last changing the record. String
plannedStartDate Read-only. The planned start date. dateTime
plannedEndDate Read-only. The planned end date. dateTime
remarks The  remarks associated with the activity. String
reservedMaterials The reserved materials associated with the activty. Array
externalId The externalId of the reserved material. This value must be unique among all reservedMaterial objects. String
id The ID of the reserved material. String
item The reserved material item. Required
id The ID assocaited with the reserved material item. String
code The code associated with the reserved material item String
externalId The external  ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String
moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided)
quantity The amount of reserved material items used for the activity. Integer Required
serialNumber The serial number of the reserved material item.
id The ID of the reserved material item managed by serial number. String
code The code of the reserved material item managed by serial number. String
externalId The external ID of the reserved material item managedd by serial number. This value must be unique. String
shipped If applicable, the amount of reserved material item that have stated "shipped", i.e. ordered but not yet available for usage. Integer
used The amount of reserved material item/s used during the course of the activity. Integer Required (defaults to 0 if not provided)
warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required
id The ID of the warehouse. String
code The code of the warehouse. String
externalId The external ID of the warehouse. This value must be unique. String
subject The subject of the activty. String Required
address The address of the service call.
city The city in which the service call is located. String
country The country in which the service call is located. String
source The source of the service call address (BUSINESSPARTNER, EQUIPMENT). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration
sourceId The ID associated with the service call address source. String
state The state in which the service call is located. String
street The street in which the service call is located. String
streetNumber The street number associated with the service call street address. String
zipCode The zip code associated with the service call address. String
businessPartner The business partner associated with the service call. A Business Partner general refers to the customer, but may also refer to a vendor, etc. Required
id The business partner ID. String
code The business partner code. String
externalId The external ID associated with the business partner. This value must be unique. String
code The service call code. This code is generated automatically by the system. String
Contact The contact associated with the service call.
id The ID associated with the service call contact. String
code The code associated with the service call contact. String
externalId The external ID associated with the service call contact. This value must be unique. String
createPerson The user responsible for creating the service call/activity. Optional
id The ID associated with the creator of the record. String
code The code associated with the new person record. String
externalId The external ID associated with the new person record. This value must be unique. String
dueDateTime The date/time at which the service call is due to be completed. DateTime
durationInMinutes The duration in minutes the service call is expected to last. Integer
earliestStartDateTime The earliest date/time on which the service call can be completed. DateTime
equipments The equipment record associated with the service call. Optional
id The ID of the equipment record associated with the service call. String
code The code associated with the service call equipment. String
externalId The external ID associated with the service call equipment. This value must be unique. String
externalId The external ID associated wth the service call record. This value must be unique among all serviceCall objects. String
lastChanged The person responsible for last changing the service call record. Integer
origin The origin of the service call (i.e. phone, online, etc). String Optional
priority The priority level associated with the service call (example: high, medium, low). String Required
problemType The problem  type associated with the service call (example: warranty, maintenance, etc.). String
remarks The remarks associated with the service call. String
reservedMaterials The reserved materials associated with the service call.
externalId The external  ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String
id The ID assocaited with the reserved material item. String
item The reserved material item. String Required
id The ID of the reserved material item. String
code The code of the reserved material item. String
externalId The external ID of the reserved material item. String
moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided)
quantity The quantity of reserved material. Integer Required
serialNumber If applicable, the reserved material managed by serial number.
id The ID of the reserved material item managed by serial number. String
code The code of the reserved material item managed by serial number. String
externalId The external ID of the reserved material item managed by serial number. String
shipped The amount of reserved material items with status "shipped"; i.e., ordered but not yet available for usage. Integer
used The amount of reserved material item/s used during the course of the service call. Integer Required (defaults to 0 if not provided)
warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required
id The ID of the warehouse. String
code The code of the warehouse. String
externalId The external ID of the warehouse. String
resolution The resolution status of the service call. String
responsibles The technician/s assigned to the service call.
id The ID associated with the responsibles assigned to the service call. String
code The code associated with the responsible assigned to the service call. String
externalId The external ID associated with the responsible assigned to the service call. String
status The current status of the service call. String Required
subject The subject of the service call. String Required
type The service call type. String

1.6 GET Service Call Activity with Sub-resources

Get an activity and its sub-resources for a service call.

1.6.1 Request

Method URL
GET https://{cluster}.coresystems.net/api/service-management/v2/composite-tree/service-calls/{service-call-uid}/activities/{activiy-uid}

1.6.1.1 URL Parameters

Parameter Description Type Required
{service-call-uid} The unique ID of the service call record created via POST request to which the activity you wish to retrieve belongs. String Required
{activity-uid} The unique ID of the activity created via POST request you wish to retrieve. String Required

1.6.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-Name accountName The name of the account associated with ther request. Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-Name companyName The name of the company associated with the request. Required
X-User-Name userName The user namer. This is required only when using an OAuth token NOT associated with any user. Optional
account accountName Deprecated–will be removed soon. Use the X-Account-Name header instead. Deprecated
company companyName Deprecated, will be removed soon. Use the X-Company-Name header instead. Deprecated

1.6.4 Response

Status Response
200 OK
401 Unauthorized
403 Forbidden
404 Not found

1.6.5 Example Response Body

{
  "address": {
    "city": "string",
    "country": "string",
    "source": "ACTIVITY",
    "sourceId": "string",
    "state": "string",
    "street": "string",
    "streetNumber": "string",
    "zipCode": "string"
  },
  "code": "string",
  "contact": {
    "id": "string",
    "code": "string",
    "externalId": "string"
  },
  "createPerson": {
    "id": "string",
    "code": "string",
    "externalId": "string"
  },
  "dueDateTime": "2019-07-05T07:16:39.112Z",
  "durationInMinutes": 0,
  "earliestStartDateTime": "2019-07-05T07:16:39.112Z",
  "equipment": {
    "id": "string",
    "code": "string",
    "externalId": "string"
  },
  "externalId": "string",
  "id": "string",
  "lastChanged": 0,
  "plannedEndDate": "2019-07-05T07:16:39.112Z",
  "plannedStartDate": "2019-07-05T07:16:39.112Z",
  "remarks": "string",
  "reservedMaterials": [
    {
      "externalId": "string",
      "id": "string",
      "item": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "moved": 0,
      "quantity": 0,
      "serialNumber": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      },
      "shipped": 0,
      "used": 0,
      "warehouse": {
        "id": "string",
        "code": "string",
        "externalId": "string"
      }
    }
  ],
  "responsibles": [
    {
      "id": "string",
      "code": "string",
      "externalId": "string"
    }
  ],
  "sourceActivity": {
    "id": "string",
    "code": "string",
    "externalId": "string"
  },
  "status": "string",
  "subject": "string",
  "type": "string"
}

1.6.6 Response Values

Value Description Type Required
activities If applicable, the activity record/s associated with the serviceCall.
address The activity address.
city The city in which the activity is located. String
country The country in which the activity is located. String
source The source of the activity address (BUSINESSPARTNER, EQUIPMENT, SERVICECALL). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration.
sourceId The ID associated with the activity address source. String
state The state in which the activity is located. String
street The street in which the activity is located. String
streetNumber The streetnumber associated with the activity address. String
zipCode The zip code associated with the actrivity address. String
code The activity code. This value is automatically created by the system. String
contact The contact associated with the activity. String
id The contact ID associated with the activity. String
code The code associated with the activity contact. String
externalId If applicable, the external ID associated with the activity contact. String
createPerson If no record for the contact exists, a new person record will be created.
id The ID associated with the new person record. String
code The code associated with the new person record. String
externalId The external ID associated with the person responsible for creating the record. This value must be unique. String
dueDateTime The date/time at which the activity is due to be completed. DateTime
durationInMinutes The expected duration in minutes of the activity. Integer
earliestStartDate The earlest date on which the activity can occur. DateTime
equipment The equipment record associated with the activity.
id The ID of the equipment record associated with the activitiy. String
code The code of the equipment associated with the activity. String
externalId The external ID of the equipment associated with the activity. This value must be unique. String
externalId The external ID of the activity record. This value must be unique among all activity records. String
lastChanged The person responsible for last changing the record. String
remarks The  remarks associated with the activity. String
reservedMaterials The reserved materials associated with the activty. Array
externalId The externalId of the reserved material. This value must be unique among all reservedMaterial objects. String
id The ID of the reserved material. String
item The reserved material item. Required
id The ID assocaited with the reserved material item. String
code The code associated with the reserved material item String
externalId The external  ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String
moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided)
quantity The amount of reserved material items used for the activity. Integer Required
serialNumber The serial number of the reserved material item.
id The ID of the reserved material item managed by serial number. String
code The code of the reserved material item managed by serial number. String
externalId The external ID of the reserved material item managedd by serial number. This value must be unique. String
shipped If applicable, the amount of reserved material item that have stated "shipped", i.e. ordered but not yet available for usage. Integer
used The amount of reserved material item/s used during the course of the activity. Integer Required (defaults to 0 if not provided)
warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required
id The ID of the warehouse. String
code The code of the warehouse. String
externalId The external ID of the warehouse. This value must be unique. String
subject The subject of the activty. String Required
address The address of the service call.
city The city in which the service call is located. String
country The country in which the service call is located. String
source The source of the service call address (BUSINESSPARTNER, EQUIPMENT). This is a temporary address that was resolved using the address resolution logic. The source field will indicate from which object the address is coming from. Enumeration
sourceId The ID associated with the service call address source. String
state The state in which the service call is located. String
street The street in which the service call is located. String
streetNumber The street number associated with the service call street address. String
zipCode The zip code associated with the service call address. String
businessPartner The business partner associated with the service call. A Business Partner general refers to the customer, but may also refer to a vendor, etc. Required
id The business partner ID. String
code The business partner code. String
externalId The external ID associated with the business partner. This value must be unique. String
code The service call code. This code is generated automatically by the system. String
Contact The contact associated with the service call.
id The ID associated with the service call contact. String
code The code associated with the service call contact. String
externalId The external ID associated with the service call contact. This value must be unique. String
createPerson The user responsible for creating the service call/activity. Optional
id The ID associated with the creator of the record. String
code The code associated with the new person record. String
externalId The external ID associated with the new person record. This value must be unique. String
dueDateTime The date/time at which the service call is due to be completed. DateTime
durationInMinutes The duration in minutes the service call is expected to last. Integer
earliestStartDateTime The earliest date/time on which the service call can be completed. DateTime
equipments The equipment record associated with the service call. Optional
id The ID of the equipment record associated with the service call. String
code The code associated with the service call equipment. String
externalId The external ID associated with the service call equipment. This value must be unique. String
externalId The external ID associated wth the service call record. This value must be unique among all serviceCall objects. String
lastChanged The person responsible for last changing the service call record. Integer
origin The origin of the service call (i.e. phone, online, etc). String Optional
priority The priority level associated with the service call (example: high, medium, low). String Required
problemType The problem  type associated with the service call (example: warranty, maintenance, etc.). String
remarks The remarks associated with the service call. String
reservedMaterials The reserved materials associated with the service call.
externalId The external  ID associated with the reserved material item. This value must be unique among all reservedMaterial objects. String
id The ID assocaited with the reserved material item. String
item The reserved material item. String Required
id The ID of the reserved material item. String
code The code of the reserved material item. String
externalId The external ID of the reserved material item. String
moved The amount of reserved materials that have been moved from one warehouse to another. Integer Required (defaults to 0 if not provided)
quantity The quantity of reserved material. Integer Required
serialNumber If applicable, the reserved material managed by serial number.
id The ID of the reserved material item managed by serial number. String
code The code of the reserved material item managed by serial number. String
externalId The external ID of the reserved material item managed by serial number. String
shipped The amount of reserved material items with status "shipped"; i.e., ordered but not yet available for usage. Integer
used The amount of reserved material item/s used during the course of the service call. Integer Required (defaults to 0 if not provided)
warehouse The warehouse in which the reserved material/s are stored. A warehouse may also refer to the technician vehicle. Required
id The ID of the warehouse. String
code The code of the warehouse. String
externalId The external ID of the warehouse. String
resolution The resolution status of the service call. String
responsibles The technician/s assigned to the service call.
id The ID associated with the responsibles assigned to the service call. String
code The code associated with the responsible assigned to the service call. String
externalId The external ID associated with the responsible assigned to the service call. String
status The current status of the service call. String Required
subject The subject of the service call. String Required

1.7 Bulk Create Service Calls

Bulk creation of service calls with optional activities.

1.7.1 Request

Method URL
POST https://{cluster}.coresystems.net/api/v2/composite-bulk/service-calls

1.7.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-Name accountName The name of the account associated with ther request. Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-Name companyName The name of the company associated with the request. Required
X-User-Name userName The user namer. This is required only when using an OAuth token NOT associated with any user. Optional
account accountName Deprecated–will be removed soon. Use the X-Account-Name header instead. Deprecated
company companyName Deprecated, will be removed soon. Use the X-Company-Name header instead. Deprecated

1.7.3 Query Parameters

Query Parameter Value Description
autoCreateActivity true / false Optional. Default value = true. When true, a default activity record will be created, if no activity has been provided explicitly.

1.7.4 Request Body

A Bulk service call creation POST request contains an array of service calls.

The values in a service call record contained in a bulk POST request are the same as those listed in section 1.3.4.


1.7.5 Response

Status Response
201 Created
207 Request succeeded
401 Unauthorized
403 Forbidden
404 Not Found

1.7.6 Example Response Body

The following is an example response for a request that returns a HTTP 207 response:

{
  "hasErrors": true,
  "results": [
    {
       // service call
    },
    {
       // another service call
    }
  ]
}

1.8 Bulk Update Service Calls

Bulk update multiple serviceCall records and optional activities.

Note The conditions required for a Bulk PATCH request are the same as those listed in section 1.4.


1.8.1 Request

Method URL
PATCH https://{cluster}.coresystems.net/api/service-management/v2/composite-bulk/service-calls

1.8.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-Name accountName The name of the account associated with ther request. Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-Name companyName The name of the company associated with the request. Required
X-User-Name userName The user namer. This is required only when using an OAuth token NOT associated with any user. Optional
account accountName Deprecated–will be removed soon. Use the X-Account-Name header instead. Deprecated
company companyName Deprecated, will be removed soon. Use the X-Company-Name header instead. Deprecated

1.8.3 Request Body

The values contained in a bulk PATCH request are the same as those listed in section 1.4.3.


1.8.5 Response

Status Response
201 Created
207 Request succeeded
401 Unauthorized
403 Forbidden
404 Not Found

1.8.6 Example Response Body

The following is an example response for a request that returns a HTTP 207 response:

{
  "hasErrors": true,
  "results": [
    {
       // service call
    },
    {
       // another service call
    }
  ]
}

Appendix

Relevant Data Transfer Objects

ActivityResponse DTO

ActivityResponse {
    address Address {
        city string
        country string
        source string
        Enum:
            Array[14]
        sourceId string
        state string
        street string
        streetNumber string
        zipCode string
    }
    code string
    contact UnifiedIdentifier {
        id string
        code string
        externalId string
    }
    createPerson UnifiedIdentifier {
        id string
        code string
        externalId string
    }
    dueDateTime string($date - time)
    durationInMinutes integer($int32)
    earliestStartDateTime string($date - time)
    equipment UnifiedIdentifier {
        id string
        code string
        externalId string
    }
    externalId string
    id string
    lastChanged integer($int64)
    remarks string
    reservedMaterials[
        ReservedMaterial {
            externalId string
            id string
            item UnifiedIdentifier {
                id string
                code string
                externalId string
            }
            moved number
            quantity number
            serialNumber UnifiedIdentifier {
                id string
                code string
                externalId string
            }
            shipped number
            used number
            warehouse UnifiedIdentifier {
                id string
                code string
                externalId string
            }
        }
    ] responsibles[
        UnifiedIdentifier {
            id string
            code string
            externalId string
        }
    ] status string
    subject string
}

Address DTO

Address {
    city string
    country string
    source string
            Enum: Array[14]
    sourceId string
    state string
    street string
    streetNumber string
    zipCode string
}

CreateActivityRequest DTO

CreateActivityRequest {
    address Address {
        city string
        country string
        source string
                Enum: Array[14]
        sourceId string
        state string
        street string
        streetNumber string
        zipCode string
    }
    code string
    contact UnifiedIdentifier {
        id string
        code string
        externalId string
    }
    createPerson UnifiedIdentifier {
        id string
        code string
        externalId string
    }
    dueDateTime string($date - time)
    durationInMinutes integer($int32)
    earliestStartDateTime string($date - time)
    equipment UnifiedIdentifier {
        id string
        code string
        externalId string
    }
    externalId string
    lastChanged integer($int64)
    remarks string
    reservedMaterials[ReservedMaterial {
        externalId string
        id string
        item UnifiedIdentifier {
            id string
            code string
            externalId string
        }
        moved number
        quantity number
        serialNumber UnifiedIdentifier {
            id string
            code string
            externalId string
        }
        shipped number
        used number
        warehouse UnifiedIdentifier {
            id string
            code string
            externalId string
        }
    }]
    subject string
}

CreateServiceCallRequest DTO

CreateServiceCallRequest {
    activities[CreateActivityRequest {
        address Address {
            city string
            country string
            source stringEnum: [ACTIVITY, ADDRESS, BUSINESSPARTNER, CONTACT, EQUIPMENT, PERSON, SERVICECALL, SERVICECALLORIGIN, SERVICECALLSTATUS, SERVICECALLPROBLEMTYPE, RESERVEDMATERIAL, WAREHOUSE, ITEM, SERIALNUMBER]
            sourceId string
            state string
            street string
            streetNumber string
            zipCode string
        }
        code string
        contact UnifiedIdentifier {
            id string
            code string
            externalId string
        }
        createPerson UnifiedIdentifier {
            id string
            code string
            externalId string
        }
        dueDateTime string($date - time)
        durationInMinutes integer($int32)
        earliestStartDateTime string($date - time)
        equipment UnifiedIdentifier {
            id string
            code string
            externalId string
        }
        externalId string
        lastChanged integer($int64)
        remarks string
        reservedMaterials[ReservedMaterial {
            externalId string
            id string
            item UnifiedIdentifier {
                id string
                code string
                externalId string
            }
            moved number
            quantity number
            serialNumber UnifiedIdentifier {
                id string
                code string
                externalId string
            }
            shipped number
            used number
            warehouse UnifiedIdentifier {
                id string
                code string
                externalId string
            }
        }]
        subject string
    }]
    address Address {
        city string
        country string
        source stringEnum: [ACTIVITY, ADDRESS, BUSINESSPARTNER, CONTACT, EQUIPMENT, PERSON, SERVICECALL, SERVICECALLORIGIN, SERVICECALLSTATUS, SERVICECALLPROBLEMTYPE, RESERVEDMATERIAL, WAREHOUSE, ITEM, SERIALNUMBER]
        sourceId string
        state string
        street string
        streetNumber string
        zipCode string
    }
    businessPartner UnifiedIdentifier {
        id string
        code string
        externalId string
    }
    code string
    contact UnifiedIdentifier {
        id string
        code string
        externalId string
    }
    createPerson UnifiedIdentifier {
        id string
        code string
        externalId string
    }
    dueDateTime string($date - time)
    durationInMinutes integer($int32)
    earliestStartDateTime string($date - time)
    equipments[UnifiedIdentifier {
        id string
        code string
        externalId string
    }]
    externalId string
    lastChanged integer($int64)
    origin string
    priority string
    problemType string
    remarks string
    reservedMaterials[ReservedMaterial {
        externalId string
        id string
        item UnifiedIdentifier {
            id string
            code string
            externalId string
        }
        moved number
        quantity number
        serialNumber UnifiedIdentifier {
            id string
            code string
            externalId string
        }
        shipped number
        used number
        warehouse UnifiedIdentifier {
            id string
            code string
            externalId string
        }
    }]
    resolution string
    responsibles[UnifiedIdentifier {
        id string
        code string
        externalId string
    }]
    status string
    subject string
}

ReservedMaterial DTO

ReservedMaterial {
    externalId string
    id string
    item UnifiedIdentifier {
        id string
        code string
        externalId string
    }
    moved number
    quantity number
    serialNumber UnifiedIdentifier {
        id string
        code string
        externalId string
    }
    shipped number
    used number
    warehouse UnifiedIdentifier {
        id string
        code string
        externalId string
    }
}

ResponseEntity DTO

ResponseEntity {
    body {}
    status {}
    statusCode string
    Enum: [100 CONTINUE, 101 SWITCHING_PROTOCOLS, 102 PROCESSING, 103 CHECKPOINT, 200 OK, 201 CREATED, 202 ACCEPTED, 203 NON_AUTHORITATIVE_INFORMATION, 204 NO_CONTENT, 205 RESET_CONTENT, 206 PARTIAL_CONTENT, 207 MULTI_STATUS, 208 ALREADY_REPORTED, 226 IM_USED, 300 MULTIPLE_CHOICES, 301 MOVED_PERMANENTLY, 302 FOUND, 302 MOVED_TEMPORARILY, 303 SEE_OTHER, 304 NOT_MODIFIED, 305 USE_PROXY, 307 TEMPORARY_REDIRECT, 308 PERMANENT_REDIRECT, 400 BAD_REQUEST, 401 UNAUTHORIZED, 402 PAYMENT_REQUIRED, 403 FORBIDDEN, 404 NOT_FOUND, 405 METHOD_NOT_ALLOWED, 406 NOT_ACCEPTABLE, 407 PROXY_AUTHENTICATION_REQUIRED, 408 REQUEST_TIMEOUT, 409 CONFLICT, 410 GONE, 411 LENGTH_REQUIRED, 412 PRECONDITION_FAILED, 413 PAYLOAD_TOO_LARGE, 413 REQUEST_ENTITY_TOO_LARGE, 414 URI_TOO_LONG, 414 REQUEST_URI_TOO_LONG, 415 UNSUPPORTED_MEDIA_TYPE, 416 REQUESTED_RANGE_NOT_SATISFIABLE, 417 EXPECTATION_FAILED, 418 I_AM_A_TEAPOT, 419 INSUFFICIENT_SPACE_ON_RESOURCE, 420 METHOD_FAILURE, 421 DESTINATION_LOCKED, 422 UNPROCESSABLE_ENTITY, 423 LOCKED, 424 FAILED_DEPENDENCY, 426 UPGRADE_REQUIRED, 428 PRECONDITION_REQUIRED, 429 TOO_MANY_REQUESTS, 431 REQUEST_HEADER_FIELDS_TOO_LARGE, 451 UNAVAILABLE_FOR_LEGAL_REASONS, 500 INTERNAL_SERVER_ERROR, 501 NOT_IMPLEMENTED, 502 BAD_GATEWAY, 503 SERVICE_UNAVAILABLE, 504 GATEWAY_TIMEOUT, 505 HTTP_VERSION_NOT_SUPPORTED, 506 VARIANT_ALSO_NEGOTIATES, 507 INSUFFICIENT_STORAGE, 508 LOOP_DETECTED, 509 BANDWIDTH_LIMIT_EXCEEDED, 510 NOT_EXTENDED, 511 NETWORK_AUTHENTICATION_REQUIRED]
    statusCodeValue integer($int32)
}

ServiceCallResponse DTO

ServiceCallResponse {
    activities[ActivityResponse {
        address Address {
            city string
            country string
            source stringEnum: [ACTIVITY, ADDRESS, BUSINESSPARTNER, CONTACT, EQUIPMENT, PERSON, SERVICECALL, SERVICECALLORIGIN, SERVICECALLSTATUS, SERVICECALLPROBLEMTYPE, RESERVEDMATERIAL, WAREHOUSE, ITEM, SERIALNUMBER]
            sourceId string
            state string
            street string
            streetNumber string
            zipCode string
        }
        code string
        contact UnifiedIdentifier {
            id string
            code string
            externalId string
        }
        createPerson UnifiedIdentifier {
            id string
            code string
            externalId string
        }
        dueDateTime string($date - time)
        durationInMinutes integer($int32)
        earliestStartDateTime string($date - time)
        equipment UnifiedIdentifier {
            id string
            code string
            externalId string
        }
        externalId string
        id string
        lastChanged integer($int64)
        remarks string
        reservedMaterials[ReservedMaterial {
            externalId string
            id string
            item UnifiedIdentifier {
                id string
                code string
                externalId string
            }
            moved number
            quantity number
            serialNumber UnifiedIdentifier {
                id string
                code string
                externalId string
            }
            shipped number
            used number
            warehouse UnifiedIdentifier {
                id string
                code string
                externalId string
            }
        }]
        responsibles[UnifiedIdentifier {
            id string
            code string
            externalId string
        }]
        status string
        subject string
    }]
    address Address {
        city string
        country string
        source stringEnum: [ACTIVITY, ADDRESS, BUSINESSPARTNER, CONTACT, EQUIPMENT, PERSON, SERVICECALL, SERVICECALLORIGIN, SERVICECALLSTATUS, SERVICECALLPROBLEMTYPE, RESERVEDMATERIAL, WAREHOUSE, ITEM, SERIALNUMBER]
        sourceId string
        state string
        street string
        streetNumber string
        zipCode string
    }
    businessPartner UnifiedIdentifier {
        id string
        code string
        externalId string
    }
    code string
    contact UnifiedIdentifier {
        id string
        code string
        externalId string
    }
    createPerson UnifiedIdentifier {
        id string
        code string
        externalId string
    }
    dueDateTime string($date - time)
    durationInMinutes integer($int32)
    earliestStartDateTime string($date - time)
    equipments[UnifiedIdentifier {
        id string
        code string
        externalId string
    }]
    externalId string
    id string
    lastChanged integer($int64)
    origin string
    priority string
    problemType string
    remarks string
    reservedMaterials[ReservedMaterial {
        externalId string
        id string
        item UnifiedIdentifier {
            id string
            code string
            externalId string
        }
        moved number
        quantity number
        serialNumber UnifiedIdentifier {
            id string
            code string
            externalId string
        }
        shipped number
        used number
        warehouse UnifiedIdentifier {
            id string
            code string
            externalId string
        }
    }]
    resolution string
    responsibles[UnifiedIdentifier {
        id string
        code string
        externalId string
    }]
    status string
    subject string
}

UnifiedIdentifier DTO

UnifiedIdentifier{
id	string
code	string
externalId	string
}