Bulk and composite request services

Bulk requests (Open Beta)

Use the bulk request service to process multiple operations for one REST object with a single HTTP call. The service provides two functions: file upload to submit a bulk request for asynchronous processing, and job status to get the status of asynchronous jobs.

Submit a bulk request

Creating a new bulk API request involves specifying the object type and operation in the request body and uploading a file, which contains the data for your objects. Operations are processed as separate transactions. Processing proceeds to the next operation on success or failure.

Data is passed into the request via a JSON file.

Currently, there is no limit on the number of operations in a bulk request.

The service uploads the file, records the job details and the callback URL, and returns a job ID. You can use the job ID to get the status and the detailed report of the job, see the Check the bulk request status section for details.

Bulk request URI and examples

  • URI
    Copy
    Copied
    https://{hostname}/ia/api/{version}/services/bulk/job/create
  • HTTP method

    POST

For example, use the following cURL command to submit a bulk request for vendor objects:

Copy
Copied
curl --location 'https://api-dev.intacct.com/ia/api/v1/services/bulk/job/create' \
--header 'Authorization: Bearer {{your_authorization_token}}' \
--header 'Cookie: DFT_LOCALE=en_US.UTF-8' \
--form 'ia::requestBody="{ \"objectName\" : \"vendor\", \"operation\": \"create\", \"jobFile\" : \"file\", \"fileContentType\" : \"json\"}";type=application/json' \
--form 'file=@"/Users/firstname.lastname/Desktop/BULK Files/vendors.json"'
ia::requestBody

Pass the following attributes in the request body, with each value in double quotes:

  • objectName : the REST object targeted by the request, such as vendor.
  • operation : must be create for a POST, update for a PATCH, or delete for a DELETE operation.
  • jobFile : the name of your file input.
  • fileContentType : the format of your file, must be json .
file

The contents of your file must represent the objects to be created, updated, or deleted, in JSON format.

The object properties specified in your file must match the schema definition of the object. If there is a mismatch, the object will not be created. Processing will proceed and an error entry will be recorded for each failed transaction.

The following example shows a file with three vendor objects:

Copy
Copied
[
 {"id":"vendor1","name":"Corner Library","billingType":null,"term":{"key":"8"},"vendorType":{"key":"1"},"accountGroup":{"key":"1"}},
 {"id":"vendor2","name":"Just Picked","billingType":null,"term":{"key":"8"},"vendorType":{"key":"1"},"accountGroup":{"key":"1"}},
 {"id":"vendor3","name":"Petco","billingType":null,"term":{"key":"8"},"vendorType":{"key":"1"},"accountGroup":{"key":"1"}},
]

Check the bulk request status

After the bulk request has been sent, you can monitor the status of the job.

Job status request URI and examples

  • URI
    Copy
    Copied
    https://{hostname}/ia/api/{version}/services/bulk/job/status
  • HTTP method

    GET

For example, use the following cURL command to send a status request for a specified job ID:

Copy
Copied
curl --location 'https://api-dev.intacct.com/ia/api/v1/services/bulk/job/status?jobId={{job_id}}&download=true' \
--header 'Authorization: Bearer {{your_authorization_token}}' \
--header 'Content-Type: application/json' \
--header 'Cookie: DFT_LOCALE=en_US.UTF-8'

The request returns the status of the job, which can be: queued, processing, completed, or failed. Once the job is completed, set the optional boolean download parameter to true to download the results of all the operations in JSON format. If the download parameter is omitted or is set to false, only the job status is returned.

Composite requests

Use the composite request service to send a request containing multiple sub-requests for different objects or services in a single HTTPS call. For example, you can create a new contact, update an existing vendor, query bills, and so forth, in a single request.

The composite request service is designed to:

  • Support mixed operations, for example GET and POST.
  • Support a combination of operations and services in one request. Each sub-request path is restricted to /objects/... or /services/... .
  • Support operations on different objects in one request.
  • Use the output from one sub-request in subsequent sub-requests. For example, you can save the key of the newly created object and use it in subsequent sub-requests.
  • Support HTTP request and response headers for each sub-request. Authorization , Content-Type and Accept headers cannot be specified for each sub-request, they are inherited from the top level.

The composite service supports between 2 and 10 sub-requests. Permissions are checked for each sub-request during execution.

All sub-requests must use the same version of the API as the composite request. You cannot use a combination of API versions.

Sub-requests are executed sequentially. The execution stops on first failure with no rollback of any previous sub-requests.

Composite request responses are synchronous.

Composite request URI and examples

See the Send a composite request reference page for a list and description of fields you can include in a composite request. Send the request to the following endpoint URL using the POST method:

Copy
Copied
  https:///api.intacct.com/ia/api/{version}/services/core/composite

Sample request body

Copy
Copied
[
    {
      "method": "POST",
      "path": "/objects/accounts-payable/vendor",
      "body": { ... },
      "resultReference": "vendor",
      "headers": {
        "X-ABC": "123"
      }
    },
    {
      "method": "GET",
      "path": "/objects/accounts-payable/vendor/@{vendor.1.key}"
    }
]

Sample response body - success

Copy
Copied
{
    "ia::result": [
      {
        "ia::result": [{ ... }],
        "ia::meta": {
          "totalCount": 1
        },
        "ia::status": 200,
        "ia::headers": {
          "X-ORM-ACTION": "create"
        }
      },
      {
        "ia::result": [{ ... }],
        "ia::meta": {
          "totalCount": 1
        },
        "ia::status": 200
      }
    ],
    "ia::meta": {
      "totalCount": 2,
      "totalSuccess": 2,
      "totalError": 0
    }
}

Sample response body - failure

Copy
Copied
{
    "ia::result": [
      {
        "ia::error": [{ ... }],
        "ia::meta": {
          "totalCount": 1
        },
        "ia::status": 400
      },
      {
        "ia::error": [{ <message that the request was not processed> }],
        "ia::meta": {
          "totalCount": 1
        },
        "ia::status": 422
      }
    ],
    "ia::meta": {
      "totalCount": 2,
      "totalSuccess": 0,
      "totalError": 2
    }
}