Custom API Connector Setup Guide

This guide explains how to set up the Custom API connector in Strand to sync account data, contacts, 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,
• sync contacts (users) from a separate API endpoint and link them to accounts,
• auto-discover fields from API responses,
• 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: Contacts Endpoint (optional)

Configure a separate REST endpoint to sync contacts (users) and link them to existing accounts. Contacts appear on account pages and can be used for activity tracking.

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

1) Enable contacts endpoint

Toggle on to activate contact syncing for this connector.

2) Contacts API URL

Enter the full URL of the endpoint that returns contact/user data. This is typically a different endpoint from your account sync (for example /api/users instead of /api/accounts).

3) Method and authentication

Choose GET or POST. The contacts 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 contacts array in the response. For example, if your API returns:

{
	"data": {
		"users": [{ "email": "jane@acme.com", "name": "Jane Doe", "company_domain": "acme.com" }]
	}
}

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

5) Pagination (optional)

Enable pagination if the contacts endpoint returns data across multiple pages. The same three pagination types are supported as for account sync:

• Page-based: ?page=1&limit=100
• Offset-based: ?offset=0&limit=100
• Cursor-based: uses a next cursor from the response

Configure page size, max pages, and (for cursor-based) the path to the next cursor value in the response.

6) Incremental sync (optional)

If the contacts API supports filtering by last-modified date, configure a timestamp query parameter (for example updated_since). Strand passes the last successful contact sync timestamp on subsequent runs, so only changed contacts are fetched. Leave blank for full sync every time.

7) Test & Discover Fields

Click Test & Discover Fields to validate the endpoint and auto-discover available fields from the response. This step is required before configuring field mappings.

8) Save Endpoint

Click Save Endpoint to store the contacts endpoint configuration.

9) Contact sync settings

After fields are discovered, the contact sync settings panel appears.

Enable periodic contact sync: turn on for automatic scheduled syncing.

Account matching: choose how contacts are linked to existing accounts:

• Domain only: match by companyDomain.
• External ID only: match by externalCustomerId.

This should align with the matching strategy used in Step 2 (Account Sync).

10) Field mappings

Map API fields to contact fields. Two fields are required:

Two fields are optional:

All fields support dot notation for nested objects (for example user.profile.email).

11) Sync now

Click Sync Now to trigger a manual contact sync. After a run, check the sync status panel for rows processed, contacts created/updated/skipped, and recent errors.

12) Save

Click Save to store the contact sync field mappings and settings.

How contact sync works

• Contacts are matched to existing accounts using the configured account match field (domain or external ID).
• Within each account, contacts are matched by email address — if a contact with the same email already exists, it is updated rather than duplicated.
• Contacts that cannot be matched to an existing account are skipped. Make sure accounts are synced first (Step 2) before running contact sync.
• Incremental sync is supported: configure a timestamp query parameter on the contacts endpoint and Strand will pass the last successful sync timestamp, so only recently changed contacts are fetched.
• Pagination is supported: if the contacts endpoint paginates, configure the pagination type and parameters so Strand fetches all pages automatically.

Step 4: 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.

Contacts

• All contacts skipped: contacts are only linked to existing accounts. Make sure account sync has run first and that the account match field (domain or external ID) in the contact data matches what Strand has stored.
• Test fails: verify the contacts API URL, response data path, and that the endpoint returns an array of objects.
• Duplicate contacts: contacts are matched by email within each account. If the same email appears with different account identifiers, it creates separate contacts under each account.
• Missing field mappings: run Test & Discover Fields first to populate the available fields list, then map at least email and the account match field.

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.