Bulk API

1.1 Overview

The Bulk API is an extension of the Data API v4 used to create/update and delete resources in bulk.


1.1.1 Supported Endpoints

  Note Section
1.1.1.1 PATCH and PUTrequest to create/update objects in bulk. The externalId must be present in the request body. 1.2
1.1.1.2 DELETE request to delete objects in bulk. The externalId must be present in the request body. 1.3

1.1.2 Supported Query Parameters

The following query paramters are supported by the Bulk API:

Query Parameter Type Required Description
forceUpdate(For Patch and Put requests) Boolean FALSE Set to false by default. If set to true, the optimistic locking mechanism provided by lastChanged property is ignored. Such a call overrides any possible changes made to the resource since the last retrieval.
forceDelete(For delete Requests) Boolean FALSE Set to false by default. If set to true, the optimistic locking mechanism provided by lastChanged property is ignored. Such a call overrides any possible changes made to the resource since the last retrieval.
dtoVersions( Only for Patch and Put requests) String TRUE resourceName.dtoVersion for example Address.20

1.1.3 URL Paramaters

Example https://{cluster}.coresuite.com/api/data/v4/Address/externalId/bulk?dtos=Address.14
Parameter Example Description Required
{resourceName} Address Here you will reference the supported data object which you wish to create or update in bulk. Required
{resourceName.dtoVersion} Address.14 Here you will reference the data transfer object again along with the specific version. Required

1.2 PATCH / PUT Bulk Request

Create/update objects in bulk.

  Note
1.2.0.1 Request should contain in the body the fields that you want to update.
1.2.0.2 If the resource does not exist, this server will create it under the given URI.

Please note that this is valid also for PATCH, but you need to send all required fields in order to create a valid object.
1.2.0.3 In order to create/update an object using a PUT request, the whole object needs to be provided in request body.

1.2.1 Request

In order to create/update an object, a PATCH or PUT request must be made to following url:

Method URL
PATCH https://{cluster}.coresuite.com/api/data/v4/{resourceName}/externalId/bulk?dtos={resourceName.dtoVersion}
PUT https://{cluster}.coresuite.com/api/data/v4/{resourceName}/externalId/bulk?dtos={resourceName.dtoVersion}

1.2.2 Request Body

The following is an example of the request body contained in a Bulk API PATCH or PUT request.

This exampe uses the following endpoint:

Method URL
PATCH https://{cluster}.coresuite.com/api/data/v4/Address/externalId/bulk?dtos=Address.14
PUT https://{cluster}.coresuite.com/api/data/v4/Address/externalId/bulk?dtos=Address.14

Note: Both PATCH and PUT requests must reference the externalId of the objects in the request body.

[{
        "externalId": "C6765B13EF1E2462868E5F",
        "inactive": false,
        "lastChanged": 0,
        "city": "test City 1",
        "country": "test Country 1",
        "defaultAddress": false,
        "name": "Test address 1",
        "object": {
            "objectId": "A506E7AD87374F209CDC43E589029445",
            "objectType": "BUSINESSPARTNER"
        },
        "street": "test street 1",
        "zipCode": "4444"
    },
    {
        "externalId": "EB6EDED4929E4246BAB1969285F",
        "inactive": false,
        "lastChanged": 0,
        "city": "test City 2",
        "country": "test Country 2",
        "defaultAddress": false,
        "name": "Test address 2",
        "object": {
            "objectId": "ABC6E7AD87374F209CDC43E589029123",
            "objectType": "BUSINESSPARTNER"
        },
        "street": "test street 2",
        "zipCode": "5555"
    }
  ]

1.2.3 Response

Code Response
207 HTTP_MULTI_STATUS

1.2.3.1 Response for Individual Resources

The following status codes are communicated in the response body:

Code Response
200 OK. Returned for each individual resource in the response body.
201 Created/Updated. Returned for individual resource in the response body.

Note: The response body contains the list of updated (created) resources with a status for each individual resource.


1.2.4 Example Response

The following is an example of a response returned from a PATCH or PUT request made to the Bulk API.

Please note that an individual response code is present for each impacted resource. This response code is communicated in status.

