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 an HTTPS 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.
For more information, see Connected Apps in Anypoint Platform.
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.
Supported Regions
IDP is available in these regions:
| Region | Base URL |
|---|---|
US East (Virginia) |
|
EU Central (Frankfurt) |
|
Use the appropriate base URL for your region when calling the IDP API.
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}"'Replace {region} with either us-east-1 or eu-central-1.eu1 depending on your region.
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. The callback URL must use HTTPS.
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}\"}"'Upload a Base64-Encoded File
You can upload a Base64-encoded file when you call the IDP API to execute your versioned document actions. For example:
curl --location 'https://idp-rt.{region}.anypoint.mulesoft.com/api/v1/organizations/{orgId}/actions/{actionId}/versions/{actionVersion}/executions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--data '{
"file": {yourBase64string},
"fileName": {testFileName.pdf}
}'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}' \
--header 'Authorization: Bearer {token}'Include Confidence Scores and Metadata in Results
By default, the API returns only the extracted field values. To retrieve additional metadata such as confidence scores, field geometry (position and dimensions), and page numbers, add the valueOnly=false query parameter to your GET request:
curl --location \
'https://idp-rt.{{region}}.anypoint.mulesoft.com/api/v1/organizations/{orgId}/actions/{actionId}/versions/{actionVersion}/executions/{executionId}?valueOnly=false' \
--header 'Authorization: Bearer {token}'When you set valueOnly=false, the response includes the following additional information for each extracted field and table item:
-
confidenceScore: Confidence level of the extracted value (0-100) -
geometry: Position and dimensions of the field on the page-
width: Width of the field as a percentage of page width -
height: Height of the field as a percentage of page height -
left: Distance from the left edge as a percentage of page width -
top: Distance from the top edge as a percentage of page height
If Location callouts is disabled, geometryshowsnull. -
-
pageNumber: Page number where the field was found
This example is a fragment of a response that shows the additional information.
...
"fields": {
"shipVia": null,
"fob": null,
"carrier": null,
"tax": {
"value": "71.05",
"confidenceScore": 99.9162,
"geometry": {
"width": 0.044640772,
"height": 0.011198458,
"left": 0.88380444,
"top": 0.49255127
}
},
"purchaseOrderDate": {
"value": "06/28/2024",
"confidenceScore": 99.906105,
"geometry": {
"width": 0.08811343,
"height": 0.011008841,
"left": 0.8385502,
"top": 0.20239446
}
},
...
The valueOnly parameter is available when calling the IDP API directly using HTTP requests. This parameter is not supported when using the IDP connector in Anypoint Studio.
|
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.