Skip to main content
An API proxy call is an authenticated passthrough to a connected app’s API, made through Refold. You call Refold, name the app and the action, and Refold attaches the linked account’s stored credentials before forwarding the request to the provider. No app tokens go in your request, and no per-app auth lives in your backend. This is how your product reads and writes data in a customer’s connected systems. Refold owns the credential storage, token refresh, and per-customer isolation, so your backend sends the same shape of request whether the app behind it is HubSpot, Salesforce, or NetSuite.
Write actions (create, update, delete) make real changes in the connected app. Test with a read action such as get_contact first, and use a sandbox account while you build.

​
How it works

Every proxy call is account-scoped and runs through the execute-action endpoint:
  • You name the app and action in the URL: an app slug (for example, hubspot) and an action_id (for example, get_contact).
  • You pass the action’s parameters in the body. The fields come from the action’s parameter schema, not from raw provider API shapes.
  • Refold injects credentials for the linked account named in the linked_account_id header, then forwards the call to the provider.
You authenticate to Refold with your API key. The customer’s app credentials never appear in your code.
All calls use the base URL https://app.refold.ai, send your API key in the x-api-key header, and send the customer’s linked_account_id as a header. The app credentials are stored against that linked account, so Refold knows which customer’s connection to use.

​
Find the available actions

Before executing, list the actions an app exposes and inspect a given action’s parameters.
cURL
curl "https://app.refold.ai/api/v2/integration-schema/hubspot/actions" \
  -H "x-api-key: $REFOLD_API_KEY" \
  -H "linked_account_id: user_12345"
For the parameter schema of one action, see Get action parameters.

​
Make a read call

A read action returns data in the provider’s native shape. Refold attaches the credentials, so the body holds only the action’s parameters.
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: user_12345" \
  -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)"
        },
        "createdAt": "2023-10-06T09:53:17.242Z",
        "archived": false
      }
    ],
    "paging": {}
  }
}

​
Make a write call

A write action changes data in the customer’s connected app. The pattern is identical, only the action and parameters differ.
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: user_12345" \
  -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"
  }
}
A node_status of Success means Refold authenticated as the customer and the provider accepted the call.

​
Custom actions for your own APIs

The actions above are the connectors Refold maintains. To proxy calls to an endpoint Refold doesn’t model, define a custom action (an API proxy) in the Console: give it fields, set the request method and URL, and reference it the same way as any other action.
1

Create the action

In the Refold Console, go to Settings > Developer > API Proxies, click New Action, and give it a name and description.
2

Add fields

On the Fields tab, add the inputs your call needs. These become the action’s parameters.
3

Configure the API call

On the API Call tab, set the HTTP method, URL, headers, and body. Reference your fields as variables in the request.
Custom actions can also run inside workflows as a node, so one definition serves both direct calls and multi-step automations.

​
Common errors

ResponseCauseFix
404 “Action … not found”The action_id or slug is wrong.List actions for the app and use an exact action_id.
Credential or auth failure from the providerThe linked account is not connected, or its token expired.Reconnect the app. Subscribe to the Connection Expired webhook to catch this.

​
Next steps

Execute action API

Full request, parameters, and response shapes.

Action parameters

Inspect the schema for any action before you call it.

Run a workflow

Chain reads, transforms, and writes across apps.

Handle connection health

Catch expired connections before a proxy call fails.