[
    {
        "status": 201,
        "location": "http://localhost:9080/dc/api/data/v4/Address/externalId/C6765B13EF1E2462868E5F",
        "address": {
            "country": "test country 1",
            "zipCode": "4444",
            "city": "test city 1",
            "county": null,
            "owners": null,
            "type": null,
            "building": null,
            "syncObjectKPIs": null,
            "postOfficeBox": null,
            "inactive": false,
            "street": "not sure",
            "block": null,
            "state": null,
            "id": "6CF10C216829433C958D3B3AE5510A91",
            "floor": null,
            "streetNo": null,
            "lastChanged": 1550566130211,
            "createPerson": "AFC0F59CD7C54474A3FA788E037C71B6",
            "externalId": "C6765B13EF1E2462868E5F",
            "groups": null,
            "branches": null,
            "room": null,
            "createDateTime": "2019-02-19T14:18:48+05:30",
            "name3": null,
            "udfMetaGroups": null,
            "name": "Test address 1",
            "location": null,
            "udfValues": null,
            "name2": null,
            "lastChangedBy": "AFC0F59CD7C54474A3FA788E037C71B6",
            "remarks": null,
            "syncStatus": "BLOCKED",
            "defaultAddress": false,
            "object": {
                "objectId": "A506E7AD87374F209CDC43E589029445",
                "objectType": "BUSINESSPARTNER"
            }
        }
    },
    {
        "status": 201,
        "location": "http://localhost:9080/dc/api/data/v4/Address/externalId/EB6EDED4929E4246BAB1969285F",
        "address": {
            "country": "test country 2",
            "zipCode": "5555",
            "city": "test city 2",
            "county": null,
            "owners": null,
            "type": null,
            "building": null,
            "syncObjectKPIs": null,
            "postOfficeBox": null,
            "inactive": false,
            "street": "test street 2",
            "block": null,
            "state": null,
            "id": "390CB7C5322346C39BDB8E1DF0DE6CD2",
            "floor": null,
            "streetNo": null,
            "lastChanged": 1550566131486,
            "createPerson": "AFC0F59CD7C54474A3FA788E037C71B6",
            "externalId": "EB6EDED4929E4246BAB1969285F",
            "groups": null,
            "branches": null,
            "room": null,
            "createDateTime": "2019-02-19T14:18:51+05:30",
            "name3": null,
            "udfMetaGroups": null,
            "name": "Test address 2",
            "location": null,
            "udfValues": null,
            "name2": null,
            "lastChangedBy": "AFC0F59CD7C54474A3FA788E037C71B6",
            "remarks": null,
            "syncStatus": "BLOCKED",
            "defaultAddress": false,
            "object": {
                "objectId": "ABC6E7AD87374F209CDC43E589029123",
                "objectType": "BUSINESSPARTNER"
            }
        }
    }
] 

1.2.5 Failure Response

The following is an example of the message returned when the request has failed:

Code Response
207 HTTP_MULTI_STATUS
 
[
    {
        "status": 422,
        "externalId": "C6765B13EF1E2462868E5F",
        "ex": {
            "error": "CA-41",
            "message": "CA-41: Cannot create resource [Address:6CF10C216829433C958D3B3AE5510A91] as it already exists.",
            "values": [
                "Address",
                "6CF10C216829433C958D3B3AE5510A91"
            ],
            "id": "df60161198284830b739dbf1e150ecd1"
        }
    },
    {
        "status": 422,
        "externalId": "EB6EDED4929E4246BAB1969285F",
        "ex": {
            "error": "CA-41",
            "message": "CA-41: Cannot create resource [Address:390CB7C5322346C39BDB8E1DF0DE6CD2] as it already exists.",
            "values": [
                "Address",
                "390CB7C5322346C39BDB8E1DF0DE6CD2"
            ],
            "id": "a25de2053bd04a9786a2a46fe899008c"
        }
    }
]

1.3 DELETE Bulk Request

Delete objects in bulk.


1.3.1 Request

Method URL
DELETE https://{cluster}.coresuite.com/api/data/v4/{resourceName}/externalId/bulk

1.3.1.1 Request Body

Note: DELETE requests must reference the externalId of the object in the request body.

 
[{
     
    "externalId":"ABAD",
    "lastChanged": 1550571215725 (lastChanged is not needed if forceDelete=true is passed as query parameter )
},{
     
    "externalId":"ACDA",
    "lastChanged": 1550571215725
}]

1.3.2 Response

Code Response
207 HTTP_MULTI_STATUS

1.3.2.1 Response for Individual Resources

The following status codes are communicated in the response body:

Code Response
200 OK. Returned for individual resource in the response body.

1.3.3 Example Response

The following is an example of a response returned from a DELETE request made to the Bulk API.

Please note that an individual response code is present for each impacted resource. This response code is communicated in status.

[
    {
        "status": 200,
        "externalId": "ABAD"
    },
    {
        "status": 200,
        "externalId": "ACDA"
    }
]