Custom API Connector Setup Guide

This guide explains how to set up the Custom API connector in Strand to sync account data 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, and
• run manual or periodic syncs.

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.

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.

Limits

• Max records per sync: 10,000 records.
• Max pages: 1,000 (pagination safety limit).
• Max flatten depth: 3 levels (for nested objects).
• Timeout: 1,000–300,000 ms.

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).

Troubleshooting

• 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.