Documentation & Guides

Jobs

A job invokes an automation process that you can track and monitor. A job can have multiple inputs and outputs at different stages of its execution.

Job object

Here is an example of a job object:

{
  "object": "job",
  "id": "e863af21-eea7-433f-822a-921871f13c5d",
  "state": "processing",
  "category": "test",
  "domainId": "Generic",
  "progress": 0,
  ...
}

state

category

The category flag allows us to distinguish between your "live" and "test" jobs to provide accurate stats, billing and better support during your integration period. The flag doesn't affect any other aspect of the job. Both "test" and "live" automation run in the same way in the same environment.

domainId

Job inherits the domain value from the Automation Cloud service.

A domain describes the input data you need to request an automation job and the output data you should expect. See the Automation Protocolopen in new window for the complete list of domains that the Automation Cloud supports today.

progress

Job progress property indicates the percentage of progress of the job, which is a calculation based on the number of automation steps completed divided by the total number of steps. You can use this to show a progress indicator to your customers, but please note that not all progress steps are equal in terms of time.

Job errors

When something goes wrong, the Automation Cloud returns an error object. There are two main places where you can face it:

{
  "object": "job",
  "state": "fail",
  ...
  "error": {
    "object": "job-error",
    "code": "DocumentExpiryDateInvalid",
    "category": "client",
    "message": "Document should be valid for more than 3 months"
  },
}

TIP

You can find the complete list of standard errors per domain in the Automation Protocolopen in new window.

The Generic domain provides the foundation for all the specific domains, which means all the errors from the Generic listopen in new window can also occur in any other domain.

The most important part of a job error is the code – consider using it to distinguish between errors.

The message field may include a human-readable description of the problem

The category field shows the source of the issue:

categorydescription
clientErrors caused by invalid input or other factors which under your control (client of Automation Cloud)
serverUnexpected problems with Automation Cloud infrastructure – usually should not happen.
websiteErrors caused by factors that neither client nor Automation Cloud can control (e.g. website is down)

All the following endpoints require authentication.

Create a Job

Initiates a new Automation Cloud job on the target service.

In response, you immediately receive a job object that contains the unique job id. The Automation Cloud will now begin processing your automation. This process is asynchronous, meaning everything happens in the background. The total duration of the process depends on the complexity and speed of the supplier's website.

TIP

While you integrate with an Automation Cloud service, please specify the category: "test" parameter, so than we can distinguish your test jobs from the live ones.

If an automation job requires a file as an input, it can be provided as a Fileopen in new window object.

...
"input": {
  ...
  "photo": {
    "type": "File",
    "url": "http://files.example.com/photos/userA.jpg",
    "filename": "userA.jpg",
    "headers": [ { "Authorization": "Bearer abc123" } ]
  }
}

Code sample

POST/jobs
curl -X POST 'https://api.automationcloud.net/jobs' \
    -H 'Authorization: Basic <credentials>' \
    -H 'Content-Type: application/json' \
--data '{
  "category": "test",
  "serviceId": "bd80b73a-af55-4087-a5d4-91f6c861994"
}'

Success Responses

Status 200

{
  "object": "job",
  "id": "e863af21-eea7-433f-822a-921871f13c5d",
  "category": "test",
  "state": "processing",
  "serviceId": "bd80b73a-af55-4087-a5d4-91f6c8619948",
  "serviceName": "School Menu",
  "domainId": "Generic",
  "awaitingInputKey": null,
  "awaitingInputStage": "",
  "lastAwaitingInputKey": null,
  "rejectedInput": null,
  "progress": 0,
  "error": null,
  "activeTdsId": null,
  "inputs": [],
  "outputs": [],
  "piiRemoved": false,
  "sessionId": "510ecbab-75e9-44a3-9d21-163053bceb12",
  "sessionCount": 0,
  "successCode": null,
  "createdAt": 1650902387208,
  "updatedAt": 1650902387367,
  "finishedAt": null,
  "duration": 183
}

👆 The job was accepted and is now in the processing state. Here is an example of a job object.

List all Jobs

Returns a list of all the available jobs created by your client application.

Code sample

GET/jobs
curl -X GET 'https://api.automationcloud.net/jobs' \
    -H 'Authorization: Basic <credentials>' \
    -H 'Content-Type: application/json' \
    -G \
    -d 'serviceId=bd80b73a-af55-4087-a5d4-91f6c8619948' \
    -d 'state=awaitingInput&state=awaitingTds' \
    -d 'category=test' \
    -d 'sort=createdAt' \
    -d 'period=range' \
    -d 'since=1649116800718' \
    -d 'until=1649203199718' \
    -d 'limit=10' \
    -d 'offset=10'

