> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usefini.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Database and Warehouse Connections

> Connect Fini to data warehouses such as Redshift by putting a scoped HTTPS endpoint in front of the warehouse.

Fini can use customer data from databases and data warehouses, but the agent flow does not connect to Redshift, Snowflake, BigQuery, Postgres, or another warehouse over JDBC or ODBC directly. Fini calls an HTTPS endpoint. That endpoint owns the warehouse credentials, network access, query logic, and response shape.

Use this pattern when an agent needs account status, subscription details, eligibility, order history, risk flags, or other structured customer context stored in a warehouse.

<Info>
  Fini's configurable calls are HTTP calls. A database or warehouse connection means `Fini -> HTTPS endpoint -> warehouse -> JSON response -> Fini`, not arbitrary SQL generated by the agent.
</Info>

## Recommended architecture

The recommended setup is a customer-hosted data access endpoint. Host a small API in AWS Lambda, API Gateway, Cloud Run, Cloud Functions, your backend, or another service that already has secure access to the warehouse.

```mermaid theme={null}
---
title: Warehouse lookup pattern
---
flowchart LR
    F["Fini<br/>Action or Attribute"] --> API["Customer HTTPS endpoint<br/>auth, validation, scoped routes"]
    API --> WH["Warehouse<br/>Redshift, Snowflake, BigQuery, Postgres"]
    WH --> API
    API --> JSON["Scoped JSON response"]
    JSON --> F
```

The endpoint should expose named lookup routes, not a general SQL interface. For example:

| Route | Input from Fini | Response fields |
| - | - | - |
| `GET /fini/account-status` | email or account ID | plan, lifecycle status, renewal date |
| `GET /fini/subscription` | user ID | tier, trial status, billing state |
| `POST /fini/order-eligibility` | account ID and SKU | eligible, reason code, policy message |

<Warning>
  Do not give the agent unrestricted warehouse access or let it construct arbitrary SQL. Keep query selection predefined, read-only when possible, and return only fields needed for personalization, guardrails, or workflow logic.
</Warning>

## Setup patterns

### Customer-hosted endpoint

Use this pattern by default.

<Steps>
  <Step title="Expose a scoped HTTPS route">
    Create one route per lookup or workflow. The route receives known user or conversation identifiers, queries the warehouse with predefined SQL, and returns JSON.
  </Step>

  <Step title="Protect the route">
    Require an API key, bearer token, mTLS, signed request, or another auth method your team can rotate. If your firewall restricts inbound traffic, allow Fini's [static outbound IPs](/en/api-reference/static-ip) to reach the endpoint on port 443.
  </Step>

  <Step title="Return a minimal JSON shape">
    Return only the fields Fini should use. Prefer stable field names such as `accountStatus`, `planName`, `isEligible`, and `policyReason`.
  </Step>

  <Step title="Configure Fini">
    Use an [Attribute](/en/api-reference/attributes) when the data should be fetched before every reply. Use an [Action](/en/api-reference/actions) when a [Rulebook](/en/automations/rulebook) Tool node should run the lookup only for a specific intent.
  </Step>

  <Step title="Map and test the response">
    In the Data Step, save the response fields Fini should keep. Then run the Test panel with staging users before attaching the Attribute to an agent or wiring the Action into a rule.
  </Step>
</Steps>

### Fini-hosted connector endpoint

Fini can also host or configure the HTTPS endpoint with you. In that case, your team must provide the connection details Fini needs to reach the warehouse or private network, and you must allowlist the relevant Fini egress addresses.

For Redshift, confirm the actual database port before allowlisting. The default Redshift port is usually `5439`, though some clusters are configured differently.

<Note>
  If you are testing against a staging warehouse or staging API, ask your Fini contact which staging egress addresses to allowlist. Production outbound IPs are listed on the [Static IP Addresses](/en/api-reference/static-ip) page.
</Note>

## Attribute or Action

Use the same data access endpoint from either product surface. The difference is when the call runs.

