Crowd Technician API

1.1 Overview

The Crowd Technician API enables crowd owner with external systems to make requests from a third-party application to SAP Field Service Management, where they can create and manage the Crowd technicians who accept assignments and complete work as part of the SAP Field Service Management Crowd platform.

For more information on the SAP Field Service Management Crowd platform, please refer to the following documentation:

Crowd


1.1.1 Request Methods

The following methods are supported by the Crowd Technician API:

  Method Description Section
1.1.0.1 POST Create a new crowd techician with skills. 1.3
1.1.0.2 PUT Update an existing crowd technician and/or skills. 1.4
1.1.0.1 GET Retrieve information on a specific crowd technician. 1.5
1.1.0.2 GET Retrieve information on all crowd techicians. 1.6
1.1.0.5 DELETE Delete an existing crowd technician record. 1.7

1.1.2 Crowd Business Partner API in Swagger

The Swagger specification for the Crowd Business Partner API can be accessed here.


1.2 Access

The Crowd Technician 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, requests will be made to one of the following server clusters:

  • EU
  • DE
  • US

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

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

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

https://{cluster}.coresystems.net/cloud-crowd-service/api/crowd/v1/technicians/


1.3 Create New Crowd Technician

Create a new crowd technician with skills.

1.3.1 Request

Method URL
POST https://{cluster}.coresystems.net/cloud-crowd-service/api/crowd/v1/technicians/

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

1.3.3 Body

Value     Description Type Required
firstName     The first name of the crowd technician. String Required
lastName          
email     The email address of the crowd technician. String Required
externalId          
  uuid   The unique identifier associated with the crowd technician. This value is automatically generated by the cloud in the response and can be used in other requests. String Automatically generated by cloud and displayed in response.
id     The ID associated with the crowd technician. String Required
mobilePhone     The mobile phone number of the crowd technician. String Required
Skills       Array  
  expiredAt   If applicable, the dateTime at which the skill expires. dateTime  
  id   The id of the skill. String Required
  status   The current status of the skill. String  
  tagExternalID        
    uuid The unique identifier associated with the skill. This value is automatically generated by the cloud in the response and can be used in other requests. String Automatically generated by cloud and displayed in response.
  technicianId   The ID of the technician for whom the skill has been assigned. String Required

1.3.4 Example Request

The following is an example of a new crowd technician created via POST request:

{
  "email": "string",
  "externalId": {
    "uuid": "string"
  },
  "firstName": "string",
  "id": "string",
  "lastName": "string",
  "mobilePhone": "string",
  "skills": [
    {
      "expiredAt": "string",
      "id": "string",
      "status": "can be reached via GET /api/crowd/v1/skill-statuses",
      "tagExternalId": {
        "uuid": "string"
      },
      "tagId": "string",
      "technicianExternalId": {
        "uuid": "string"
      },
      "technicianId": "string"
    }
  ]
}

1.3.5 Response

Status Response
201 Created
401 Unauthorized
403 Forbidden
404 Not Found

1.3.6 Example Response

{
  "email": "string",
  "externalId": {
    "uuid": "string"
  },
  "firstName": "string",
  "id": "string",
  "lastName": "string",
  "mobilePhone": "string",
  "skills": [
    {
      "expiredAt": "string",
      "id": "string",
      "status": "can be reached via GET /api/crowd/v1/skill-statuses",
      "tagExternalId": {
        "uuid": "string"
      },
      "tagId": "string",
      "technicianExternalId": {
        "uuid": "string"
      },
      "technicianId": "string"
    }
  ]
}

1.4 Update Crowd Technician

Update an existing crowd technician record and/or crowd technician skills.

1.4.1 Request

Method URL
PUT https://{cluster}.coresystems.net/cloud-crowd-service/api/crowd/v1/technicians/{id}

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

1.4.3 URL Paramters

Parameter Description Type Required
id The uuid of the crowd technician record you wish to update. String Required

1.4.4 Body

Value     Description Type Required
firstName     The first name of the crowd technician. String Required
lastName          
email     The email address of the crowd technician. String Required
externalId          
  uuid   The unique identifier associated with the crowd technician. This value is automatically generated by the cloud in the response and can be used in other requests. String Automatically generated by cloud and displayed in response.
