Crowd Document API

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

1.1 Overview

The Crowd Document API enables Crowd owners with external systems to make requests from a third-party application to SAP Field Service Management, where they can manage Crowd partner documentation.

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

Crowd


1.1.1 Supported Requests

The following requests are supported by the Crowd Document API:

  Method Description Section
1.1.0.1 GET Retrieve list of all Crowd partner documentation. 1.3
1.1.0.2 POST Create a document for a specified Crowd partner. 1.4
1.1.0.3 GET Retrieve a specific document by ID. 1.5
1.1.0.3 PUT Update document for specified Crowd partner. 1.6
1.1.0.4 DELETE Delete a document by ID. 1.7
1.1.0.5 POST Approve documents provided by Crowd partner. 1.8
1.1.0.6 POST Reject documents provided by Crowd partner. 1.9

1.1.2 Crowd Document API in Swagger

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


1.2 Access

The Crowd Document 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
  • CN
  • AU

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

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

https://{cluster}.coresuite.net/api/crowd/v1/documents


1.3 GET All Documents

Retrieve all documents from all Crowd partners associated with Crowd owner.

1.3.1 Request

Method URL
GET https://{cluster}.coresuite.com/api/crowd/v1/documents

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-Account-Name accountName The name of the account 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-Company-Name companyName The name of the company Required
Accept application/json;charset=UTF-8   Required
content-type application/json   Required

1.3.3 URL Parameters

The following query parameters can be appended to the URL path to filter results:

Parameter Type Description
{attachmentId} String The ID of the attachment you wish to return.
{name} String The name of the file related to document.
{partnerId} String The identifier of the Crowd partner associated with the documents.
{technicianId} String The identifier of the technician associated with the documents.
{validFrom} String The beginning date of the document validity range.
{validTo} String The end date of the document validity range.

If you wish to filter data using parameters, they can be applied as shown in the following examples:

Filter Parameter Example
{name} https://{cluster}.coresuite.com/api/crowd/v1/documents?name=IMG_20190916_105419.jpg
{attachmentId} https://{cluster}.coresuite.com/api/crowd/v1/documents?attachmentId=03181C9AEC494B798550793C34041D04
{validFrom} https://{cluster}.coresuite.com/api/crowd/v1/documents?validFrom=2019-01-01&validTo=2019-12-31

1.3.4 Response

The following values are displayed in the request response:

Value   Description Type
approvalDecision      
  approvalStatus The current documentation approval status. String
  reason If applicable, the comment associated withe the approval decision. String
attachmentId   The unique ID of the attachment. String
description   The description of the document. String
id   The unique ID of the document. String
name   The name of the document file with file extension. String
objectType      
  objectId The ID of the object. String
  objectId the object type (example: ADDRESS). String
state   The current status of the document (example: NEW). String
validFrom   The beginning date of the document validity date range. Date
validTo   The end date of the document validity date range. Date

1.3.5 Example Response

{
  "results": [
    {
      "approvalDecision": {
        "approvalStatus": "APPROVED",
        "reason": "Fully agree with that"
      },
      "attachmentId": "59052728e6434a598d1ff9965637ec1e",
      "description": "Report includes statistics for 2018-2019 period.",
      "id": "eb581c4d-1eec-4200-af60-ae7be2f01a98",
      "name": "Report-2019.pdf",
      "objectType": {
        "objectId": "string",
        "objectType": "ADDRESS"
      },
      "state": "NEW",
      "validFrom": "2019-10-28",
      "validTo": "2019-11-28"
    }
  ]
}

1.3.6 Response Codes

Status Response
200 OK
401 Unauthorized
403 Forbidden
404 Not Found

1.4 Create Document for Crowd Partner

Create a new document for a specified Crowd partner. This method creates and uploads new attachment of a given document.


1.4.1 Request

Method URL
POST https://{cluster}.coresuite.com/api/crowd/v1/documents

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-Account-Name accountName The name of the account 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-Company-Name companyName The name of the company Required
Accept application/json;charset=UTF-8   Required
content-type multipart/form-data   Required

1.4.3 Request Body

The following are the values are supported when creating a new document for a Crowd partner:

Value   Description Type Required
approvalDecision        
  approvalStatus The current documentation approval status. String  
  reason If applicable, the comment associated withe the approval decision. String  
