Custom API Connector Setup Guide

This guide explains how to set up the Custom API connector in Strand to sync account data and pull usage events from any REST API.

What this connector does

The Custom API connector lets Strand:

• pull account data from any REST API endpoint,
• auto-discover fields from the API response,
• map API fields to Strand fields,
• handle pagination, authentication, and incremental sync,
• run manual or periodic syncs, and
• show per-account usage events in the Events tab on account pages.

This is useful when your account data lives in an internal system, a SaaS tool without a native Strand connector, or any service that exposes a REST API.

Before you start

Make sure you have:

• Admin or Owner access in your organization (required to configure and sync).
• A REST API endpoint that returns JSON data.
• Authentication credentials for the API (if required).

Step 1: Configure API Connection

Open: Settings -> Connectors -> Custom API Sync

1) API endpoint

Enter the full URL of the API endpoint that returns your account data.

• Must be an http:// or https:// URL.
• Private/internal network addresses (localhost, 10.x, 172.16-31.x, 192.168.x) are blocked for security.

Choose the HTTP method:

• GET (default) for standard REST endpoints.
• POST if your API requires a request body.

2) Authentication

Choose an authentication type:

• Bearer Token: sends Authorization: Bearer <token> header (most common).
• API Key: sends the token in a custom header (default: X-API-Key, configurable).
• None: no authentication.

3) Response data path

Tell Strand where the account records are in the JSON response using dot notation.

For example, if your API returns:

{
	"data": {
		"accounts": [{ "name": "Acme Corp", "domain": "acme.com" }]
	}
}

Set the response data path to data.accounts.

4) Custom headers (optional)

Add any extra HTTP headers your API requires (for example X-Tenant-Id, Accept-Version).

5) Request body (optional, POST only)

If using POST, provide a JSON request body.

6) Timeout (optional)

Set a custom request timeout in milliseconds (default: 30,000 ms, max: 300,000 ms).

7) Test connection

Click Test Connection to:

• Validate the API endpoint is reachable.
• Fetch a sample of data.
• Auto-discover available fields from the response.

This step is required before you can configure field mappings.

8) Save configuration

Click Save to store the API configuration. Authentication tokens are encrypted at rest.

Step 2: Account Sync Settings

After saving the API configuration and testing the connection, configure how accounts are synced.

1) Periodic sync

• Turn on for automatic scheduled syncing (recommended for production).
• Turn off if you only want manual sync runs.

2) Create-missing behavior

Choose whether Strand should create new accounts when no match is found.

• On: create + update.
• Off: update matched accounts only.

3) Account matching

Choose how synced records are matched to existing Strand accounts:

• Domain: match by company domain.
• External ID: match by external customer ID.
• Domain + External ID: try external ID first, fall back to domain.

4) Field mappings

Map API fields to Strand fields. After Test Connection discovers available fields, you’ll see a mapping table:

• Left side: API source fields (auto-discovered).
• Right side: Strand target field names.

Use camelCase Strand target fields, for example:

• companyName
• companyDomain
• externalCustomerId
• accountOwnerEmail

Auto-mapping suggestions are provided based on fuzzy field name matching.

Required mappings depend on account matching mode:

• Domain requires companyDomain.
• External ID requires externalCustomerId.
• Domain + External ID requires at least one of the above.

5) Sync now

Click Sync Now to trigger a manual sync immediately.

After a run, check the sync status panel for:

• last completed time,
• rows processed / accounts created / updated / skipped,
• recent errors (if any).

6) Save

Click Save to store your sync settings.

Step 3: Events Endpoint (optional)

Configure a separate REST endpoint to pull per-account usage events. Once set up, events appear in the Events tab on each account page alongside events from BigQuery, Snowflake, and PostHog.

Open: Settings -> Connectors -> Custom API Sync -> Events

1) Enable events endpoint

Toggle on to activate event querying for this connector.

2) Events API URL

Enter the full URL of the endpoint that returns events. This can be the same base API as your account sync or a different one.

3) Method and authentication

Choose GET or POST. The events endpoint uses the same authentication token as the API configuration in Step 1 — no second credential is needed.

If you need a different auth header name (API key mode), set it here independently.

4) Response data path

Dot-notation path to the events array in the response. For example, if your API returns:

{
	"data": {
		"events": [{ "timestamp": "2026-04-01T10:00:00Z", "event": "page_view" }]
	}
}

Set the response data path to data.events. Leave blank if the response root is the array.

5) Account match by

Choose how Strand identifies which account each event belongs to:

• Company domain: match events to accounts using a domain field (e.g. acme.com).
• External customer ID: match events to accounts using an external ID field.

This should align with the matching strategy used in Step 2.

6) Field mappings

Map fields from each event record to the standard event structure. Three fields are required:

Two fields are optional:

If Properties is left blank, all remaining fields on the event record are used as properties automatically.

All paths support dot notation (e.g. actor.email).

7) Time range parameters (optional)

If your API accepts date range filters, configure the query parameter names Strand should use:

• Start time param: query parameter for the range start (e.g. from, start_date).
• End time param: query parameter for the range end (e.g. to, end_date).
• Lookback days: how many days back to fetch events (default: 90, max: 365).

Strand passes ISO 8601 timestamps for these parameters on every query.

8) Save

Click Save to store the events configuration.

How events are fetched

When an account page loads the Events tab, Strand calls your configured endpoint with the time range parameters (if set) and filters the response client-side by accountIdentifier. Events are sorted newest first and capped at the page limit.

Note: Because filtering happens after fetching, if your API returns events for all accounts in a single response, Strand reads up to 5,000 records per request. For best performance, configure your API to accept an account identifier as a query parameter and filter server-side.

Advanced Settings

Pagination

Enable pagination if your API returns data across multiple pages. Three pagination types are supported:

• Page-based: uses a page number parameter (for example ?page=1&limit=100).
  • Configure: page parameter name, page size parameter name, page size.
• Offset-based: uses an offset parameter (for example ?offset=0&limit=100).
  • Configure: offset parameter name, page size parameter name, page size.
• Cursor-based: uses a cursor from the previous response (for example ?cursor=abc123).
  • Configure: cursor parameter name, path to next cursor in response JSON, page size.

Additional pagination options:

• Page size: number of records per page (default: 100).
• Max pages: safety limit on total pages fetched (default: 100, max: 1,000).
• Total count path: optional path to total record count in response (for progress tracking).

Incremental sync

If your API supports filtering by last-modified date, configure the timestamp parameter:

• Set the query parameter name (for example updated_since).
• Strand will automatically pass the last successful sync timestamp on subsequent runs.
• If no previous sync exists, incremental sync is skipped and a full sync runs.
• If a sync fails, the timestamp is not advanced — the next run retries the same window.

Nested object handling

API responses with nested objects are automatically flattened up to 3 levels deep using dot notation.

For example, { "address": { "city": "Oslo" } } becomes the field address.city in field discovery.

Validation rules you may hit

• If Domain matching is selected, companyDomain mapping is required.
• If External ID matching is selected, externalCustomerId mapping is required.
• If Domain + External ID is selected, at least one of those two mappings is required.
• API URL must be a valid HTTP/HTTPS endpoint (no private network addresses).

Limits

Troubleshooting

Account sync

• Test Connection fails: verify the API URL, authentication credentials, and response data path.
• No fields discovered: check that the response data path points to an array of objects.
• Save fails with mapping error: check account matching mode and required mapping fields.
• Too many rows skipped: enable Create new accounts when no match is found.
• Sync times out: increase timeout in advanced settings, or reduce page size.
• Rate limited (429 errors): Strand automatically retries with backoff using the Retry-After header.
• Sync button not working: confirm your role is Admin/Owner.

Events

• No events showing on account pages: confirm events endpoint is enabled and saved, and that the event time, event name, and account ID field paths are correct.
• Events show for wrong accounts / no events for a specific account: check that the account ID field path resolves to the same value Strand uses for matching (domain or external ID). Matching is case-insensitive.
• Events endpoint returns an error: verify the URL, auth type, and response data path. The endpoint must return HTTP 200 and an array at the configured path.
• Events are stale or missing recent data: check your lookback days setting, and ensure start/end time params are correctly named to match your API’s expected query parameters.
• Performance is slow on the Events tab: configure your API to filter by account server-side and pass the account identifier as a query parameter, rather than returning all accounts’ events in one payload.