| Use case | Choose | Why |
| - | - | - |
| The agent should know the customer's plan, status, or eligibility before every reply. | [Attribute](/en/api-reference/attributes) | Attributes run automatically on every message for attached agents. |
| A customer asks for a specific lookup, workflow, or decision. | [Action](/en/api-reference/actions) | Actions run only when a Rulebook Tool node invokes them. |
| A rule should branch on a warehouse value without showing it to the customer. | Attribute | Toggle **Use in Rulebooks** and leave **Visible to AI** off. |
| The lookup is expensive or only relevant to one intent. | Action | The call runs only on the branch that needs it. |

## Configure the Data Step

Whether you are using an Attribute or an Action, the warehouse endpoint is configured as a Data Step: one HTTP request with a URL, method, headers, optional body, and response mapping.

Example Attribute lookup:

```http theme={null}
Method: GET
URL: https://api.example.com/fini/account-status?email=${User Email}
Headers: {"Authorization": "Bearer <warehouse_lookup_token>"}
Save From Response: {"accountStatus": "data.status", "planName": "data.plan.name", "isEligible": "data.eligibility.supportBot"}
```

Example Action lookup:

```http theme={null}
Method: POST
URL: https://api.example.com/fini/order-eligibility
Headers: {"Authorization": "Bearer <warehouse_lookup_token>"}
Body: {"accountId": "${accountId}", "sku": "${sku}"}
Save From Response: {"eligible": "eligible", "reasonCode": "reason.code", "policyMessage": "reason.message"}
```

Use [External API calls](/en/api-reference/actions-and-attributes) for the public API object model if you are creating these configurations programmatically.

## Customer checklist

Before testing, align on the exact integration contract:

* HTTPS endpoint URL for staging and production
* Auth method and header format
* Input fields Fini can pass, such as email, account ID, user ID, order ID, or SKU
* Response JSON schema and example responses
* Which response fields are safe for **Visible to AI**
* Which fields should only be available to **Rulebooks**
* Whether the endpoint is read-only or can trigger writes
* Network allowlisting requirements
* Expected latency, timeout behavior, and rate limits
* Sample staging users and test flows

<Tip>
  Keep the endpoint response narrow. A field can be useful to a rule without being useful to the LLM. Toggle **Visible to AI** only for fields the agent should be able to reference in a reply.
</Tip>

## Why a warehouse lookup isn't working

<AccordionGroup>
  <Accordion title="Fini cannot reach the endpoint" icon="clock">
    Confirm the endpoint is HTTPS, reachable from Fini's outbound IPs, and listening on the expected port. For customer-hosted APIs this is usually port 443. For Fini-hosted connector work, confirm the actual warehouse port and network route.
  </Accordion>

  <Accordion title="The endpoint works locally but fails in Fini" icon="shield-halved">
    Check the auth header format, allowlist, and environment. Staging and production endpoints often use different tokens, hostnames, and egress IPs.
  </Accordion>

  <Accordion title="The call succeeds but fields are empty" icon="arrow-right-arrow-left">
    Compare the Data Step **Save From Response** paths with the real JSON body. If your endpoint returns `data.account.status`, mapping `status` will not populate anything.
  </Accordion>

  <Accordion title="The agent mentions data it should not see" icon="eye-slash">
    Turn off **Visible to AI** for that field. Use **Use in Rulebooks** when the value should drive branching without being included in the model context.
  </Accordion>

  <Accordion title="The lookup adds too much latency" icon="gauge-high">
    Move expensive queries behind a cached endpoint, reduce the response size, or use an Action instead of an Attribute so the call runs only for the intents that need it.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Attributes" icon="id-card" href="/en/api-reference/attributes">
    Fetch warehouse-backed context automatically before each reply.
  </Card>

  <Card title="Actions" icon="wand-magic-sparkles" href="/en/api-reference/actions">
    Run a warehouse lookup only when a Rulebook Tool node invokes it.
  </Card>

  <Card title="External API calls" icon="plug" href="/en/api-reference/actions-and-attributes">
    Create and manage the Data Steps that call your HTTPS endpoint.
  </Card>

  <Card title="Static IP Addresses" icon="address-book" href="/en/api-reference/static-ip">
    Allowlist Fini's outbound traffic when your endpoint is behind a firewall.
  </Card>
</CardGroup>


## Related topics

- [Static IP Addresses](/en/api-reference/static-ip.md)
- [Overview](/en/api-reference/actions-and-attributes.md)
- [MCP Connections](/en/api-reference/connect-mcp.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.