How to connect a REST API to Hubviz

Build a cube that fetches data from a REST API. It works with any system whose API answers in JSON, such as ERPs, CRMs and ad platforms.

When to use it

• The system has an API and you want Hubviz to fetch the data at the time you choose.
• The API returns JSON. A list of records (orders, opportunities, entries) becomes the rows of the cube.

If the system should send the data to Hubviz when something happens, use a webhook.

Before you start, have the API documentation at hand: the base URL, the authentication type and the endpoint that returns the data.

How the setup is split

Where	What it keeps	Applies to
Connection	Base URL, authentication, common headers, parameters and body, call limit	Every cube that uses this API
Cube	Method, endpoint path, pagination, data path and its own headers or parameters	That cube only

So a CRM with several endpoints (opportunities, contacts, activities) uses one connection and one cube per endpoint.

Create the connection

Does the base URL have a path?

If the base URL has something after the domain, such as /v2, Hubviz asks what to do when you save:

Button	What happens
Save base only (Salvar apenas base)	Keeps only https://api.aurora-crm.com. You enter /v2/... in each cube’s endpoint. Recommended.
Keep full (Manter completa)	Keeps the URL with /v2. Cube endpoints start after it.
Cancel (Cancelar)	Goes back to the window without saving.

This window is shown in Portuguese even when the Studio is in English.

Connection tabs

Tab	What it does
Authentication	Authentication type and credentials.
Request Headers	Headers sent on every call, such as Accept: application/json.
Params	URL parameters sent on every call, such as company=12.
Body	Common body for POST calls, in JSON or another format picked in the editor.
Limits	Requests Per Minute: the maximum number of calls per minute. Blank means no limit.

The connection limit applies to every cube. In the cube, the same field shows the connection value with a globe icon (Applied from data source). Fill it in there only if that endpoint has a different limit.

Authentication types

Type	When to use it	Fields
None	Public API, no login	None. The Test Authentication button goes away.
Basic Auth	The API asks for a user and password	Username and Password. Sent in the Authorization: Basic header.
Bearer Token	The API gives you a fixed token	Token. Sent in the Authorization: Bearer header.
API Key	The API gives you a key	API Key, Placement and Parameter Name (table below).
OAuth 2.0	The API uses OAuth 2.0	Four sections: credentials, endpoints and scopes, redirect and security, advanced.
Pre-Request	You must call a login endpoint that returns a token	Three sections: request, test and token placement.

API key

Field	What it does
API Key	The key the API gave you. It stays masked. The eye icon shows the value.
Placement	Where the key goes: Header (default), Query Parameter, Cookie or Request Body.
Parameter Name	Name of the header or parameter, such as X-API-Key or api_key. Disabled when the key goes in the body.
Body Format	Only with the key in the body: JSON or x-www-form-urlencoded.
Field Name in Body	Only with the key in the body: the field name, such as apiKey or token.

OAuth 2.0

Section	Fields
1. Credentials	Client ID and Client Secret, from the provider.
2. Endpoints and scopes	Authorization Endpoint URL, Token Endpoint URL and Scopes. Type each scope and press Enter.
3. Redirect and security	Redirect URI Strategy (Local HTTP Server, Custom Protocol or a Hubviz managed URL), Redirect URI, Token Endpoint Client Auth Method (credentials in the body or in the Basic header) and Enable PKCE.
4. Advanced	Extra parameters and headers sent to the token endpoint. Optional.

Token requested before each fetch

Pick Pre-Request when the token expires and must be requested again before each fetch.

1. Configure Request: the login URL, the method (POST by default), the headers and the body, such as {"user": "bi", "password": "{{ENCRYPT(...)}}"}. Click Next.
2. Test & Extract Token: click Send Request. In the response, click the token value. Hubviz fills in Token Location in Response (JSON body or header) and Token Path / Header Name, such as data.access_token. You can also type the path.
3. Token Placement in Request: in Place Token In, pick Header or Query Parameter and the name, such as Authorization. In Token Prefix, enter the prefix if the API asks for one, such as Bearer (with the trailing space).

