Skip to main content
An action is a single operation a connector 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. 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.
  • 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 endpoint.
cURL
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"
Output
[
  { "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 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 endpoint, passing the action_id in the path and any parameters in the body.
cURL
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" }'
Output
{
  "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.
cURL
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"
  }'
Output
{
  "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 when the job spans more than one step.
Use a single action whenUse a workflow when
You need one read or one writeYou read, transform, then write in sequence
Your backend drives the logicYou fan out to several apps or actions
The call is synchronous and you want the result backA trigger (event, webhook, or schedule) should start the run
No mapping or validation is neededYou map and validate data between systems (see 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.

​
See also

Sync data

Keep records aligned between your app and connected systems, one-way or two-way.

Data mapping

Transform and validate data as it moves between systems.

Execute Action API

Full request and response reference for executing an action.

Workflows overview

Orchestrate multi-step logic across apps and actions.