Success Responses

Status 200

{
  "object": "list",
  "data": [],
  "totalCount": 0,
  "totalSessionCount": 0,
  "sort": "-createdAt"
}

An empty list of Automation Jobs.

{
  "object": "list",
  "data": [
    {
      "object": "job",
      "id": "e863af21-eea7-433f-822a-921871f13c5d",
      "serviceId": "bd80b73a-af55-4087-a5d4-91f6c8619948",
      "serviceName": "School Menu",
      "domainId": "Generic",
      "state": "processing",
      "category": "test",
      "awaitingInputKey": null,
      "awaitingInputStage": "",
      "lastAwaitingInputKey": null,
      "rejectedInput": null,
      "progress": 10,
      "error": null,
      "activeTdsId": null,
      "inputs": [],
      "outputs": [],
      "piiRemoved": false,
      "sessionId": "921f9609-014a-4cab-9262-2f28c0a1f85e",
      "sessionCount": 0,
      "successCode": null,
      "createdAt": 1649190861695,
      "updatedAt": 1649190861730,
      "finishedAt": null,
      "duration": 80604
    }
  ],
  "totalCount": 1,
  "totalSessionCount": 1,
  "sort": "-createdAt"
}

Jobs list.

Retrieve a Job

Retrieves the details of a job. Supply the unique job ID from the create a job request's result to see the latest state of the job and any error details should something have gone wrong. More detail about errors can be found in the job errors section.

Code sample

GET/jobs/:id/
curl -X GET 'https://api.automationcloud.net/jobs/e863af21-eea7-433f-822a-921871f13c5d/' \
    -H 'Authorization: Basic <credentials>' \
    -H 'Content-Type: application/json'

Success Responses

Status 200

{
  "object": "job",
  "id": "e863af21-eea7-433f-822a-921871f13c5d",
  "serviceId": "bd80b73a-af55-4087-a5d4-91f6c8619948",
  "serviceName": "School Menu",
  "domainId": "Generic",
  "state": "awaitingInput",
  "category": "test",
  "awaitingInputKey": "ingredientToAvoid",
  "awaitingInputStage": "",
  "lastAwaitingInputKey": "ingredientToAvoid",
  "rejectedInput": null,
  "progress": 20,
  "error": null,
  "activeTdsId": null,
  "inputs": [],
  "outputs": [
    {
      "object": "job-output-meta",
      "key": "ingredients",
      "createdAt": 1649689409325
    }
  ],
  "piiRemoved": false,
  "sessionId": "de041fce-03fa-4353-a925-22d7ec390789",
  "sessionCount": 1,
  "successCode": null,
  "createdAt": 1649689408057,
  "updatedAt": 1649689409408,
  "finishedAt": null,
  "duration": 90322
}

👆 Here is the latest job object. The automation is now waiting for an additional input.

List Job events

Returns a list of job-event objects. Use this endpoint to track your job.

Job Event

Here is an example of a job-event object:

{
    "object": "job-event",
    "id": "9ed24ec4-d40c-4f84-b802-045d1cdf66f1",
    "name": "createOutput",
    "key": "menu", // available with `awaitingInput` and `createOutput` events only
    "createdAt": 1655118891335,
}

id[uuid]

A unique job-event identifier.

name[string]

All possible job event names are listed below.

Event nameDescription
restartAfter job restart.
successAfter job state change to success. The job is finished.
failAfter job state change to fail. The job is finished.
processingAfter job state change to processing.
awaitingInputOn job state job change to awaitingInput. The job is expecting additional input to proceed.
createOutputOn job state job change to createOutput. A new piece of job output is available to be collected.
tdsStartOn 3D Secure challenge start.
tdsFinishOn 3D Secure challenge finish.

key[string]

The key field is available with awaitingInput and createOutput events only.

createdAt[timestamp]

Timestamp of the moment when an event was recorded.

Code sample

GET/jobs/:id/events
curl -X GET 'https://api.automationcloud.net/jobs/e863af21-eea7-433f-822a-921871f13c5d/events' \
    -H 'Authorization: Basic <credentials>' \
    -H 'Content-Type: application/json' \
    -G \
    -d 'offset=1'

Success Responses

Status 200

