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.

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

When you query a published document action, IDP uses the model selected in each prompt to extract the data for the corresponding field.

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 with state SUCCEEDED, FAILED, or MANUAL_VALIDATION_REQUIRED.

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}\"}"'

Use a Different Salesforce Org to Execute Your Document Actions

If you have multiple Salesforce Orgs connected with your Anypoint Platform organization, you can specify the Org to use when executing your document actions.

To specify a Salesforce Org, add the following header to the API call:

x-sfdc-core-tenant-id=<18-char-sfdc-org-id>

Replace <18-char-sfdc-org-id> with your Salesforce Org ID.

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.

IDP API Documentation

To confirm the endpoints to call to trigger document action executions and retrieve results, refer to the API documentation. The IDP API documentation is part of the specification and shows in the API portal after you publish the document actions to Anypoint Exchange.