Crowd Partner API

1.1 Overview

The Crowd Partner API enables crowd owner with external systems to make requests from a third-party application to SAP Field Service Management, where they can invite partners to join 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 Partner API:

  Method Description Section
1.1.0.1 POST Create a secure hash for a Crowd partner. 1.3
1.1.0.2 GET Retreieve a Crowd partner secure hash. 1.4
1.1.0.3 GET Retrieve information on all Crowd partners and related sub-resources. 1.5
1.1.0.4 GET Retrieve Crowd partner address. 1.6
1.1.0.5 GET Retrieve crowd partner contact 1.7
1.1.0.6 GET Retrieve Crowd partner service area. 1.8
1.1.0.7 POST Create a new Crowd partner with optional sub-resources. 1.9
1.1.0.8 PUT Update an existing Crowd partner and sub-resources. 1.10

1.1.2 Crowd partner API in Swagger

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


1.2 Access

The Crowd Partner 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 SAP 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@coresuite.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 Partner API as follows:

https://{cluster}.coresuite.net/cloud-crowd-service/api/crowd-partner/v1/


1.3 POST Crowd Partner Secure Hash

Create a new Crowd partner secure hash.

ATTENTION: The secure hash is a required header for Crowd Partner POST requests (refer to section 1.9).

1.3.1 Request

Method URL
POST https://{cluster}.coresuite.com/api/crowd-partner/v1/partners/secure-hash

1.3.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-ID accountId The account identifier. Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-Id companyId The company identfier. Required

1.3.3 Body

No body is included in a secure hash POST request.


1.3.4 Response

The following is an example of a new Crowd partner secure hash created via POST request:

Value Description Type
accountId The ID of the account associated with the secure hash. String
companyId The ID of the company associated with the secure hash. String
secureHash The secure hash for the account/company. This is used in POST and PUT requests to create and updated Crowd partners. String

1.3.5 Example Response

{
  "results": [
    {
      "accountId": 912345,
      "companyId": 127534,
      "secureHash": "eb581c4d-1eec-4200-af60-ae7be2f01a98"
    }
  ]
}

1.3.6 Response Codes

Status Response
201 Created
401 Unauthorized
403 Forbidden
404 Not Found

1.4 GET Crowd Partner Secure Hash

Retrieve a Crowd partner secure hash that was previously created.

ATTENTION: The secure hash is a required header for Crowd Partner POST and PUT requests.


1.4.1 Request

Method URL
GET https://{cluster}.coresuite.com/api/crowd-partner/v1/partners/secure-hash

1.4.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-ID accountId The account identifier. Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-Id companyId The company identfier. Required

1.4.3 Response

The following are the values returned in a secure hash GET request:

Value Description Type
accountId The ID of the account associated with the secure hash. String
companyId The ID of the company associated with the secure hash. String
secureHash The secure hash for the account/company. This is used in POST and PUT requests to create and update Crowd partners. String

1.4.4 Example Response

{
  "results": [
    {
      "accountId": 912345,
      "companyId": 127534,
      "secureHash": "eb581c4d-1eec-4200-af60-ae7be2f01a98"
    }
  ]
}

1.4.5 Response Codes

Status Response
201 Created
401 Unauthorized
403 Forbidden
404 Not Found

1.5 GET Information on All Crowd partners

Retrieve information on all Crowd partners.

1.5.1 Request

Method URL
GET https://{cluster}.coresuite.net/api/crowd-partner/v1/partners

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
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.5.4 Response Example

{
  "results": [
    {
      "id": "59052728e6434a598d1ff9965637ec1e",
      "name": "Coresystems Partner Solutions"
    }
  ]
}

1.5.5 Response

Status Response
200 OK
401 Unauthorized
403 Forbidden
404 Not Found

1.6 GET Crowd Partner Address

Retrieve address for Crowd partner.

1.6.1 Request

Method URL
GET https://{cluster}.coresuite.net/api/crowd-partner/v1/partners/{partner-id}/addresses

1.6.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-ID accountId The account identifier Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-Id companyId The company identfier Required

1.6.3 URL Parameters

URL Parameter Value Description Required
partner-id partnerId The Crowd partner identifier. Required

1.6.4 Response Values

Value Description Type
city The city associated with the address. String
country The country associated with the address. String
id The address identifier. String
number The street number associated with the address. Integer
streetName The street name associated with the address. String
zipCode The zip code associated with the address. Integer

1.6.5 Example Response

{
  "results": [
    {
      "city": "Munich",
      "country": "Germany",
      "id": "59052728e6434a598d1ff9965637ec1e",
      "number": 15,
      "streetName": "Rosenheimer Strasse",
      "zipCode": 81667
    }
  ]
}

1.6.6 Response Codes

Status Response
200 OK
401 Unauthorized
403 Forbidden
404 Not Found

1.7 GET Crowd Partner Contact

Retrieve a Crowd partner contact.

1.7.1 Request

Method URL
GET https://{cluster}.coresuite.net/api/crowd-partner/v1/partners/{partner-id}/contacts

1.6.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-ID accountId The account identifier Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-Id companyId The company identfier Required