{
  "object": "list",
  "data": [
    {
      "object": "job-event",
      "id": "459b7c4d-cba6-4419-9cd3-cd62d648c57e",
      "name": "createOutput",
      "key": "ingredients",
      "createdAt": 1655118863314
    },
    {
      "object": "job-event",
      "id": "7f3a69e4-2b12-433c-827f-02288e41310c",
      "name": "awaitingInput",
      "key": "ingredientToAvoid",
      "createdAt": 1655118863594
    },
    {
      "object": "job-event",
      "id": "95b93123-a050-4bc1-b47b-c289e84897a1",
      "name": "processing",
      "createdAt": 1655118891247
    },
    {
      "object": "job-event",
      "id": "9ed24ec4-d40c-4f84-b802-045d1cdf66f1",
      "name": "createOutput",
      "key": "menu",
      "createdAt": 1655118891335
    },
    {
      "object": "job-event",
      "id": "4bec9528-0519-46eb-8e78-161d309b9c43",
      "name": "success",
      "createdAt": 1655118891397
    }
  ]
}

👆 Here is an example list of events for a job.

Create a Job

Initiates a new Automation Cloud job on the target service.

In response, you immediately receive a job object that contains the unique job id. The Automation Cloud will now begin processing your automation. This process is asynchronous, meaning everything happens in the background. The total duration of the process depends on the complexity and speed of the supplier's website.

TIP

While you integrate with an Automation Cloud service, please specify the category: "test" parameter, so than we can distinguish your test jobs from the live ones.

If an automation job requires a file as an input, it can be provided as a Fileopen in new window object.

...
"input": {
  ...
  "photo": {
    "type": "File",
    "url": "http://files.example.com/photos/userA.jpg",
    "filename": "userA.jpg",
    "headers": [ { "Authorization": "Bearer abc123" } ]
  }
}

Code sample

POST/jobs
curl -X POST 'https://api.automationcloud.net/jobs' \
    -H 'Authorization: Basic <credentials>' \
    -H 'Content-Type: application/json' \
--data '{
  "category": "test",
  "serviceId": "bd80b73a-af55-4087-a5d4-91f6c861994"
}'

Success Responses

Status 200

{
  "object": "job",
  "id": "e863af21-eea7-433f-822a-921871f13c5d",
  "category": "test",
  "state": "processing",
  "serviceId": "bd80b73a-af55-4087-a5d4-91f6c8619948",
  "serviceName": "School Menu",
  "domainId": "Generic",
  "awaitingInputKey": null,
  "awaitingInputStage": "",
  "lastAwaitingInputKey": null,
  "rejectedInput": null,
  "progress": 0,
  "error": null,
  "activeTdsId": null,
  "inputs": [],
  "outputs": [],
  "piiRemoved": false,
  "sessionId": "510ecbab-75e9-44a3-9d21-163053bceb12",
  "sessionCount": 0,
  "successCode": null,
  "createdAt": 1650902387208,
  "updatedAt": 1650902387367,
  "finishedAt": null,
  "duration": 183
}

👆 The job was accepted and is now in the processing state. Here is an example of a job object.

List all Jobs

Returns a list of all the available jobs created by your client application.

Code sample

GET/jobs
curl -X GET 'https://api.automationcloud.net/jobs' \
    -H 'Authorization: Basic <credentials>' \
    -H 'Content-Type: application/json' \
    -G \
    -d 'serviceId=bd80b73a-af55-4087-a5d4-91f6c8619948' \
    -d 'state=awaitingInput&state=awaitingTds' \
    -d 'category=test' \
    -d 'sort=createdAt' \
    -d 'period=range' \
    -d 'since=1649116800718' \
    -d 'until=1649203199718' \
    -d 'limit=10' \
    -d 'offset=10'

Success Responses

Status 200

{
  "object": "list",
  "data": [],
  "totalCount": 0,
  "totalSessionCount": 0,
  "sort": "-createdAt"
}

An empty list of Automation Jobs.

{
  "object": "list",
  "data": [
    {
      "object": "job",
      "id": "e863af21-eea7-433f-822a-921871f13c5d",
      "serviceId": "bd80b73a-af55-4087-a5d4-91f6c8619948",
      "serviceName": "School Menu",
      "domainId": "Generic",
      "state": "processing",
      "category": "test",
      "awaitingInputKey": null,
      "awaitingInputStage": "",
      "lastAwaitingInputKey": null,
      "rejectedInput": null,
      "progress": 10,
      "error": null,
      "activeTdsId": null,
      "inputs": [],
      "outputs": [],
      "piiRemoved": false,
      "sessionId": "921f9609-014a-4cab-9262-2f28c0a1f85e",
      "sessionCount": 0,
      "successCode": null,
      "createdAt": 1649190861695,
      "updatedAt": 1649190861730,
      "finishedAt": null,
      "duration": 80604
    }
  ],
  "totalCount": 1,
  "totalSessionCount": 1,
  "sort": "-createdAt"
}

