Skip to main content

Using the REST API to run flows

In this guide we'll demonstrate how to use the REST API to integrate your flow into existing systems. All examples use the cURL command line tool, but any tool you're using that has support for making REST API calls will work similarly.


Prerequisites​

You need to have a Cradl AI account and have created a flow. If you haven't, go to flows and create one.


Step 1: Acquire API credentials​

Go to the API tab in Cradl to find or create API credentials. Read more on how to use the credentials to make authenticated requests here

caution

Remember to add the Authorization header to all API requests demonstrated in this guide or the requests will fail. Read more about how to get and add the Authorization header here


Step 2: Run a flow with a document​

Choose the REST API input integration on your flow by going to the flow builder in Cradl AI and locate the workflowId that will be required to run a flow.

REST API Input Integration


Uploading a document​

Next, upload the document that you want to send to the flow. In order to do that you need to create a document handle in the API.

curl -X POST https://api.lucidtech.ai/v1/documents

In the response you'll find a documentId and a fileUrl which we'll need for the next steps.

{
  "documentId": "<your documentId>",
  "fileUrl": "https://files.api.cradl.ai/<your fileId>"
}

Upload the document from your computer to Cradl AI using the fileUrl from the previous step.

curl -X PUT https://files.api.cradl.ai/<your fileId> --data-binary @my-document-file.pdf

Running the flow​

After successfully uploading a document to the API, you are now ready to run the flow with the workflowId that you got from the REST API integration card in the flow builder and the documentId from the previous step.

curl -X POST https://api.lucidtech.ai/v1/workflows/<your workflowId>/executions --json '{"documentId": "<your documentId>"}'
info

You can give the flow run a title by adding a string value for the key title in the POST request.

{
  "documentId": "<your documentId>",
  "title": "My flow run title"
}

Step 3: Validate the document in Cradl AI​

Go to the Cradl AI Validator and validate the document by going to Tasks, selecting the correct flow and completing the validation task.


Step 4: Fetch the final result​

After successfully running the flow on a document you can now get the result from the API. When you made the API call to POST https://api.lucidtech.ai/v1/workflows/<your workflowId>/executions in step 2 , the response contained an executionId. You will need the executionId in addition to the workflowId in order to get the output from the flow.

The output of the flow run contains values for all the fields automatically predicted by Cradl's AI, with potential corrections made by a validator. You can now be sure that the extracted data is correct and use it for further processing.

curl -X GET https://api.lucidtech.ai/v1/workflows/<your workflowId>/executions/<your executionId>

The response JSON will have a key called output which contains the final (validated) results.

{
  "executionId": "<your executionId>",
  "output": {
    "documentId": "<your documentId>",
    "values": {
      "my_flow_field_1": "some_value_1",
      "my_flow_field_2": "some_value_2"
    }
  }
}
info

Marking the flow run as completed will make it easier for you to track which runs have already been processed in your system and which ones have not.

curl -X PATCH https://api.lucidtech.ai/v1/workflows/<your workflowId>/executions/<your executionId> --json '{"status": "completed"}'