1.7.3 URL Parameters

URL Parameter Value Description Required
partner-id partnerId The Crowd partner identifier. Required

1.7.4 Response Values

Value Description Type
emailAddress The email address of the Crowd partner contact. String
firstName The first name of the Crowd partner contact String
id The Crowd partner contact identifier. String
lastName The last name of the Crowd partner contact. String
phoneNumber The Crowd partner contact phone number. String
role The role of the crowd partner contact (example: PARTNER ADMIN). String

1.7.5 Example Response

{
  "results": [
    {
      "emailAddress": "john.smith@coresystems-partner.com",
      "firstName": "John",
      "id": "59052728e6434a598d1ff9965637ec1e",
      "lastName": "Smith",
      "phoneNumber": "+1234567890",
      "role": "PARTNER_ADMIN"
    }
  ]
}

1.7.6 Response Codes

Status Response
200 OK
401 Unauthorized
403 Forbidden
404 Not Found

1.8 GET Crowd Partner Service Area

Retrieve a Crowd partner service area.

1.8.1 Request

Method URL
GET https://{cluster}.coresuite.net/api/crowd-partner/v1/partners/{partner-id}/service-areas

1.8.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-ID accountId The account identifier Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-Id companyId The company identfier Required

1.8.3 URL Parameters

URL Parameter Value Description Required
partner-id partnerId The Crowd partner identifier. Required

1.8.4 Response

Value   Description Type
googlePlaceId   The google place ID associated with the service area center point. String
id   The identifier associated with the service area record. String
latitude   The latitude of the service area center point. Integer
longitude   The longitude of the service area center point Integer
radius   The service area readius.  
  unit The unit of measure associated with the service area radius (example: km; mi). String
  value The value associated with the service area radius (example: 10). Integer

1.8.5 Example Response

{
  "results": [
    {
      "googlePlaceId": "ChIJrTLr-GyuEmsRBfy61i59si0",
      "id": "eb581c4d-1eec-4200-af60-ae7be2f01a98",
      "latitude": 48.137154,
      "longitude": 11.576124,
      "radius": {
        "unit": "mi",
        "value": 15.5
      }
    }
  ]
}

1.8.6 Response Codes

Status Response
200 OK
401 Unauthorized
403 Forbidden
404 Not Found

1.9 POST Crowd Partner with Sub-resources

Create a new Crowd partner record with optional sub-resources (address, contact, service area).

1.9.1 Request

Method URL
POST https://{cluster}.coresuite.com/api/crowd-partner/v1/dispatch/accept

1.9.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-ID accountId The account identifier Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-Id companyId The company identfier Required
X-Secure-Hash secureHash The secure hash generated via POST request to the Crowd Partner secure hash endpoint. For more information, please refer to section 1.3. Required

1.9.3 Body

Value     Description Type
address     The address information of the Crowd partner.  
  city   The city associated with the address. String
  country   The country associated with the address. String
  id   The address identifier. String
  number   The street number associated with the address. Integer
  streetName   The street name associated with the address. String
  zipCode   The zip code associated with the address. Integer
contacts     The Crowd partner contact information.  
  emailAddress   The email address of the Crowd partner contact. String
  firstName   The first name of the Crowd partner contact String
  id   The Crowd partner contact identifier. String
  lastName   The last name of the Crowd partner contact. String
  phoneNumber   The Crowd partner contact phone number. String
  role   The role of the crowd partner contact (example: PARTNER ADMIN). String
id     The unique Crowd partner identifier. String
name     The name of the Crowd partner. String
serviceAreas     The service area information of the Crowd partner.  
  googlePlaceId   The google place ID associated with the service area center point. String
  id   The identifier associated with the service area record. String
  latitude   The latitude of the service area center point. Integer
  longitude   The longitude of the service area center point Integer
  radius   The service area readius.  
    unit The unit of measure associated with the service area radius (example: km; mi). String
    value The value associated with the service area radius (example: 10). Integer

1.9.4 Example Body

The following is an example of a new Crowd partner record created via POST request:

{
  "address": {
    "city": "Munich",
    "country": "Germany",
    "id": "59052728e6434a598d1ff9965637ec1e",
    "number": 15,
    "streetName": "Rosenheimer Strasse",
    "zipCode": 81667
  },
  "contacts": [
    {
      "emailAddress": "john.smith@coresystems-partner.com",
      "firstName": "John",
      "id": "59052728e6434a598d1ff9965637ec1e",
      "lastName": "Smith",
      "phoneNumber": "+1234567890"
    }
  ],
  "id": "59052728e6434a598d1ff9965637ec1e",
  "name": "Coresystems Partner Solutions",
  "serviceArea": {
    "googlePlaceId": "ChIJrTLr-GyuEmsRBfy61i59si0",
    "id": "eb581c4d-1eec-4200-af60-ae7be2f01a98",
    "latitude": 48.137154,
    "longitude": 11.576124,
    "radius": {
      "unit": "mi",
      "value": 15.5
    }
  }
}

1.9.5 Example Resonse