Create the cube

After you save the connection, the wizard stays on the same screen with the endpoint fields.

The cube opens on the API Endpoint tab. Click Send to make the call and see the response. After the first response, the Field Mapping tab becomes available to review the fields.

Pagination

Next to the URL, Hubviz shows what the first call looks like, such as ?page=1&per_page=100.

Option	When to use it	Fields
No pagination	The API returns everything at once	None. Default.
Offset and Limit	The API takes a start position and a count	Offset Param Name (e.g. offset), Limit Param Name (e.g. limit), Initial Offset (usually 0), Records per page.
Page Number	The API takes a page number	Param Name (e.g. page), Initial Page (usually 1), Page Size Param Name (e.g. per_page), Page Size.
Date range	The API fetches by date ranges	Start date parameter, End date parameter, Start date, End date (blank = today), Pagination period (Month or Year, default Year) and Date format (default yyyy-MM-dd).
Link in Response Body	The response has the next page link in the JSON	Next Link Path and Previous Link Path.
Link in Response Header	The response has the next page link in the Link header	Next Link Path, Rel (e.g. next) and Previous Link Path.
Cursor	The response has a cursor to request the next page	Cursor Param Name (e.g. after), Initial Cursor (optional) and Next Cursor Path.

Pagination Location sets where the pagination parameters go: Param (in the URL, default), Header or Body. Body is only available for POST calls. Accepted date formats are yyyy-MM-dd, dd/MM/yyyy, MM/dd/yyyy, yyyyMMdd and yyyy-MM.

Dates that update by themselves

In the URL and in the body, use variables that Hubviz replaces at call time. See the full list in the Runtime variables icon next to the URL.

Variable	Becomes
{{TODAY}}	Today’s date, as yyyy-MM-dd
{{YESTERDAY}}	Yesterday’s date
{{START_OF_MONTH}} and {{END_OF_MONTH}}	The first and last day of the current month
{{START_OF_YEAR}} and {{END_OF_YEAR}}	The first and last day of the current year
{{TODAY|dd/MM/yyyy}}	Today’s date in the format you choose

Example: /v2/opportunities?from={{START_OF_MONTH}}&to={{TODAY}} always fetches the current month’s opportunities.

Example: Aurora’s CRM opportunities

Aurora’s (fictional) CRM has this API:

• Base URL: https://api.aurora-crm.com
• Authentication: key in the X-API-Key header
• Endpoint: GET /v2/opportunities?page=1&per_page=100, with at most 60 calls per minute

The response looks like this:

{
  "data": [
    { "id": 981, "data": "2026-03-04", "unidade": "Retail", "valor": 18500.0, "etapa": "won" },
    { "id": 982, "data": "2026-03-05", "unidade": "Industry", "valor": 42000.0, "etapa": "proposal" }
  ],
  "page": 1,
  "total_pages": 7
}

Where	Field	Value
Connection	Base URL	https://api.aurora-crm.com (with Save and Save base only)
Connection	Authentication Type	API Key, Header, X-API-Key
Connection	Requests Per Minute	60
Cube	Endpoint URL	/v2/opportunities
Cube	Pagination	Page Number: page, 1, per_page, 100
Cube	Data Extraction Path	data

Each item of data becomes a cube row, with the fields id, data, unidade, valor and etapa.

Common errors

Situation	What to do
Please fill in all fields before submitting the form.	When saving the connection: the name, base URL, method or authentication type is missing.
The authentication test fails	Hubviz shows the error the API returned. Check the credential, the placement and the header name.
The call works but the cube has no rows	The Data Extraction Path does not point to the list. Look at the response and use the path up to the [ bracket.
The API returns error 429 (too many requests)	Set or lower Requests Per Minute.
Only the first page arrives	Pagination is set to No pagination, or the parameter names do not match the API documentation.

Good to know

• For the cube to refresh by itself, see Automatic refresh.
• An API that only exists on the internal network refreshes through the schedule on this computer, not through the cloud.