> ## Documentation Index
> Fetch the complete documentation index at: https://cobalt-55-abhishek.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Read and write data
> Read records from a customer's connected app and write changes back by executing actions from your backend.
An **action** is a single operation a [connector](/v3/platform/concepts/connector/supported-apps-actions) exposes against a connected app, such as fetching a contact or creating one. Execute an action to read records from a customer's app or to write changes back, using the credentials Refold already holds for that [linked account](/v3/platform/concepts/linked-account).
Every action runs against one linked account. You pass the account in the `linked_account_id` header, and Refold resolves its stored credentials, so no app tokens go in your request. Read actions return data. Write actions change the connected app.
## How actions work
You call actions from your backend over HTTP. Each call names the app `slug`, the `action_id`, and the linked account to run against.
* **The app slug** identifies the connector, for example `hubspot`.
* **The action id** identifies the operation, for example `get_contact` or `create_contact`.
* **The `linked_account_id` header** selects whose connection to use. Refold resolves the stored credentials for that account.
* **The request body** holds the action's parameters, one key per field in the action's [parameter schema](/v3/api-reference/applications/get-action-parameters).
* **The response** returns the result in the app's native shape under `data`, with an execution `node_status`.
Every call uses the base URL `https://app.refold.ai`, sends your API key in the `x-api-key` header, and sends the customer's `linked_account_id` as a header. Keep your API key server-side. Never expose it in the browser.
## List available actions
Before you execute an action, confirm it exists for the app and get its `action_id`. List the actions a connected app supports with the [List Actions](/v3/api-reference/applications/get-actions) endpoint.
```bash cURL theme={null}
curl -X GET "https://app.refold.ai/api/v2/integration-schema/hubspot/actions" \
-H "x-api-key: $REFOLD_API_KEY" \
-H "linked_account_id: demo-user-1"
```
```json Output theme={null}
[
{ "name": "HTTP Request", "action_id": "httprequest", "description": "Make a raw HTTP request", "tag": "v2" },
{ "name": "Create Contact", "action_id": "create_contact", "description": "Creating a contact in Hubspot", "tag": "v2" },
{ "name": "Get Contact", "action_id": "get_contact", "description": "Fetch contacts", "tag": "v2" },
{ "name": "Search Contact", "action_id": "search_contacts", "description": "Search for contacts", "tag": "v2" }
]
```
Each `action_id` is what you pass to fetch the action's [parameter schema](/v3/api-reference/applications/get-action-parameters) and to execute it.
Read the parameter schema to learn an action's required and optional fields before you call it, so you know exactly what to put in the request body.
## Execute a read action
A read action fetches data and changes nothing. Execute one with the [Execute Action](/v3/api-reference/applications/execute-action) endpoint, passing the `action_id` in the path and any parameters in the body.
```bash cURL theme={null}
curl -X POST "https://app.refold.ai/api/v2/integration-schema/hubspot/actions/get_contact/execute" \
-H "x-api-key: $REFOLD_API_KEY" \
-H "linked_account_id: demo-user-1" \
-H "Content-Type: application/json" \
-d '{ "limit": "1" }'
```
```json Output theme={null}
{
"node_status": "Success",
"data": {
"results": [
{
"id": "51",
"properties": {
"email": "contact@example.com",
"firstname": "Brian",
"lastname": "Halligan (Sample Contact)",
"createdate": "2023-10-06T09:53:17.242Z"
},
"createdAt": "2023-10-06T09:53:17.242Z",
"updatedAt": "2024-05-15T18:35:12.877Z",
"archived": false
}
],
"paging": {}
}
}
```
The result arrives in the app's native shape under `data`. Read the fields you need straight from there.
## Execute a write action
A write action creates, updates, or deletes a record in the connected app. The call is the same shape as a read, with a write `action_id` and the new values in the body.
```bash cURL theme={null}
curl -X POST "https://app.refold.ai/api/v2/integration-schema/hubspot/actions/create_contact/execute" \
-H "x-api-key: $REFOLD_API_KEY" \
-H "linked_account_id: demo-user-1" \
-H "Content-Type: application/json" \
-d '{
"email": "jane@example.com",
"firstname": "Jane",
"lastname": "Doe"
}'
```
```json Output theme={null}
{
"node_status": "Success",
"data": {
"id": "1510721",
"createdAt": "2026-06-21T10:04:11.000Z"
}
}
```
Write actions (create, update, delete) make real changes in the customer's app. Test with a read action such as `get_contact` first, and use a sandbox account while you build.
## Single action or workflow
A single action call is the right tool when one operation does the job. Reach for a [workflow](/v3/platform/concepts/workflows/overview) when the job spans more than one step.
| Use a single action when | Use a workflow when |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| You need one read or one write | You read, transform, then write in sequence |
| Your backend drives the logic | You fan out to several apps or actions |
| The call is synchronous and you want the result back | A [trigger](/v3/platform/concepts/workflows/triggers/overview) (event, webhook, or schedule) should start the run |
| No mapping or validation is needed | You map and validate data between systems (see [Data mapping](/v3/native/move-data/data-mapping)) |
A workflow is built once on the Platform and runs across all three Refold products. This page does not re-document workflow building. See [Workflows overview](/v3/platform/concepts/workflows/overview).
## See also
Keep records aligned between your app and connected systems, one-way or two-way.
Transform and validate data as it moves between systems.
Full request and response reference for executing an action.
Orchestrate multi-step logic across apps and actions.