{
  "results": [
    {
      "address": {
        "city": "Munich",
        "country": "Germany",
        "id": "59052728e6434a598d1ff9965637ec1e",
        "number": 15,
        "streetName": "Rosenheimer Strasse",
        "zipCode": 81667
      },
      "contacts": [
        {
          "emailAddress": "john.smith@coresystems-partner.com",
          "firstName": "John",
          "id": "59052728e6434a598d1ff9965637ec1e",
          "lastName": "Smith",
          "phoneNumber": "+1234567890",
          "role": "PARTNER_ADMIN"
        }
      ],
      "id": "59052728e6434a598d1ff9965637ec1e",
      "name": "Coresystems Partner Solutions",
      "serviceArea": {
        "googlePlaceId": "ChIJrTLr-GyuEmsRBfy61i59si0",
        "id": "eb581c4d-1eec-4200-af60-ae7be2f01a98",
        "latitude": 48.137154,
        "longitude": 11.576124,
        "radius": {
          "unit": "mi",
          "value": 15.5
        }
      }
    }
  ]
}

1.9.6 Response Codes

Status Response
201 Created
401 Unauthorized
403 Forbidden
404 Not Found

1.10 PUT Crowd Partner Update

Update an existing Crowd partner record and sub-resources.

1.10.1 Request

Method URL
PUT https://{cluster}.coresuite.net/api/crowd-partner/v1/partners/{id}

1.10.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-ID accountId The account identifier Required
X-Client-ID clientId Client app identifier Required
X-Client-Version clientVersion The client version Required
X-Company-Id companyId The company identfier Required

1.10.3 URL Parameters

Parameter Description Type Required
id The unique ID of the Crowd partner record you wish to update. String Required

1.10.4 Body

Value     Description Type
address     The address information of the Crowd partner.  
  city   The city associated with the address. String
  country   The country associated with the address. String
  id   The address identifier. String
  number   The street number associated with the address. Integer
  streetName   The street name associated with the address. String
  zipCode   The zip code associated with the address. Integer
contacts     The Crowd partner contact information.  
  emailAddress   The email address of the Crowd partner contact. String
  firstName   The first name of the Crowd partner contact String
  id   The Crowd partner contact identifier. String
  lastName   The last name of the Crowd partner contact. String
  phoneNumber   The Crowd partner contact phone number. String
  role   The role of the crowd partner contact (example: PARTNER ADMIN). String
id     The unique Crowd partner identifier. String
name     The name of the Crowd partner. String
serviceAreas     The service area information of the Crowd partner.  
  googlePlaceId   The google place ID associated with the service area center point. String
  id   The identifier associated with the service area record. String
  latitude   The latitude of the service area center point. Integer
  longitude   The longitude of the service area center point Integer
  radius   The service area readius.  
    unit The unit of measure associated with the service area radius (example: km; mi). String
    value The value associated with the service area radius (example: 10). Integer

1.10.5 Example Body

{
  "address": {
    "city": "Munich",
    "country": "Germany",
    "id": "59052728e6434a598d1ff9965637ec1e",
    "number": 15,
    "streetName": "Rosenheimer Strasse",
    "zipCode": 81667
  },
  "contacts": [
    {
      "emailAddress": "john.smith@coresystems-partner.com",
      "firstName": "John",
      "id": "59052728e6434a598d1ff9965637ec1e",
      "lastName": "Smith",
      "phoneNumber": "+1234567890"
    }
  ],
  "id": "59052728e6434a598d1ff9965637ec1e",
  "name": "Coresystems Partner Solutions",
  "serviceArea": {
    "googlePlaceId": "ChIJrTLr-GyuEmsRBfy61i59si0",
    "id": "eb581c4d-1eec-4200-af60-ae7be2f01a98",
    "latitude": 48.137154,
    "longitude": 11.576124,
    "radius": {
      "unit": "mi",
      "value": 15.5
    }
  }
}

1.10.6 Example Response

{
  "results": [
    {
      "address": {
        "city": "Munich",
        "country": "Germany",
        "id": "59052728e6434a598d1ff9965637ec1e",
        "number": 15,
        "streetName": "Rosenheimer Strasse",
        "zipCode": 81667
      },
      "contacts": [
        {
          "emailAddress": "john.smith@coresystems-partner.com",
          "firstName": "John",
          "id": "59052728e6434a598d1ff9965637ec1e",
          "lastName": "Smith",
          "phoneNumber": "+1234567890",
          "role": "PARTNER_ADMIN"
        }
      ],
      "id": "59052728e6434a598d1ff9965637ec1e",
      "name": "Coresystems Partner Solutions",
      "serviceArea": {
        "googlePlaceId": "ChIJrTLr-GyuEmsRBfy61i59si0",
        "id": "eb581c4d-1eec-4200-af60-ae7be2f01a98",
        "latitude": 48.137154,
        "longitude": 11.576124,
        "radius": {
          "unit": "mi",
          "value": 15.5
        }
      }
    }
  ]
}

1.10.7 Response Codes

Status Response
200 OK
201 Created
401 Unauthorized
403 Forbidden
404 Not Found