Execute a Batch Request

This endpoint processes a batch of resource calls in one go.

1. Requires an integrated_account_id, which must be accessible to the user based on environment permissions.
2. Requires a list of resources describing how each resource call should be made, including optional dependencies.
3. Processes these calls in an order that respects dependencies and loops (loop_on).
4. Handles signature or re-auth logic if the integrated account needs reauthorization.
5. Returns a combined result including successful records and any errors encountered.

An example of a batch request would look like this -

curl --location 'https://api.truto.one/batch-request' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: ••••••' \
  --data '{
    "integrated_account_id": "<replace with your integrated account id>",
    "args": {
      "page_id": "<replace with your notion page id>"
    },
    "resources": [
      {
        "name": "page-content",
        "resource": "block-children",
        "method": "list",
        "query": {
          "block_id": "{{args.page_id}}",
          "truto_ignore_remote_data": true
        },
        "recurse": {
          "if": "{{resources.block-children.has_children:bool}}",
          "config": {
            "query": {
              "block_id": "{{resources.block-children.id}}"
            }
          }
        },
        "persist": false
      },
      {
        "name": "all-page-content",
        "type": "spool",
        "depends_on": "page-content"
      },
      {
        "name": "combine-page-content",
        "type": "transform",
        "config": {
          "expression": "$convertNotionToMarkdown($sortNodes($map(resources.`block-children`, function($v) {$merge([$v, {'parent_id': $firstNonEmpty($v.parent.page_id, $v.parent.block_id)}])}), 'id', 'parent_id'))"
        },
        "depends_on": "all-page-content",
        "persist": true
      }
    ]
  }'

In the above example, we have the page content in Notion blocks which is converted into Markdown format (.md), joined together one by one using spool and returned as part of the batch request reponse. The depends_on options help in executing it step by step wherein one results depends on another. The batch requests are similar to Sync Jobs - just that they are much simpler in terms of setting up - the data can be returned as part of the same Request/Response cycle.

Endpoint

POST /batch-request

Request Body

integrated_account_id

string · uuid

The ID of the integrated account in whose context these resource calls are made.

args

object

Optional arguments available for placeholder replacement in resource definitions.

Example: { "my_placeholder": 123 }

resources

object[]

A list of resource definitions that can be either a request or a transform.

resource

string

REQUIRED · 

The name of the resource to sync. For Unified APIs, it should be in the format unified_api_name/resource_name. For Proxy API, it can just be resource_name.

Example: For fetching Contacts from CRM Unified API, `crm/contacts`. For fetching Contacts from a Proxy API, `contacts`.

method

string

REQUIRED · 

The method to call on the resource.

Example: list

id

string

The ID of the resource to sync. This is optional and can be used to sync a single resource. It also supports placeholders.

Example: Static value like `4a4de828-f4db-4c9e-adfd-434e0864c3c7` or placeholder like `{{args.user_id}}`.

query

object

The query parameters to pass to the resource method. It supports placeholders for values.

Example: { "page": 1, "per_page": 100, "user_id": "{{args.user_id}}" }

loop_on

string

When a particular placeholder argument is an array and you want to repeat the request for each element in that array, you can set this parameter. For example, if you accept an argument called user_ids which is an array of strings, and you want to fetch each user's details, you can set this parameter to user_ids and the request will be repeated for each element in the user_ids array.

Example: { "{ args.user_ids }": null }

depends_on

string

The resource that this resource depends on (parent resource). This is optional and can be used to sync a resource only after another resource has been synced. Each object synced for the parent resource is available as the resources object in placeholders for the child resource, e.g. {{resources.crm.contacts.id}} if depends on is crm/contacts resource.

Example: crm/contacts

persist

boolean

Whether to persist the resource in the database or not in case of a Daemon sync job run or send as a payload in case of RapidBridge sync job run. The Proxy API resources are by default NOT persisted and this parameter can be set to true to persist them. Unified API resources are always persisted.

Response Body

result

object

A map of resource names to fetched records.

errors

object

A map of resource names to encountered errors (if any).