Asynchronous API Requests

Asynchronous API Requests gives you the flexibility to start a job that may take some time to complete and be notified when it has completed. For example, a user makes a request to copy a folder to her account. This request may take some time to process. With an Asynchronous API Request, your app will receive a notification that job has started, as well as, a notification when the job has processed.

Performing an Asynchronous API Request:

Additional Required Header:

• Elements-Async-Request – this must be set to True

Optional Header:

• Elements-Async-Callback-URL – if not included in request, then the app will use the callback URL associated with the instance. If you do not have a callback URL associated with the instance configuration or supply one in the request, then an error will be returned. If you configured the Callback Notification Signature Key (event.notification.signature.key) when you authenticated an element instance, the bulk APIs will use the signature key to provide hash verification in the header of bulk jobs. For more on Cloud Elements Hash Verification, see Hash Verification.

For example, this request is asynchronous:

curl -X POST \
  -H 'Authorization: User <INSERT_USER_SECRET>, Element <INSERT_ELEMENT_SECRET>' \
  -H 'Content-Type: application/json' \
  -H 'Elements-Async-Request: True' \
  -H 'Elements-Async-Callback-Url: <www.samplecallbackurl.com>' \
  -d @copy-folder.json \
  'https://api.cloud-elements.com/elements/api-v2 /hubs/documents/folders/copy?path=/TestFolderCreate'

with the following copy-folder.json:

{
  "path": "/testfoldercopy",
  "tags": [
    "TestFolderCopy"
  ],
  "name": "TestFolderCopy"
}

The immediate response from this call will have content like this:

{
  "eventId": 1028,
  "eventStatus": "dispatched"
}

When the copy is complete, a webhook will be delivered to the notification callback URL that looks like this:

{
  "eventId": 1028,
  "instanceId": 30,
  "response": {
    "events": [
      {
        "path": "/testfoldercopy",
        "metadata": {
          "path": "/TestFolderCopy",
          "name": "TestFolderCopy",
          "type": "folder"
        }
      },
      {
        "path": "/testfoldercopy/testuploadfile.txt",
        "metadata": {
          "path": "/TestFolderCopy/testUploadFile.txt",
          "name": "testUploadFile.txt",
          "type": "file"
        }
      }
    ]
  },
  "notificationId": 1084
}