Jobs list.

Provide additional input

Supply additional job input at any time while the job is running. The data should be correctly formatted according to the Automation Protocolopen in new window.

WARNING

Note that we will not allow you to supply the same input key twice. This will result in the RecordNotUniqueError.

If you need to amend a previous input, consider the reset a job endpoint.

If an automation Job requires a file as an input, it can be provided as a Fileopen in new window object.

{
  "key": "photo",
  "data": {
    "type": "File",
    "url": "http://files.example.com/photos/userA.jpg",
    "filename": "userA.jpg",
    "headers": [ { "Authorization": "Bearer abc123" } ]
  }
}

Responding to in-flow requests for information

When the job can't proceed further without additional information, our service will request input from you by switching the job state to awaitingInput.

The awaitingInputKey field of the Job object communicates which piece of input you need to provide to continue. Additionally, to help you take action, the output field of the Job object may contain some relevant information. See also retrieve Job output.

Code sample

POST/jobs/:id/inputs
curl -X POST 'https://api.automationcloud.net/jobs/e863af21-eea7-433f-822a-921871f13c5d/inputs' \
    -H 'Authorization: Basic <credentials>' \
    -H 'Content-Type: application/json' \
--data '{
  "key": "ingredientToAvoid",
  "data": "almond"
}'

Success Responses

Status 200

{
  "object": "job-input",
  "jobId": "e863af21-eea7-433f-822a-921871f13c5d",
  "key": "ingredientToAvoid",
  "stage": "",
  "data": "almond"
}

👆 Here is an example of a job-input object you get in return.

List Job outputs

Returns a list of the output objects produced by the job.

Supply the unique job id that you can find in the job object.

Code sample

GET/jobs/:id/outputs
curl -X GET 'https://api.automationcloud.net/jobs/e863af21-eea7-433f-822a-921871f13c5d/outputs' \
    -H 'Authorization: Basic <credentials>' \
    -H 'Content-Type: application/json'

Success Responses

Status 200

{
  "object": "list",
  "data": [
    {
      "object": "job-output",
      "jobId": "e9416189-2f9b-4b7c-a594-f9aab12e9add",
      "key": "ingredients",
      "stage": "",
      "data": [
        "almond",
        "bean",
        "butter",
        "cheddar",
        "cinnamon",
        "cress",
        "cucumber",
        "egg",
        "flour",
        "lettuce",
        "oil",
        "onion",
        "salt",
        "sugar",
        "tahini",
        "water",
        "yeast"
      ],
      "createdAt": 1650991375490,
      "updatedAt": 1650991375490
    },
    {
      "object": "job-output",
      "jobId": "e9416189-2f9b-4b7c-a594-f9aab12e9add",
      "key": "menu",
      "stage": "",
      "data": [
        {
          "title": "Bean salad with tahini dressing",
          "description": "A mouth-watering bean salad served with tahini dressing.",
          "ingredients": "cucumber, lettuce, cress, bean, tahini"
        },
        {
          "title": "Tahini sandwich with onion relish",
          "description": "Tahini and onion relish served between slices of fresh bread.",
          "ingredients": "flour, yeast, water, salt, sugar, oil, onion, tahini, butter"
        },
        {
          "title": "Cheddar and yeast bread",
          "description": "Crunchy bread made with cheddar and fresh yeast.",
          "ingredients": "flour, salt, yeast, butter, water, onion, cheddar"
        }
      ],
      "createdAt": 1650991375627,
      "updatedAt": 1650991375627
    }
  ],
  "totalCount": 2
}

👆 The full list of job-output objects produced during the job.

Retrieve Job output

Retrieves the details of a particular job output object.

Supply the unique job id and job output key that you can find in the job object.

Code sample

GET/jobs/:id/outputs/:key/
curl -X GET 'https://api.automationcloud.net/jobs/e863af21-eea7-433f-822a-921871f13c5d/outputs/ingredients/' \
    -H 'Authorization: Basic <credentials>' \
    -H 'Content-Type: application/json'

Success Responses

Status 200

