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.


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


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 

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

"documentId": "<your documentId>",
"fileUrl": "<your fileId>"

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

curl -X PUT<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<your workflowId>/executions --json '{"documentId": "<your documentId>"}'

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<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<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"

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<your workflowId>/executions/<your executionId> --json '{"status": "completed"}'