attachmentId   The unique ID of the attachment. String  
description   The description of the document. String Optional
id   The unique ID of the document. String  
name   The name of the document file with file extension. String  
objectType       Required
  objectId The ID of the object. String  
  objectId the object type (example: ADDRESS). String  
state   The current status of the document (example: NEW). String  
validFrom   The beginning date of the document validity date range. Date Optional
validTo   The end date of the document validity date range. Date Optional

1.4.4 Example Request

{
  "approvalDecision": {
    "approvalStatus": "APPROVED",
    "reason": "Fully agree with that"
  },
  "attachmentId": "59052728e6434a598d1ff9965637ec1e",
  "description": "Report includes statistics for 2018-2019 period.",
  "id": "eb581c4d-1eec-4200-af60-ae7be2f01a98",
  "name": "Report-2019.pdf",
  "objectType": {
    "objectId": "string",
    "objectType": "ADDRESS"
  },
  "state": "NEW",
  "validFrom": "2019-10-28",
  "validTo": "2019-11-28"
}

1.4.5 Example Response

{
  "approvalDecision": {
    "approvalStatus": "APPROVED",
    "reason": "Fully agree with that"
  },
  "attachmentId": "59052728e6434a598d1ff9965637ec1e",
  "description": "Report includes statistics for 2018-2019 period.",
  "id": "eb581c4d-1eec-4200-af60-ae7be2f01a98",
  "name": "Report-2019.pdf",
  "objectType": {
    "objectId": "string",
    "objectType": "ADDRESS"
  },
  "state": "NEW",
  "validFrom": "2019-10-28",
  "validTo": "2019-11-28"
}

1.4.6 Response Codes

Status Response
201 Created
401 Unauthorized
403 Forbidden
404 Not Found

1.5 GET Document by ID

Retrieve details of existing Crowd owner document by id.

1.5.1 Request

Method URL
GET https://{cluster}.coresuite.net/api/crowd/v1/documents/{id}

1.5.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-ID accountId The account identifier Required
X-Account-Name accountName The name of the account 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-Company-Name companyName The name of the company Required
Accept application/json;charset=UTF-8   Required
content-type application/json   Required

1.5.3 URL Parameters

Parameter Description Type Required
{id} The ID of the Crowd owner document you wish to retrieve. String Required

1.5.4 Response Example

{
  "results": [
    {
      "approvalDecision": {
        "approvalStatus": "APPROVED",
        "reason": "Fully agree with that"
      },
      "attachmentId": "59052728e6434a598d1ff9965637ec1e",
      "description": "Report includes statistics for 2018-2019 period.",
      "id": "eb581c4d-1eec-4200-af60-ae7be2f01a98",
      "name": "Report-2019.pdf",
      "objectType": {
        "objectId": "string",
        "objectType": "ADDRESS"
      },
      "state": "NEW",
      "validFrom": "2019-10-28",
      "validTo": "2019-11-28"
    }
  ]
}

1.5.5 Response

Status Response
200 Document found and available to read
401 Unauthorized
403 Forbidden
404 Not Found

1.6 Update Document

Update an existing Crowd owner document by id.

1.6.1 Request

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

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-Account-Name accountName The name of the account 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-Company-Name companyName The name of the company Required
Accept application/json;charset=UTF-8   Required
content-type application/json   Required

1.6.3 URL Parameters

Parameter Description Type Required
{id} The ID of the Crowd owner document you wish to update. String Required

1.6.4 Request Body

The following are the values are supported when updating an existing document:

Value   Description Type Required
approvalDecision   Read-only.    
  approvalStatus The current documentation approval status. String  
  reason If applicable, the comment associated withe the approval decision. String  
attachmentId   Read-only. The unique ID of the attachment. String  
description   The description of the document. String  
id   Read-only. The unique ID of the document. String Required
name   Read-only. The name of the document file with file extension. String  
objectType        
  objectId The ID of the object. String  
  objectId the object type (example: ADDRESS). String  
state   Read-only. The current status of the document (example: NEW). String  
validFrom   The beginning date of the document validity date range. Date  
validTo   The end date of the document validity date range. Date  

1.6.5 Example Request

