--- schema_version: "1" id: 7da97fa1824f018ac0212b996bcd8dbdbf7915f64690b85e146bb5e96014f73d title: Processing Documents and Retrieving Results With the API collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/idp/automate-document-processing-with-the-idp-api.md canonical_url: https://docs.mulesoft.com/idp/automate-document-processing-with-the-idp-api source_site: docs.mulesoft.com content_type: documentation content_hash: a29074656a60e6fdae512ff048c9bc75352cd7a04d23849142ad58ecf418d508 description: MuleSoft Documentation Site latest: true --- --- product: IDP --- # Processing Documents and Retrieving Results With the API > For the full documentation index, see: https://docs.mulesoft.com/llms.txt 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](https://docs.mulesoft.com/idp/automate-document-processing-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](https://docs.mulesoft.com/access-management/connected-apps-overview). ## Obtain the Access Token After you configure the connected app, use the following `curl` command to get the token: ```bash 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": "", (2) "client_secret": "" (3) }' ```
1If you are in the EU region, use the eu1.anypoint.mulesoft.com domain.
2Replace <connected-app-client-id> with the client ID from your connected app.
3Replace <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:
RegionBase URL

US East (Virginia)

https://idp-rt.us-east-1.anypoint.mulesoft.com

EU Central (Frankfurt)

https://idp-rt.eu-central-1.eu1.anypoint.mulesoft.com

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: ```bash 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`, `DISMISSED`, 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: ```bash 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: ```bash 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. If a reviewer dismisses the review, the execution status changes to `DISMISSED` and the extracted results aren’t submitted. 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: ```bash 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: ```bash 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 > [!NOTE] If **Location callouts** is disabled, `geometry` shows `null`. - `pageNumber`: Page number where the field was found This example is a fragment of a response that shows the additional information. ```json ... "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 } }, ... ``` > [!NOTE] 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. - `DISMISSED`: A reviewer dismissed the review of the execution. The extracted results weren’t submitted. > [!IMPORTANT] Resubmitting a document after a `FAILED`, `PARTIAL_SUCCESS`, or `DISMISSED` execution > creates a new execution and consumes Automation Credits in full, in addition to the credits > already consumed by the original execution. See > [Automation Credit Consumption and Estimation](https://docs.mulesoft.com/idp/quotas-and-limits#automation-credits). ## 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. ## See Also - [Submit Document to MuleSoft IDP](https://docs.mulesoft.com/rpa-builder/latest/toolbox-mulesoft-idp-submit-document-to-mulesoft-idp) - [Retrieve Results from MuleSoft IDP](https://docs.mulesoft.com/rpa-builder/latest/toolbox-mulesoft-idp-retrieve-results-from-mulesoft-idp) - [Analyzing Documents Using Pre-Built Schemas](https://docs.mulesoft.com/idp/creating-document-actions) - [Publishing Document Actions](https://docs.mulesoft.com/idp/publishing-document-actions)