--- Source: https://docs.microblink.com/platform/api/transaction-api Title: Working with transactions Description: Create, manage, and query identity verification transactions via API --- # Working with transactions In this tutorial, you'll learn to interact with Microblink Platform API endpoints, to create transactions, progress them throughout the workflow, and to perform other useful things over the API. This tutorial assumes the following: - You already have an account set up. If not, see [account setup](../account-setup.md). - You have API credentials (`client_id` and `client_secret`). If not, follow the instructions in [Authentication](./authentication.md). SDK integration is not required, as all examples use direct `curl` calls. Note that this tutorial uses `us-east` as the region. When following along, make sure to use the correct [region](./overview.md#region) for your deployment. :::tip Before you start, it's useful to read the [API overview section](./overview.md). ::: ## Intro The platform uses two different APIs: an **Agent API** and an **Edge API**. The **Agent API** is used to initially create the transaction, and to access transaction history and analytics for a user account. The **Edge API** is used to progress **an individual transaction**. In production environments, your end users (mobile apps, clients) will first contact the Agent API (through some sort of [proxy](../proxy.md) service, or proxy-like code under your control). The Agent API will respond with further instructions, specifically where the client should continue with the transaction. This continuation (actually progressing the transaction throughout the workflow steps) is performed via the **Edge API**. Visually: ```mermaid graph LR SDK Agent["Agent API"] Proxy Edge["Edge API"] SDK <--Step 1--> Proxy <--Step 2--> Agent SDK <--Step 3+--> Edge ``` ## Build a workflow to test For this tutorial, we'll create the simplest possible workflow: one in which the user passes some data in the [initialization step](../capabilities/initialization-step.md). Create a workflow (see: [Build your workflow](../build-workflow.md)), but don't add any of the [capabilities](../capabilities/index.md). Configure the initialization step to expect exactly one field called "hello", like so: ![Initialization step expecting "hello"](/platform/img/start-node-hello-world.png) ## Create your first transaction ### Authenticate your request to the Agent API The Agent API uses HTTP Basic authentication with your `client_id` and `client_secret`. Save them in environment variables for use in the examples below: ```bash export CLIENT_ID="{your_client_id}" export CLIENT_SECRET="{your_client_secret}" ``` ### Create a request to start a transaction Now, start a transaction that uses your workflow. You need to get the workflow ID from the Platform web interface. It's going to look something like this: `6870ca44335606082bb4bf90`. #### JSON payload You also need to have a JSON payload. We'll use `curl` and a separate JSON file to make things more readable. Create your JSON file and name it `request_body.json` (or another descriptive name): ```json { "workflowId": "6870ca44335606082bb4bf90", "platform": "browser", "sdkVersion": "1.4.0", "formValues": { "hello": "world" // we're passing "world" to the declared "hello" field }, "consent": { "userId": "unique-user-id", "givenOn": "2025-08-29T09:00:00", "isProcessingStoringAllowed": true, "isTrainingAllowed": true } } ``` All of the above fields are required. We won't discuss the individual meaning of them in this tutorial, but to learn more, see our [API reference](/platform/api/agent). #### Running the first request Now, run your request. ```bash curl --url https://api.us-east.platform.microblink.com/agent/api/v1/transaction --user "$CLIENT_ID:$CLIENT_SECRET" --json @request_body.json | jq ``` The response will look like this: ```json {2,6,24,26} { "transactionId": "0168b58c71fa53b5c88c0caedd", "workflowId": "6870ca44335606082bb4bf90", "workflowVersionId": "68b58647b84a9097911b3f30", "organizationId": "66d99fa9edc165df54072f8c", "ephemeralKey": "qRqL.Mu2rINe835hF6MweR5AUw_j..." // cropped "authorization": "MDE2OGI1OGM3MWZhNTNiNWM4OGM..." // cropped "workflowInfo": { "stepCount": 2, "interactiveStepCount": 0, "hasConditionalInteractiveStep": false, "interactiveSteps": [], "completedInteractiveSteps": [], "currentStep": "End", "currentStepRetryCount": 0, "currentStepExecutionIndex": 1, "steps": [], "currentStepId": 2, "pendingStepIds": [], "completedStepIds": [] }, "createdOn": "2025-09-01T12:07:13.9506202Z", "modifiedOn": "2025-09-01T12:07:13.9511885Z", "processingStatus": "InProgress", "warnings": [], "edgeApiUrl": "https://api.us-east.platform.microblink.com/edge" } ``` A couple of things have happened now: 1. We now have a new transaction with its own transaction ID. 2. We have received an **ephemeral key** which we will use to continue this transaction. 3. We can see that the processing status is `InProgress` (the transaction is not yet completed). 4. Finally, we have received a URL (`edgeApiUrl`) at which we will complete the transaction. In our web interface, in the "Transactions" tab, we can see that a transaction has been created, but has not yet been completed: ![Transaction created but not completed](/platform/img/incomplete-transaction.png) ## Complete the created transaction Now, to complete the transaction, we must contact the **Edge API**.
A note on production environments :::note Most production environments should not use direct API access to the Edge API. Instead, client libraries (mobile and web SDKs) are the preferred way as they are preconfigured to work with individual [capabilities](../capabilities/index.md), and each capability has its own request/response schema. However, to illustrate how the API works, we will continue using direct `curl` calls even when contacting the Edge API. :::
### Authorize your request to the Edge API We will authenticate using the transaction ID and ephemeral key received in the previous response. The HTTP authorization header should be set like so: ``` Authorization: Basic {base64(transactionId:ephemeralKey)} ``` ### Running the second request We will use the Edge API URL received from the previous response and append the full path for resuming transactions: `/api/v1/transaction/{transactionId}/resume`. Putting it all together, we run this `curl` example: ```bash curl --request POST --user "{transaction_id}:{ephemeral_key}" --url "https://api.us-east.platform.microblink.com/edge/api/v1/transaction/{transaction_id}/resume" | jq ``` When the transaction is complete, the response from the "resume" endpoint returns either "Complete" or "Error", as highlighted below: ```json {4} { "transactionId": "0168b58c71fa53b5c88c0caedd", "isChanged": true, "processingStatus": "Complete", "verificationStatus": "Accept", "workflowInfo": { "stepCount": 2, "interactiveStepCount": 0, "hasConditionalInteractiveStep": false, "interactiveSteps": [], "completedInteractiveSteps": [], "currentStep": "End", "currentStepRetryCount": 0, "currentStepExecutionIndex": 1, "steps": [], "currentStepId": 2, "pendingStepIds": [], "completedStepIds": [] }, "hasConsent": true } ``` You will see that same transaction in the web UI now display as completed: ![The transaction is now complete](/platform/img/complete-transaction.png) ## Access a transaction You can access a transaction at any point after it has been created, even during its execution, for example: ```sh curl --url "https://api.us-east.platform.microblink.com/agent/api/v1/transaction/{transaction_id}" --user "$CLIENT_ID:$CLIENT_SECRET" ``` The response is a JSON object with information about that specific transaction: ```json { "id": "0168b58c71fa53b5c88c0caedd", "workflowId": "6870ca44335606082bb4bf90", "workflowVersionId": "68b58647b84a9097911b3f30", "partnerId": "66d99fa9edc165df54072f8a", "companyId": "66d99fa9edc165df54072f8b", "organizationId": "66d99fa9edc165df54072f8c", "platform": "Browser", "sdkVersion": {}, "createdOn": "2025-09-01T12:07:13.95Z", "modifiedOn": "2025-09-01T14:10:13.999Z", "processingStatus": "Complete", "verificationStatus": "Accept", "originalVerificationStatus": "Accept", "statusLog": [], "state": {}, "tags": [], "linkFields": {}, "consent": {} } ``` This is a shortened version, and the complete transaction schema is available [in the API reference](/platform/api/agent#tag/transaction/GET/api/v1/transaction/{transactionId}). ## Update verification status You can also update the verification outcome for **completed** transactions. ```bash curl --request PUT --url https://api.us-east.platform.microblink.com/agent/api/v1/transaction/{transaction_id}/verification-status --user "$CLIENT_ID:$CLIENT_SECRET" --json '{"verificationStatus": "Reject","comment": "My manual update"}' ``` The `verificationStatus` is a mandatory field, and possible values are: - `Accept` - `Reject` - `Review` Changing this value doesn't affect the `originalVerificationStatus` field, which will always reflect the status set at workflow completion time. The `comment` field is optional and can provide context as to why an update was made. You can see the result of this manual update in the UI: ![Verification: manually rejected](/platform/img/transaction-manually-rejected.png) ## Delete a transaction Finally, you can delete a transaction. It is only possible to delete a transaction after it's been completed. While being executed, transactions are locked for deletion. ```bash curl --request DELETE --user "$CLIENT_ID:$CLIENT_SECRET" --url https://api.us-east.platform.microblink.com/agent/api/v1/transaction/{transaction_id} ``` Once the transaction has been deleted, it will no longer show up in the list of transactions in the Transactions tab. --------- And that's it! In this tutorial, you've successfully: 1. Built a workflow. 2. Authenticated to the Agent API. 3. Created a transaction. 4. Completed the transaction using the Edge API. 5. Accessed the details of the transaction. 7. Performed a manual verification override. 8. Deleted the transaction. Last updated on Jun 18, 2026