{
  "object": "job-output",
  "jobId": "e863af21-eea7-433f-822a-921871f13c5d",
  "key": "ingredients",
  "stage": "",
  "data": [
    "almond",
    "bean",
    "butter",
    "cheddar",
    "cinnamon",
    "cress",
    "cucumber",
    "egg",
    "flour",
    "lettuce",
    "oil",
    "onion",
    "salt",
    "sugar",
    "tahini",
    "water",
    "yeast"
  ],
  "createdAt": 1650991375490,
  "updatedAt": 1650991375490
}

👆 Here is an example of a job-output object you get in return.

Cancel a Job

Sends a request to cancel the job.

A cancelled job will have the fail state with the JobCancelledopen in new window job error code.

Code sample

POST/jobs/:id/cancel
curl -X POST 'https://api.automationcloud.net/jobs/e863af21-eea7-433f-822a-921871f13c5d/cancel' \
    -H 'Authorization: Basic <credentials>' \
    -H 'Content-Type: application/json'

Success Responses

Status 200

{
  "object": "job",
  "id": "e863af21-eea7-433f-822a-921871f13c5d",
  "serviceId": "bd80b73a-af55-4087-a5d4-91f6c8619948",
  "serviceName": "School Menu",
  "domainId": "Generic",
  "state": "fail",
  "category": "test",
  "awaitingInputKey": null,
  "awaitingInputStage": "",
  "lastAwaitingInputKey": null,
  "rejectedInput": null,
  "progress": 60,
  "error": {
    "object": "job-error",
    "code": "JobCancelled",
    "category": "client",
    "message": ""
  },
  "activeTdsId": null,
  "inputs": [],
  "outputs": [],
  "piiRemoved": false,
  "sessionId": "921f9609-014a-4cab-9262-2f28c0a1f85e",
  "successCode": null,
  "createdAt": 1649190861695,
  "updatedAt": 1649190861730,
  "finishedAt": 1649194475674,
  "duration": 3613979
}

👆 Here is an example of a job object you get in return.

Reset a Job

Sends a request to restart the job. The job will start from the beginning or proceed from a specific step.

WARNING

It is possible to reset a job in the processing, awaitingInput and fail within 15 minutes of the failure states.

Successful jobs and jobs which failed more than 15 minutes ago cannot be restarted.

Code sample

POST/jobs/:id/reset
curl -X POST 'https://api.automationcloud.net/jobs/e863af21-eea7-433f-822a-921871f13c5d/reset' \
    -H 'Authorization: Basic <credentials>' \
    -H 'Content-Type: application/json' \
--data '{
  "fromInputKey": "payment",
  "preserveInputs": [
    "ingredientToAvoid"
  ]
}'

Success Responses

Status 200

{
  "object": "job",
  "id": "e863af21-eea7-433f-822a-921871f13c5d",
  "serviceId": "bd80b73a-af55-4087-a5d4-91f6c8619948",
  "serviceName": "School Menu",
  "domainId": "Generic",
  "state": "processing",
  "category": "test",
  "awaitingInputKey": null,
  "awaitingInputStage": "",
  "lastAwaitingInputKey": null,
  "rejectedInput": null,
  "progress": 85,
  "error": null,
  "activeTdsId": null,
  "inputs": [],
  "outputs": [],
  "piiRemoved": false,
  "sessionId": "8efc024a-b880-47f0-bc0f-e217b2c5ab9b",
  "successCode": null,
  "createdAt": 1649197026130,
  "updatedAt": 1649197026167,
  "finishedAt": null,
  "duration": 23009
}

👆 The state of the job changes to `processing` again.

Retrieve an End User

Retrieves the end-user object of a job.

The end-user token is a Basic access token value that is valid in the scope of the job. No password is required.

Code sample

GET/jobs/:id/end-user
curl -X GET 'https://api.automationcloud.net/jobs/e863af21-eea7-433f-822a-921871f13c5d/end-user' \
    -H 'Authorization: Basic <credentials>' \
    -H 'Content-Type: application/json'

Success Responses

Status 200

{
  "object": "end-user",
  "id": "519e8807-5f86-4077-9ec7-0acf98aeed92",
  "clientId": "25dfe2a6-1be7-443b-a285-3cf4d237968c",
  "jobId": "e863af21-eea7-433f-822a-921871f13c5d",
  "serviceId": "bd80b73a-af55-4087-a5d4-91f6c8619948",
  "token": "74f30340f5245b6061fd8a5b56fbb342",
  "createdAt": 1651577121993,
  "updatedAt": 1651577121993
}

👆 Here is the end-user object you get in response.