Processing Documents and Retrieving Results With the API | MuleSoft Documentation
# 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.
For more information, see Secure API Integration with 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)**
}'
```

If you are in the EU region, use the `eu1.anypoint.mulesoft.com` domain.  
---  
Replace `<connected-app-client-id>` with the client ID from your connected app.  
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}\"}"'
```

### 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}/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.
## See Also
  * Submit Document to MuleSoft IDP
  * Retrieve Results from MuleSoft IDP
  * Analyzing Documents Using Pre-Built Schemas
  * Publishing Document Actions