Processing Documents and Retrieving Results With the API
You can automate the data extraction process by using the IDP API to integrate your document actions with Mule applications and other systems. Integrating with IDP requires creating a connected app, obtaining the access token, and calling the IDP API to execute document actions and retrieve the results.
Use the IDP API to execute your published actions and retrieve the results of the execution. You can also specify a callback URL for IDP to call when the process finishes.
Instead of calling the IDP API to execute your document actions, you can use the Submit Document to MuleSoft IDP and Retrieve Results from MuleSoft IDP action steps from MuleSoft RPA. For instructions on integrating your document actions with MuleSoft RPA, see Processing Documents and Retrieving Results With RPA.
Before You Begin
Ensure you have the following Anypoint permissions:
- Execute Published Actions
-
Enables a user to execute a published document action and retrieve the results of the execution.
- Configure Connected Apps
-
Enables a user to configure a connected app to communicate with IDP.
Create a Connected App
To communicate with the IDP API, create a connected app with the following details:
-
Type:
App acts on its own behalf (client credentials) -
Scopes:
Execute Published Actions
After you create the connected app, copy its ID and Secret for further use when you obtain the access token.
For more information, see Connected Apps.
Obtain the Access Token
After you configure the connected app, use the following curl command to get the token:
curl --location --request POST 'https://anypoint.mulesoft.com/accounts/api/v2/oauth2/token' \ (1)
--header 'Content-Type: application/json' \
--data-raw '{
"grant_type": "client_credentials",
"client_id": "<connected-app-client-id>", (2)
"client_secret": "<connected-app-client-secret>" (3)
}'| 1 | If you are in the EU region, use the eu1.anypoint.mulesoft.com domain. |
| 2 | Replace <connected-app-client-id> with the client ID from your connected app. |
| 3 | Replace <connected-app-client-secret> with the client secret from your connected app. |
Use the access token when calling the IDP API.
Execute the Published Document Actions
After you publish document actions, configure a connected app, and obtain the access token, you can call the IDP API to execute your document actions.
The following is a sample call that provides guidance about how to construct an API call to execute a document action:
curl --location 'https://idp-rt.{region}.anypoint.mulesoft.com/api/v1/organizations/{orgId}/actions/{actionId}/versions/{actionVersion}/executions' \
--header 'Authorization: Bearer {token}' \
--form 'file=@"{pathToFile}"'Define a Callback URL
You can define a callback URL when you call IDP to execute your document actions. If defined, IDP calls the callback URL when the document action execution finishes.
To specify the callback URL, include the callback field in your API call and define a JSON value with the callback URL. The following example adds a callback to the previous curl command example:
curl --location 'https://idp-rt.{region}.anypoint.mulesoft.com/api/v1/organizations/{orgId}/actions/{actionId}/versions/{actionVersion}/executions' \
--header 'Authorization: Bearer {token}' \
--form 'file=@"{pathToFile}"' \
--form 'callback="{\"noAuthUrl\":\"{callbackURL}\"}"'Retrieve the Results of the Execution
After a document action successfully processes a document, or after a reviewer verifies and submits a document queued for review, the results are available for consumption.
When you use the IDP API to execute your document actions, retrieve the results by calling the /executions endpoint and providing an executionId, for example:
curl --location \
'https://idp-rt.{{region}}.anypoint.mulesoft.com/api/v1/organizations/{orgId}/actions/{actionId}/versions/{actionVersion}/executions/{executionId}/v2' \
--header 'Authorization: Bearer {token}'Execution Results Reference
When you query the results of an execution, the IDP API returns any of the following statuses:
-
ACKNOWLEDGED: The document action execution request was received. -
IN_PROGRESS: The execution started. -
RESULTS_PENDING: The execution finished and IDP is processing the results. -
MANUAL_VALIDATION_REQUIRED: The execution finished but the results need manual validation. -
FAILED: The execution request finished unsuccessfully. -
PARTIAL_SUCCESS: The execution request finished but some sub-tasks failed. -
SUCCEEDED: The execution request finished successfully.