{
  "approvalDecision": {
    "approvalStatus": "APPROVED",
    "reason": "Fully agree with that"
  },
  "attachmentId": "59052728e6434a598d1ff9965637ec1e",
  "description": "Report includes statistics for 2018-2019 period.",
  "id": "eb581c4d-1eec-4200-af60-ae7be2f01a98",
  "name": "Report-2019.pdf",
  "objectType": {
    "objectId": "string",
    "objectType": "ADDRESS"
  },
  "state": "NEW",
  "validFrom": "2019-10-28",
  "validTo": "2019-11-28"
}

1.6.6 Example Response

{
  "approvalDecision": {
    "approvalStatus": "APPROVED",
    "reason": "Fully agree with that"
  },
  "attachmentId": "59052728e6434a598d1ff9965637ec1e",
  "description": "Report includes statistics for 2018-2019 period.",
  "id": "eb581c4d-1eec-4200-af60-ae7be2f01a98",
  "name": "Report-2019.pdf",
  "objectType": {
    "objectId": "string",
    "objectType": "ADDRESS"
  },
  "state": "NEW",
  "validFrom": "2019-10-28",
  "validTo": "2019-11-28"
}

1.6.6 Response Codes

Status Response
200 Document updated successfully
201 Created
401 Unauthorized
403 Forbidden
404 Not Found

1.7 Delete Document by ID

Delete a specific document by id. Associated attachment will be deleted as well.

1.7.1 Request

Method URL
DELETE https://{cluster}.coresuite.net/api/crowd/v1/documents/{id}

1.7.2 Headers

Header Parameter Value Description Required
Authorization bearer OAuth 2.0 token Required
X-Account-ID accountId The account identifier Required
X-Account-Name accountName The name of the account 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-Company-Name companyName The name of the company Required
Accept application/json;charset=UTF-8   Required
content-type application/json   Required

1.7.3 URL Parameters

Parameter Description Type Required
{id} The ID of the Crowd owner document you wish to delete. String Required

1.7.4 Response Codes

Status Response
204 Operation performed successfully and returned no content
401 Unauthorized
403 Forbidden

1.8 Approve Documents Provided by Crowd Partner

Approve documents provided by Crowd partner.

Attention: documents can ONLY be approved by the Crowd Owner.

1.8.1 Request

Method URL
POST https://{cluster}.coresuite.net/api/crowd/v1/documents/actions/approve

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-Account-Name accountName The name of the account 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-Company-Name companyName The name of the company Required
Accept application/json;charset=UTF-8   Required
content-type application/json   Required

1.8.3 Request Body

Value Description Type Required
id The ID of the document you wish to approve. String Required
reason The reason for the document approval. String  

1.8.5 Example Request

[
  {
    "id": "eb581c4d-1eec-4200-af60-ae7be2f01a98",
    "reason": "Rejected because signature absence"
  }
]

1.8.6 Example Response

[
  {
    "id": "eb581c4d-1eec-4200-af60-ae7be2f01a98",
    "reason": "Rejected because signature absence"
  }
]

1.8.7 Response Codes

Status Response
201 Created
202 Accepted
401 Unauthorized
403 Forbidden
404 Not Found

1.9 Reject Crowd Partner Documents

Reject document provided by Crowd partner.

Attention: documents can ONLY be rejecte by the Crowd Owner.

1.9.1 Request

Method URL
POST https://{cluster}.coresuite.net/api/crowd/v1/documents/actions/reject

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-Account-Name accountName The name of the account 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-Company-Name companyName The name of the company Required
Accept application/json;charset=UTF-8   Required
content-type application/json   Required

1.9.3 Request Body

Value Description Type Required
id The ID of the document you wish to reject. String Required
reason The reason for the document rejection. String  

1.9.5 Example Request

[
  {
    "id": "eb581c4d-1eec-4200-af60-ae7be2f01a98",
    "reason": "Rejected because signature absence"
  }
]

1.9.6 Example Response

[
  {
    "id": "eb581c4d-1eec-4200-af60-ae7be2f01a98",
    "reason": "Rejected because signature absence"
  }
]

1.9.7 Response Codes

Status Response
201 Created
202 Accepted
401 Unauthorized
403 Forbidden
404 Not Found