> For the complete documentation index, see [llms.txt](https://docs.borndigital.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.borndigital.ai/digital-agent/tools-reference/web-apis-and-data.md).

# Web, APIs & data

Calling web services, sending e-mails and working with JSON and files.

Calling web services, sending e-mails and working with JSON and files. How to add a tool and use its result is described in [Tools & smart functions](https://docs.borndigital.ai/digital-agent/tools-reference.md).

| Tool                 | Technical name         | What it does                                                                                                                                           | Languages |
| -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- |
| Download to base64   | `download_to_base64`   | Downloads a file from a URL and converts it to a base64 string.                                                                                        | any       |
| Fetch Url            | `fetch_url`            | Call external link using given method and data and return the response.                                                                                | any       |
| Normalize images     | `normalize_images`     | Make images LLM-ready via image-handler: upright, downscaled, same form and order as the input.                                                        | any       |
| Send email           | `send_email`           | Send email to one or more recipients using SMTP                                                                                                        | any       |
| SOAP extractor       | `soap_extractor`       | Send a SOAP request and return the response data with raw request and response XML                                                                     | any       |
| Unpack JSON          | `unpack_json`          | Parse a JSON object and store every top-level key as a separate variable.                                                                              | any       |
| Update JSON variable | `update_json`          | Update an existing JSON variable by merging it with one or more new dictionaries                                                                       | any       |
| Upload to Blob       | `upload_to_blob`       | Upload a file or text to Azure Blob Storage and return the blob URL or a temporary download link.                                                      | any       |
| URL Decode           | `unquote`              | Decode a URL-encoded string.                                                                                                                           | any       |
| User data management | `user_data_management` | Select rows from Input data in Data Sources based on input filters defined in Input column and return content from specified columns in Output Columns | any       |

## Download to base64

Technical name: `download_to_base64`

Downloads a file from a URL and converts it to a base64 string.

* Can also be used in expressions as `download_to_base64()`.

| Parameter | Name  | Required | Default | Description                  |
| --------- | ----- | -------- | ------- | ---------------------------- |
| URL       | `url` | yes      |         | URL of the file to download. |

**Example input:** {'url': '<https://example.com/file.pdf'}>

**Example output:**

```
base64 encoded string
```

## Fetch Url

Technical name: `fetch_url`

Call external link using given method and data and return the response.

| Parameter       | Name              | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                   |
| --------------- | ----------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| URL             | `url`             | yes      |         | URL of the webservice.                                                                                                                                                                                                                                                                                                                                                                        |
| Method          | `method`          | yes      | `POST`  | HTTP method to use.                                                                                                                                                                                                                                                                                                                                                                           |
| JSON body       | `json_body`       | no       |         | Data to send to the backend as JSON.                                                                                                                                                                                                                                                                                                                                                          |
| Data            | `data`            | no       |         | Data to send to the backend as form data.                                                                                                                                                                                                                                                                                                                                                     |
| Files           | `files`           | no       |         | Files to send to the backend as multipart/form-data, as pairs of file name and content, for example `{"invoice.pdf": "{binary_invoice}"}`. Content may be raw bytes, a base64 data URI (what `binary_` variables expand to), or `{'content': ..., 'type': '<mime type>', 'field': '<form field name>'}` with type and field optional. Filenames and contents support {placeholder} variables. |
| File field name | `file_field_name` | no       | `file`  | Default multipart form-field name the file parts are sent under (default 'file'). Individual files can override it via {'field': ...} in their content dict.                                                                                                                                                                                                                                  |
| Timeout         | `timeout`         | no       | `1.0`   | Wait at most before timeout, in seconds.                                                                                                                                                                                                                                                                                                                                                      |
| Headers         | `headers`         | no       |         | Dictionary of HTTP Headers to send with the Request.                                                                                                                                                                                                                                                                                                                                          |
| Cookies         | `cookies`         | no       |         | Cookies to send with the request, as name–value pairs.                                                                                                                                                                                                                                                                                                                                        |
| Auth method     | `auth_method`     | no       |         | One of 'HTTPBasicAuth', 'HTTPDigestAuth' and 'HTTPDigestAuth'.                                                                                                                                                                                                                                                                                                                                |
| Username        | `username`        | no       |         | Username for authentication.                                                                                                                                                                                                                                                                                                                                                                  |
| Password        | `password`        | no       |         | Password for authentication.                                                                                                                                                                                                                                                                                                                                                                  |
| Certificate     | `cert`            | no       |         | SSL client cert file.                                                                                                                                                                                                                                                                                                                                                                         |
| Proxies         | `proxies`         | no       |         | Dictionary mapping protocol to the URL of the proxy.                                                                                                                                                                                                                                                                                                                                          |
| Verify          | `verify`          | no       | `True`  | Whether to verify the server's TLS certificate. Set to true, in which case it controls whether we verify the server's TLS certificate, or a string, in which case it must be a path to a CA to be used. use false, if certificate validationshould be turned of                                                                                                                               |
| Non blocking    | `non_blocking`    | no       | `False` | If set to True, we spawn the process in a new thread.                                                                                                                                                                                                                                                                                                                                         |
| Log             | `log`             | no       | `True`  | If set to True, we log request/response as an interaction to logstash.                                                                                                                                                                                                                                                                                                                        |
| Delay           | `delay`           | no       |         | If set to integer 0-X, we wait for X seconds before sending the request.                                                                                                                                                                                                                                                                                                                      |

**How to use it**

* **URL**, **Headers** and **JSON body** can contain variables, for example `https://api.example.com/orders/{order_id}`.
* The default **Timeout** is only **1 second**. Raise it (for example to `5`) for slower services – otherwise the call ends with an error.
* Tip: paste a cURL command into the tool (Ctrl/Cmd + V) – Studio fills in the URL, method, headers and body for you.

**What you get back** in the variable you named in **Tool name** (say `weather`):

* a JSON response as data – read its parts with `weather["temp"]`,
* a text, XML or HTML response as text,
* on an error status: `{"error": "Response status code not 2xx…", "response_payload": …}`; on a timeout or an invalid URL: `{"error": "…"}`.

The tool also sets `weather_http_status` (the HTTP status code), `response_headers_weather` and `response_cookies_weather`. Check the status before using the data, for example with a Decision node on `weather_http_status == 200`.

With **Non blocking** on, the flow does not wait – the result arrives at the start of the next interaction.

## Normalize images

Technical name: `normalize_images`

Make images LLM-ready via image-handler: upright, downscaled, same form and order as the input.

| Parameter          | Name           | Required | Default | Description                                                                                                                                                                                                                                                                                 |
| ------------------ | -------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Images             | `images`       | yes      |         | Required. One image or a list of images: HTTPS Azure Blob URL (SAS allowed), base64 data URI or raw base64. Supports {placeholder} variables; a `binary_` variable is sent as its URL, not downloaded. Empty or non-string entries come back unchanged as `failed`.                         |
| Max side           | `max_side`     | no       |         | Optional. Longest side of the output in pixels; 0 = no downscaling. Not sent when absent (service default 2000). Invalid value -> error, no call.                                                                                                                                           |
| Output form        | `output`       | no       |         | Optional. Form of the output images: same\_as\_input (default), blob or base64. Not sent when absent. Invalid value -> error, no call.                                                                                                                                                      |
| Timeout            | `timeout`      | no       |         | Optional. Seconds the call may wait for the service, all batches included; a batch still waiting at the deadline falls back, one already received is kept. Overrides IMAGE\_HANDLER\_TIMEOUT\_SECONDS (default 120).                                                                        |
| Merge into one PDF | `merge_to_pdf` | no       | `false` | Optional. `true` = normalize the images and join them, with any PDF inputs, into one PDF in input order (at most 20 inputs). The output is then `{'pdf', 'pages', 'items'}`, plus `content` (raw base64) for an inline PDF and `error` when no PDF was made. One unreadable input = no PDF. |

**Merge into one PDF** – for example when the next system takes exactly one file, such as photos of a two-page form plus a PDF the customer already has. Each photo becomes one A4-sized page, a PDF is added with all its pages. A PDF is never made with a page missing: if any input cannot be read, `pdf` is empty, `error` says why and the flow continues. Use `output: base64` and `merged['content']` when the next step needs the file as base64; put the variable among the not-logged variables, because it then holds the whole PDF.

```yaml
- merged: [normalize_images, {images: "{uploaded_files}", merge_to_pdf: true, output: base64}]
```

## Send email

Technical name: `send_email`

Send email to one or more recipients using SMTP

| Parameter             | Name            | Required | Default | Description                                        |
| --------------------- | --------------- | -------- | ------- | -------------------------------------------------- |
| SMTP host             | `smtp_host`     | yes      |         | Hostname of the SMTP server                        |
| SMTP port             | `smtp_port`     | no       | `25`    | Port of the SMTP server                            |
| SMTP password         | `smtp_password` | no       |         | Password for SMTP authentication                   |
| SMTP username         | `smtp_username` | no       |         | Username for SMTP authentication                   |
| Subject               | `subject`       | yes      |         | Subject of the email                               |
| Sender address        | `address_from`  | yes      |         | Sender email address                               |
| Recipients            | `address_to`    | yes      |         | Recipient email address or list of addresses       |
| Reply-To              | `reply_to`      | no       |         | Reply-To email address or list of addresses        |
| CC Recipients         | `address_cc`    | no       |         | CC recipient email address or list of addresses    |
| BCC Recipients        | `address_bcc`   | no       |         | BCC recipient email address or list of addresses   |
| HTML content          | `html`          | no       |         | HTML content of the email body                     |
| Text content          | `text`          | no       |         | Plain-text content of the email body               |
| Attachments           | `attachments`   | no       |         | Mapping of filenames to file bytes for attachments |
| Authentication method | `auth_method`   | no       | `PLAIN` | Authentication method to use ('PLAIN' or 'NTLM')   |

**Example input:** This function does not use the user input utterance.

**Example output:**

```
True
```

## SOAP extractor

Technical name: `soap_extractor`

Send a SOAP request and return the response data with raw request and response XML

* Not shown in the tool list until you type its name – start typing `soap_extractor`.
* Advanced – usually set up together with Born Digital.

**Example input:** This function does not use the user input utterance.

**Example output:**

```
{'payload': {'Customer': {'Name':'Alice'}}, 'request_xml': '<Envelope>...sent</Envelope>', 'response_xml': '<Envelope>...received</Envelope>'}
```

## Unpack JSON

Technical name: `unpack_json`

Parse a JSON object and store every top-level key as a separate variable.

* Can also be used in expressions as `unpack_json()`.

| Parameter       | Name     | Required | Default | Description                                                                                                                                        |
| --------------- | -------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Value           | `value`  | yes      |         | JSON encoded string or dictionary variable to unpack.                                                                                              |
| Variable prefix | `prefix` | no       |         | Optional prefix prepended to every created variable name.                                                                                          |
| Strip from keys | `strip`  | no       |         | Optional substring removed from every top-level key before creating the variable name, e.g. strip `_c_` turns `_c_VA_OrigLine` into `VA_OrigLine`. |
| Keys to unpack  | `keys`   | no       |         | Optional list of top-level keys to unpack. All keys are unpacked when empty.                                                                       |

**Example input:** {"VA\_WhiteList": false, "VA\_ActiveTT": false}

**Example output:**

```
{'VA_WhiteList': False, 'VA_ActiveTT': False}
```

## Update JSON variable

Technical name: `update_json`

Update an existing JSON variable by merging it with one or more new dictionaries

| Parameter             | Name                 | Required | Default | Description                                          |
| --------------------- | -------------------- | -------- | ------- | ---------------------------------------------------- |
| JSON variable name    | `json_variable_name` | yes      |         | Name of the JSON variable to update                  |
| Dictionaries to merge | `values`             | yes      |         | List of dictionaries to merge into the JSON variable |

**Example input:** json\_variable\_name='user\_profile', values=\[{'age': 35}, {'preferences': {'theme': 'dark'}}]

**Example output:**

```
{'age': 35, 'preferences': {'theme': 'dark'}}
```

## Upload to Blob

Technical name: `upload_to_blob`

Upload a file or text to Azure Blob Storage and return the blob URL or a temporary download link.

| Parameter              | Name                   | Required | Default | Description                                                                                                                                                                                                                                                                                                                              |
| ---------------------- | ---------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content                | `content`              | yes      |         | Blob content. May be raw bytes, a base64 data URI (what `binary_` variables expand to), a plain string (stored utf-8 encoded), or `{'content': ..., 'type': '<mime type>'}`. Supports {placeholder} variables, including `binary_` ones.                                                                                                 |
| URL                    | `url`                  | no       |         | Full destination blob URL (<https://.blob.core.windows.net//>); may carry a SAS token in its query. The blob name's extension is used to guess the content type when none is given. Omit it together with `credential` for engine mode (the engine's temporary container, random name, download link). Supports {placeholder} variables. |
| Credential             | `credential`           | no       |         | SAS token or storage account access key used to authenticate the upload; not needed when the URL carries a SAS token. Only an account key can sign a download link. Reference it as a {placeholder} of a variable listed in BOTH secret\_variables and not\_logged\_variables.                                                           |
| Content type           | `content_type`         | no       |         | Explicit MIME type stored with the blob. Defaults to the data URI mime, then a guess from the file name, then from the blob name, then application/octet-stream.                                                                                                                                                                         |
| Overwrite              | `overwrite`            | no       | `True`  | Overwrite the blob if it already exists (default true). When false, uploading over an existing blob returns an error result. Engine mode never overwrites.                                                                                                                                                                               |
| File name              | `file_name`            | no       |         | Name the browser saves the downloaded file under (stored as Content-Disposition: attachment; the blob name does not change). Supports {placeholder} variables.                                                                                                                                                                           |
| Link expires (minutes) | `link_expires_minutes` | no       |         | Return a read-only `download_url` valid for this many minutes (at least 1; at most 7 days in engine mode) with its `expires_at`. Default 60 in engine mode; with a flow destination a link is made only when this is given. Supports {placeholder} variables.                                                                            |

## URL Decode

Technical name: `unquote`

Decode a URL-encoded string.

* Can also be used in expressions as `unquote()`.

| Parameter    | Name              | Required | Default | Description                       |
| ------------ | ----------------- | -------- | ------- | --------------------------------- |
| Encoded Text | `text_to_unquote` | yes      |         | The URL-encoded string to decode. |

**Example input:** text\_to\_unquote='Hello%20World%21'

**Example output:**

```
Hello World!
```

## User data management

Technical name: `user_data_management`

Select rows from Input data in Data Sources based on input filters defined in Input column and return content from specified columns in Output Columns

* Can also be used in expressions as `user_data_management()`.

| Parameter          | Name                 | Required | Default         | Description                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------ | -------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Table name         | `table_name`         | yes      |                 | Name of the table in Input data to query                                                                                                                                                                                                                                                                                                                                                                            |
| Input column       | `input_column`       | yes      |                 | Mapping of column names to values to filter rows                                                                                                                                                                                                                                                                                                                                                                    |
| Output columns     | `output_columns`     | yes      |                 | List of column names to include in the output                                                                                                                                                                                                                                                                                                                                                                       |
| Cosine similarity  | `cosine_similarity`  | no       |                 | Fuzzy text match by cosine similarity method. Provide a dict with {'cosine\_score': <0.0-1.0>}. When set, string fields specified in 'input\_column' are compared to each row using character n-gram TF-IDF and rows with the average score above the threshold are returned (sorted by score). For multiple tables, pass a list aligned with 'table\_name' (use null where not used). Typical threshold: 0.6-0.85. |
| Edit distance      | `edit_distance`      | no       |                 | Fuzzy text match by edit distance method. Provide either {"edit\_distance": } to threshold per-column Levenshtein distance (results include 'summed\_distance'), or {"edit\_distance\_input\_columns": } to compare the concatenated input fields (results include 'input\_column\_distance'). For multiple tables, pass a list aligned with 'table\_name' (use null where not used). Lower distance is better.     |
| Ignore case        | `ignore_case`        | no       | `False`         | Whether to ignore case sensitivity for string columns                                                                                                                                                                                                                                                                                                                                                               |
| Generic vectorizer | `generic_vectorizer` | no       | `False`         | Whether to use a generic vectorizer for text similarity                                                                                                                                                                                                                                                                                                                                                             |
| Non-blocking       | `non_blocking`       | no       | `False`         | Whether to perform the query asynchronously                                                                                                                                                                                                                                                                                                                                                                         |
| Edit distance mode | `edit_distance_mode` | no       | `edit_distance` | Edit distance algorithm to apply                                                                                                                                                                                                                                                                                                                                                                                    |

**Example input:** not applicable

**Example output:**

```
[{"name": "John", "email": "john.doe@gmail.com", "age": "30"}]
```
