Understanding the API Integration Framework

This guide explains how Yurbi's API integration framework works, what every field and parameter type is for, and a recommended workflow for setting up an integration with any REST API. It's written for someone who's comfortable reading API documentation but new to Yurbi's specific way of modeling integrations.

If you're looking for a step-by-step walkthrough of a specific integration (Microsoft Excel, Google Sheets), see the Related Articles at the bottom. This document is the underlying reference those guides assume.

What This Framework Does

The API integration framework lets you pull data from any REST API and surface it inside Yurbi as a regular table. Once configured:

• Yurbi fetches data from the vendor's API on demand or on a schedule

• The fetched data lands in Yurbi tables you can join, query, and report on like any other data source

• Authentication and pagination are handled automatically once you've configured them

Common uses include pulling customer/ticket data from a SaaS tool (CRM, help desk), reading spreadsheets from cloud storage (Google Sheets, Excel on SharePoint), syncing data from accounting tools, or mirroring data from any internal or third-party API your team relies on.

The result is that data living outside your databases — in SaaS tools your team uses — becomes reportable in the same workflow as your operational data.

Before You Open Yurbi: Test in Postman First

The single most useful thing you can do before configuring an API integration in Yurbi is to make the API call succeed in a dedicated API client first — Postman, NativeRest, Insomnia, or any equivalent. Don't try to debug Yurbi configuration and vendor API quirks at the same time.

The reasoning is practical. Every vendor's REST API has its own conventions, and the docs are often slightly out of sync with the actual behavior:

• The auth header might want a literal prefix you didn't notice (Bearer vs Token )

• A query parameter might be case-sensitive (?Status=open vs ?status=open)

• The response might be wrapped in a JSON envelope the docs don't show

• Pagination might behave differently than documented when you reach the last page

Until you can reliably make the call return data outside Yurbi, you don't know what the request actually needs to look like — and you'll waste time blaming Yurbi for the vendor's quirks.

What to capture from your Postman test

For each API endpoint you want to bring into Yurbi, write down:

1. The full URL including query string parameters

2. HTTP method (almost always GET for reading data)

3. Auth method — exactly what header(s) you sent and what they contained

4. Other headers the vendor required (Accept, version headers, tenant IDs)

5. The full response JSON — specifically, where in the JSON the actual data array lives

6. Pagination behavior — what query params control it, what tells you there are more pages

7. Anything else weird — rate limit headers, undocumented fields, etc.

With those notes in hand, configuring Yurbi becomes a translation exercise rather than a debugging exercise.

The Three Connection Types

When you create a new API integration via Settings → Integrations → Create App → APIs, the first decision is the Api Connection type. Pick based on how the vendor's API authenticates:

Important: oAuth 2.0 and Manual expose the exact same form and behave identically. There's no extra automation, no special handling, no difference under the hood — the two labels exist purely to make your configuration more readable. Pick oAuth 2.0 when the vendor literally uses OAuth 2.0; pick Manual for any other multi-step URL-exchange flow.

How vendor docs map to your choice

Read the vendor's authentication section. What you see there → which connection type to pick:

• "Pass ?api_key=YOUR_KEY in the URL" → HttpBasicAuthenticator (you can put the key in an auth header param), or Manual if you'd rather hardcode it in the URL

• "Send Authorization: Basic <base64(username:password)>" → HttpBasicAuthenticator

• "Send Authorization: Bearer <static-token>" or "X-API-Key: <key>" → HttpBasicAuthenticator

• "Implement OAuth 2.0 authorization code flow with the following endpoints..." → oAuth 2.0