id     The ID associated with the crowd technician. String Required
mobilePhone     The mobile phone number of the crowd technician. String Required
Skills       Array  
  expiredAt   If applicable, the dateTime at which the skill expires. dateTime  
  id   The id of the skill. String Required
  status   The current status of the skill. String  
  tagExternalID        
    uuid The unique identifier associated with the skill. This value is automatically generated by the cloud in the response and can be used in other requests. String Automatically generated by cloud and displayed in response.
  technicianId   The ID of the technician for whom the skill has been assigned. String Required

1.4.5 Example Body

{
  "email": "string",
  "externalId": {
    "uuid": "string"
  },
  "firstName": "string",
  "id": "string",
  "lastName": "string",
  "mobilePhone": "string",
  "skills": [
    {
      "expiredAt": "string",
      "id": "string",
      "status": "can be reached via GET /api/crowd/v1/skill-statuses",
      "tagExternalId": {
        "uuid": "string"
      },
      "tagId": "string",
      "technicianExternalId": {
        "uuid": "string"
      },
      "technicianId": "string"
    }
  ]
}

1.4.4 Response

Status Response
200 OK
201 Created
202 Accepted
400 Bad Request
409 Conflict
500 Internal Server Error

1.5 GET Information on a Specific Crowd Technician

Retrieve information for a specific crowd technician.

1.5.1 Request

Method URL
GET https://{cluster}.coresystems.net/cloud-crowd-service/api/crowd/v1/technicians/{id}

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

1.5.3 URL Parameters

Parameter Type Description Required
ID String The uuid of the crowd technician for which you wish to retrieve information. Required

1.5.4 Response

Status Response
200 OK
401 Unauthorized
403 Forbidden
404 Not Found

1.5.5 Example Response

{
  "email": "string",
  "externalId": {
    "uuid": "string"
  },
  "firstName": "string",
  "id": "string",
  "lastName": "string",
  "mobilePhone": "string",
  "skills": [
    {
      "expiredAt": "string",
      "id": "string",
      "status": "can be reached via GET /api/crowd/v1/skill-statuses",
      "tagExternalId": {
        "uuid": "string"
      },
      "tagId": "string",
      "technicianExternalId": {
        "uuid": "string"
      },
      "technicianId": "string"
    }
  ]
}

1.6 GET Information on All Crowd Technicians

Retrieve information on all crowd technicians.

1.6.1 Request

Method URL
GET https://{cluster}.coresystems.net/cloud-crowd-service/api/crowd/v1/technicians/

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

1.6.3 Query Parameters

Parameter Type Description Required
Page Integer The amount of results per page you wish to return.  
Size Integer The number of records per page you wish to return .  
Offset Integer The offset to be taken according to the page count and page size  
Sort Array of strings Sorting critera in the format: property (ascidesc). Default sort order is ascending. Multiple sort criteria are supported.  

1.6.4 Body Example

{
  "content": [
    {
      "email": "string",
      "externalId": {
        "uuid": "string"
      },
      "firstName": "string",
      "id": "string",
      "lastName": "string",
      "mobilePhone": "string",
      "skills": [
        {
          "expiredAt": "string",
          "id": "string",
          "status": "can be reached via GET /api/crowd/v1/skill-statuses",
          "tagExternalId": {
            "uuid": "string"
          },
          "tagId": "string",
          "technicianExternalId": {
            "uuid": "string"
          },
          "technicianId": "string"
        }
      ]
    }
  ],
  "empty": true,
  "first": true,
  "last": true,
  "number": 0,
  "numberOfElements": 0,
  "pageable": {
    "offset": 0,
    "pageNumber": 0,
    "pageSize": 0,
    "paged": true,
    "sort": {
      "empty": true,
      "sorted": true,
      "unsorted": true
    },
    "unpaged": true
  },
  "size": 0,
  "sort": {
    "empty": true,
    "sorted": true,
    "unsorted": true
  },
  "totalElements": 0,
  "totalPages": 0
}

1.6.5 Response

Status Response
200 OK
401 Unauthorized
403 Forbidden
404 Not Found

177 Delete Crowd Technician

Delete an existing crowd technician record.

1.7.1 Request

Method URL
DELETE https://{cluster}.coresystems.net/cloud-crowd-service/api/crowd/v1/technicians/{id}

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

1.7.3 URL Parameters

Parameter Description Type Required
id The uuid of the crowd technician record you wish to delete. String Required

1.7.4 Response

Status Response
200 OK
202 Accepted
204 No Content
401 Unauthorized
403 Forbidden