• Anything stranger (e.g., custom signed requests, HMAC, multi-step token exchanges that aren't standard OAuth) → Manual or a feature request

Anatomy of an API Integration

Every API integration in Yurbi has the same structure, regardless of connection type:

1. The API Connection itself — the wrapper. Has a name, description, connection type, and active status.

2. URL flow forms (for oAuth 2.0 and Manual connection types — functionally identical, see above) — three URL configuration sections for the authorization, token exchange, and refresh URLs.

3. Endpoints — one per API URL you want to call. Each endpoint becomes one (or more) tables in Yurbi.

4. Endpoint Parameters — per-endpoint settings that control how Yurbi builds each request: auth headers, custom headers, pagination, dynamic value substitution.

5. Reusable Dynamic Parameters (optional, at the connection level) — named parameter sources that let one endpoint reference data from another endpoint or from a saved Yurbi report.

Each section has a corresponding part of the Register New API form. The form shows or hides sections based on the connection type you picked.

Endpoints — One Per Resource You Want as a Table

Click Add Endpoint under the Api Endpoints section. You'll see:

Below the URL, you add parameters that customize how the request is built — auth headers, pagination, custom headers, and so on. The parameter system is covered in detail below.

Response By — Where the Data Lives in the JSON

This single field is responsible for more "endpoint fetched but the table is empty" frustration than any other. The fix is almost always understanding the response shape.

REST APIs return JSON in one of three common shapes. Look at the response you captured in Postman to identify which one applies.

Shape A — Data at the root level (a bare array):

[
  {"id": 1, "name": "Alpha"},
  {"id": 2, "name": "Beta"}
]

→ Set Response By to blank (leave the field empty).

Shape B — Data wrapped under a key:

{
  "data": [
    {"id": 1, "name": "Alpha"},
    {"id": 2, "name": "Beta"}
  ],
  "meta": {"total": 2, "page": 1}
}

→ Set Response By to data.

Shape C — Vendor-specific key name:

{
  "listConversations": [
    {"id": 1001, "subject": "..."},
    {"id": 1002, "subject": "..."}
  ]
}

→ Set Response By to listConversations.

How to figure out the right value

Open your Postman test, look at the response body. The JSON key whose value is the array of records is your Response By value. If the array is at the top level (no key wrapping it), leave the field blank.

Single-object responses (a detail endpoint that returns one record, not an array) often work with Response By blank — Yurbi treats the entire object as a one-row response. But if the single object is wrapped (e.g., {"ticket": {...}}), set Response By to that wrapper key.

The Parameter Type Catalog

Every parameter row on an endpoint has a Param Type dropdown that tells Yurbi how to use that parameter when building the request. Here's every option, what it means, and when you'd use it.

Is Auth Header

Puts the parameter into the HTTP Authorization (or other auth) header. The behavior depends on the Authentication column setting (covered later):

Pattern 1 — OAuth bearer token (used after OAuth authentication completes):

• Name: Authorization

• Param Type: Is Auth Header

• Value: access_token (Yurbi substitutes the stored token automatically)

• Authentication: Authentication

Pattern 2 — HTTP Basic Auth (vendor wants username/password):

• Name: your username (e.g., david@yourcompany.com)

• Param Type: Is Auth Header

• Value: your password or API key

• Authentication: HttpBasicAuthenticator (Yurbi base64-encodes and sends as Authorization: Basic <encoded>)

Pattern 3 — Custom auth header (vendor wants something like X-API-Key):

• Name: X-API-Key

• Param Type: Is Auth Header

• Value: your key

• Authentication: Authentication

Is Header

A non-auth HTTP header. Examples:

• Accept header: Name = Accept, Value = application/json

• Tenant ID: Name = X-Tenant-Id, Value = your-tenant-id

• API version pin: Name = Api-Version, Value = 2024-01-01

The vendor's docs will tell you when these are required.

Is Page

Pagination — for APIs that use page numbers, like ?page=1, ?page=2, ....

• Name: the query parameter name the API expects (commonly page)

• Param Type: Is Page

• Value: typically also page

When this param is present, Yurbi automatically calls the endpoint multiple times — incrementing the page counter each call — until pagination tells it to stop (see More Check). All pages get appended into the same table.

Is Offset

Pagination — for APIs that use record offsets instead of page numbers (e.g., ?offset=0, ?offset=50, ?offset=100).

• Name: the query parameter name (commonly offset, skip, or start)

• Param Type: Is Offset

Works just like Is Page but increments by the per-page count rather than by 1.

Records Per Page

Tells the API how many records to return per call (e.g., ?limit=50, ?per_page=100, ?pageSize=200).

• Name: the query parameter name (commonly limit, per_page, pageSize, count)

• Param Type: Records Per Page

Pair with either Is Page or Is Offset. Most vendor APIs cap this at 100 or 200 — check the docs.

More Check

Tells Yurbi how to detect when there are no more pages to fetch.

Most APIs include some kind of signal in the response that indicates whether more data is available. Common patterns:

• A total count: {"meta": {"total_count": 487}} — Yurbi compares total to rows-fetched-so-far

• A boolean: {"has_more": true} — Yurbi stops when it sees false

• A next-page indicator: {"next_page": null} — Yurbi stops when null

• Name: the response field name that signals more results — e.g., total_count, has_more, nextPageUrl

Without More Check, Yurbi can't reliably tell when to stop paginating. Configure it.

From Dynamic Param

References a reusable dynamic parameter you've defined separately at the API connection level. Used for parent → child fetch patterns where the value of one column from a previous endpoint's results is substituted into this endpoint's URL.

• Name: a label matching the URL placeholder (e.g., customer_id)

• Param Type: From Dynamic Param

• Value: dropdown — select from your saved dynamic parameters

The URL contains a placeholder like https://api.vendor.com/customers/{customer_id}/invoices. At fetch time, Yurbi runs the endpoint once per row from the dynamic param's source, substituting each value into the URL.

See the Reusable Dynamic Parameters section below for the full setup.

The Authentication Column

Each parameter row also has an Authentication dropdown with two values:

For the vast majority of parameter rows, Authentication is the right choice. Switch to HttpBasicAuthenticator only when you're configuring an HTTP Basic Auth credential.

The "Is Query Param" Checkbox

Separate from Param Type, every parameter row has an Is Query Param checkbox. It controls whether the parameter is appended to the URL as a query string parameter (?name=value) or used elsewhere (in a header, in a placeholder substitution, etc.).

For most cases the behavior is implicit in the Param Type:

• Is Auth Header and Is Header — value goes in the header, checkbox doesn't apply

• Is Page, Is Offset, Records Per Page — value goes in the query string regardless of the checkbox (Yurbi handles it)

• From Dynamic Param — value substitutes into a URL placeholder; checkbox state generally doesn't change this

You'll mostly leave this unchecked unless you're explicitly adding a static query string parameter (uncommon — those are usually just baked into the URL itself).

Reusable Dynamic Parameters

Dynamic parameters enable two important patterns:

• Parent → child fetching: a list endpoint returns IDs; a detail endpoint runs once per ID

• Yurbi-data-driven fetching: a Yurbi report (e.g., "active customer IDs from our CRM database") drives which records to fetch from a separate API

This is a two-step configuration: first you define the named parameter at the connection level, then any endpoint can reference it.

Step 1: Define the dynamic parameter

In the API connection form, under Api Endpoints Parameters, click Add Parameters. The form asks for:

Select Parameter Type — pick one of:

• From Table — source the values from a column in another endpoint's resulting table (in this same API connection):

  • Select Table — pick the endpoint's data table

  • Select Column — pick the column to iterate

  • Enter Parameter Value — the name of this dynamic param (e.g., customer_id)

• From Document — source the values from a saved Yurbi report (a database query result):

  • Select Document — pick the saved report

  • Enter Parameter Value — the name of this dynamic param

The "Enter Parameter Value" name is what shows up in the dropdown when other endpoints reference it.

Step 2: Reference it from an endpoint

In an endpoint's URL, use a placeholder syntax matching the parameter name:

https://api.vendor.com/customers/{customer_id}/invoices

Add a parameter row on the endpoint:

• Name: customer_id (must match the placeholder in the URL)

• Param Type: From Dynamic Param

• Value: pick customer_id from the dropdown (your saved dynamic param)

How the iteration works

When this endpoint is fetched:

1. Yurbi looks at the source (the table or document the dynamic param points to)

2. For each row in that source, Yurbi makes one API call, substituting the column value into the URL placeholder

3. All results are appended into a single table for this endpoint

4. An additional column called id_yurbi is added automatically — it contains the source row's identifier, letting you join parent and child tables in Architect

One call per source row. If your parent endpoint returns 500 conversations, the child endpoint will make 500 API calls — sequentially. For large parent sets, plan your schedule cadence around the vendor's rate limits.

Joining parent and child in Architect

After both endpoints have fetched, you'll have two tables — for example:

• api_X_Y_listConversations_listdatatable (the parent list) with a conversation_id column

• api_X_Z_listdatatable (the per-conversation details) with an id_yurbi column

In Architect, bring both tables into your app and join parent.conversation_id = child.id_yurbi. You'll then have detail data accessible per parent record for reporting.

OAuth 2.0 (and Manual) — The Three URL Forms

If you picked oAuth 2.0 or Manual as your connection type, the form shows three additional URL sections above the endpoints. For a standard OAuth 2.0 integration, the three sections correspond to the steps of the authorization code flow:

After configuring all three forms, click Authenticate in the API Authorization List section. A popup walks the user through the vendor's login, Yurbi receives the tokens, and stores them. Endpoints can then use the stored access_token via an Is Auth Header parameter.

For complete OAuth setup walkthroughs, see the Microsoft Excel OAuth2 and Google Sheets OAuth2 guides.

A note on the OAuth callback URL

Yurbi serves the OAuth callback at /apiconnection.html on whatever domain your Yurbi instance is reachable at. For self-hosted Yurbi deployments — which is most of them — the callback URL looks like https://yurbi.yourcompany.com/apiconnection.html.

Critically, the callback URL must be reachable from the user's browser when they click Authenticate. For a Yurbi instance behind a firewall, this typically means exposing at minimum the /apiconnection.html endpoint publicly via your reverse proxy, with a valid TLS certificate. The vendor doesn't directly call this URL — the user's browser is redirected to it after sign-in completes — but it needs to be resolvable wherever that browser is running.

Deconstructing Vendor API Documentation — A Checklist

When you sit down with a new vendor's API docs, work through these sections in order. The answer to each maps to specific Yurbi configuration.

1. Authentication

Where do you find this? Usually a top-level section called "Authentication," "Auth," "Getting Started," or "API Keys."

What you're looking for:

• Which scheme? API key (in URL or header), HTTP Basic Auth, OAuth 2.0, custom?

• How is it provisioned? Self-service in their dashboard? Admin only? Per-user or per-application?

• How is it sent? Header name? URL parameter name?

Map your answer to a connection type using the table earlier in this guide.

2. Base URL and Resource Paths

What's the API root (e.g., https://api.vendor.com/v3)? What endpoints (paths) do you need? Most APIs follow a /resource and /resource/{id} pattern.

Pick the endpoints you actually need. One endpoint per data table you want in Yurbi. Don't add every endpoint the vendor offers; just the ones whose data you need to report on.

3. Response Format

Pull up a sample response in Postman (or in the vendor's API docs if they show example responses).

• Where is the data array? Top-level array → Response By blank. Nested under a key → Response By = that key.

• What does each record look like? Just for awareness — Yurbi auto-detects columns from the JSON.

4. Pagination

Vendors use one of three styles. Figure out which:

• Page-based: docs say "pass ?page=N and optionally ?per_page=M" → Is Page + (optionally) Records Per Page

• Offset-based: docs say "pass ?offset=N and ?limit=M" → Is Offset + Records Per Page

• Cursor-based: docs say "use the next_cursor field from the response in the next request" → trickier. Some vendors' cursor pagination can be made to work with More Check pointing at a has_more field, but cursor-only pagination without a numeric counter doesn't map cleanly. Worth testing in Postman before committing to a Yurbi setup.

Also figure out the stopping signal — is there a total_count, has_more, next_page field? Whatever it is, that's your More Check field name.

5. Required Headers

Many APIs require headers beyond auth: Accept: application/json, version pins, tenant identifiers. Each goes in as an Is Header parameter.

6. Rate Limits

Note the vendor's rate limit. Common patterns:

• Per-minute: e.g., 60 requests/minute

• Per-hour: e.g., 1000 requests/hour

• Per-day: e.g., 100,000 requests/day

If you're using the parent → child dynamic param pattern with large datasets, plan your schedule cadence around these limits. A parent with 1000 children fetched every 15 minutes is 4000+ calls/hour — make sure that fits.

7. Anything Else Unusual

Some APIs have quirks worth noting:

• Eventual consistency (data created via API isn't immediately readable)

• Soft-deleted records that show up in some endpoints but not others

• Different field naming conventions (camelCase vs snake_case in different endpoints)

Postman-test these as you go.

A Worked End-to-End Example

Let's walk through configuring a fictional "AcmeTickets" support-platform API to feel concrete.

Vendor docs say...

Authentication: Send X-Api-Key: <your-key> header on every request. Generate your key from your AcmeTickets admin dashboard.

Base URL: https://api.acmetickets.com/v3

List tickets: GET /tickets. Returns:

{
  "data": [
    {"id": 1001, "subject": "Login broken", "status": "open", "created_at": "2025-01-15"},
    ...
  ],
  "meta": {
    "total_count": 487,
    "page": 1,
    "per_page": 50
  }
}

Pagination: ?page=N&per_page=M (max 100 per_page).

Ticket details: GET /tickets/{ticket_id}. Returns a single ticket object with full comments array nested.

Rate limit: 120 requests/minute.

Step 1 — Test in Postman

In Postman, make a GET https://api.acmetickets.com/v3/tickets request with header X-Api-Key: abc123.... Confirm a successful response and inspect the JSON. Also test GET https://api.acmetickets.com/v3/tickets/1001 and verify the detail shape.

Step 2 — Plan the Yurbi configuration

Step 3 — Build it in Yurbi

Walk through the form in this order:

1. Register the API connection with name, description, type = HttpBasicAuthenticator

2. Add Endpoint 1 (List Tickets) with the URL, Response By = data, and the pagination + auth parameters

3. Click Connect on Endpoint 1 from the Actions menu — verify rows appear in the _listdatatable table

4. Add a dynamic parameter ticket_id sourced from Endpoint 1's table, id column

5. Add Endpoint 2 (Ticket Details) with the placeholder URL, the dynamic param, and the auth header

6. Click Connect on Endpoint 2 — verify the detail rows fetch (one per ticket)

7. In Architect, join the two tables on tickets_list.id = ticket_details.id_yurbi for combined reporting

Step 4 — Schedule and run

Once both endpoints are validated, set a schedule on each. For 487 tickets at 120 requests/minute, even a refresh-every-15-minutes cadence is well within limits.

Common Mistakes and Gotchas

Picking Between the Three Connection Types in Practice

If your vendor uses a static API key sent in a header or HTTP Basic Auth credentials, HttpBasicAuthenticator is the right choice — it gives you the streamlined form, and the per-endpoint auth-header pattern works for any custom header name (X-API-Key, Authorization: Bearer ..., etc.).

For anything that requires the multi-step URL exchange — OAuth 2.0 or otherwise — pick either oAuth 2.0 or Manual. As noted in the connection types table earlier, these two are functionally identical in Yurbi: same form, same fields, same Authenticate button behavior. The choice is purely about labeling:

• Pick oAuth 2.0 when the vendor's docs explicitly say "OAuth 2.0 authorization code flow." The form's section names (Authorization, Token Exchange, Refresh Token) will match the spec terminology.

• Pick Manual for any other multi-step token-exchange auth — custom session tokens, non-standard grant types, multi-step handshakes — where the OAuth 2.0 labeling would be misleading.

In practice, most integrations use either HttpBasicAuthenticator or oAuth 2.0. Manual is uncommon but useful for vendors with non-OAuth multi-step auth flows.

Related Articles

• Microsoft Excel (OneDrive for Business / SharePoint via OAuth2) — a complete OAuth 2.0 walkthrough

• Google Sheets (OAuth2) — another OAuth 2.0 example, with the parent-versus-child decision around Workspace vs personal Gmail

• Google Sheets (Public API) — the simplest HttpBasicAuthenticator / Manual style integration (no auth flow, API key in URL)

• Microsoft Excel (Personal OneDrive) — when API-based access isn't an option, fall back to file imports

For unresolved issues setting up a specific integration, contact your Yurbi administrator or support contact.