Custom SaaS Connector: When and How to Build

Off-the-shelf integration platforms cover the popular apps, but many businesses depend on software they do not support well: an industry-specific platform, a regional accounting system, an internal tool or a SaaS product whose connector only handles a fraction of its API. A custom SaaS connector is a small piece of software built to move data between such a system and the rest of your stack, reliably and on your terms. This guide explains when a custom SaaS connector makes sense, what a well-built one contains, how to handle authentication, pagination, rate limits and errors, and how to keep it maintainable, with a worked example.

When to build a custom SaaS connector

A custom connector is worth considering when:

• No pre-built connector exists for the application, or the existing one lacks the objects or fields you need
• You need behaviour an integration platform cannot express well, such as complex matching or multi-step transactions
• Volumes make per-task pricing expensive
• You need control over where data flows and how credentials are stored
• The integration is core to your operations and deserves proper testing and monitoring

If a reliable pre-built connector covers your needs, use it. Building is justified by a real gap, not by preference.

What a good connector contains

ComponentResponsibilityAuthenticationObtain, store and refresh credentials securelyAPI clientMake requests, handle pagination, respect rate limitsData mappingTranslate between the SaaS app's objects and your systems' objectsSync logicDecide what to fetch or send, track progress, handle conflictsError handlingRetry temporary failures, record permanent onesLogging and monitoringRecord what happened and alert when it goes wrongConfigurationField mappings, schedules and endpoints outside the code

Not every connector needs every component in elaborate form, but each should exist in some shape. Separating these responsibilities keeps the connector understandable and makes changes, such as a new field or an API version upgrade, local rather than sweeping.

Authentication

Most SaaS APIs use API keys or OAuth 2.0. With OAuth, defined in RFC 6749, the connector holds a refresh token and exchanges it for short-lived access tokens. Store secrets in a secrets manager or encrypted configuration, never in code. Refresh access tokens before they expire or on an authorisation error, and make sure only one process refreshes at a time if the provider invalidates old tokens. Request only the scopes the connector needs.

Pagination, rate limits and incremental sync

• Pagination: APIs return large result sets in pages using page numbers, offsets or cursors. Follow the provider's method and stop when no further pages are returned.
• Rate limits: read the provider's documented limits and any rate-limit headers. Throttle requests and back off when told to slow down.
• Incremental sync: fetch only records changed since the last successful run, using a modified-time filter or change feed if the API offers one. Store the checkpoint only after the batch is safely processed.
• Webhooks: where the SaaS app sends events, combine them with periodic incremental syncs to catch anything missed.

Data mapping and conflicts

Document how each object and field maps between systems, including transformations such as status codes, date formats and currency handling. Decide which system owns each field so conflicts have a clear resolution. Use stable identifiers to match records, and store the other system's ID on each record to make updates and troubleshooting straightforward. Keep the mapping in configuration where practical, so adding a field does not require a code change.

Worked example: a connector for a field service platform

Suppose a company uses a niche field service platform for engineer scheduling, with no reliable connector to its CRM. It needs completed jobs to appear on the customer's CRM record each hour. The connector's core client handles authentication, pagination and rate limits. This is a simplified, untested illustration; the endpoint paths, parameters and response fields are placeholders, because each provider's API differs:

import time, requests

class FieldServiceClient:
    def __init__(self, base_url, token_provider):
        self.base_url = base_url
        self.tokens = token_provider

    def _get(self, path, params):
        for attempt in range(5):
            headers = {"Authorization": f"Bearer {self.tokens.access_token()}"}
            resp = requests.get(self.base_url + path, params=params,
                                headers=headers, timeout=30)
            if resp.status_code == 401:
                self.tokens.refresh()
                continue
            if resp.status_code == 429:
                time.sleep(int(resp.headers.get("Retry-After", pow(2, attempt))))
                continue
            resp.raise_for_status()
            return resp.json()
        raise RuntimeError(f"Gave up on {path}")

    def completed_jobs_since(self, since_iso):
        cursor = None
        while True:
            params = {"status": "completed", "updated_after": since_iso}
            if cursor:
                params["cursor"] = cursor
            page = self._get("/jobs", params)
            yield from page["items"]
            cursor = page.get("next_cursor")
            if not cursor:
                break

The sync job reads the last checkpoint, fetches completed jobs since then, maps each job to a CRM activity using the customer's stored CRM ID, and upserts activities keyed on the field service job ID so reruns create no duplicates. It saves the new checkpoint only after all activities are written. Jobs whose customer has no CRM ID are logged to an exceptions report for the operations team rather than silently skipped.

Security and data handling

A connector holds credentials that can read and often change data in a business system, so treat it as production software. Run it in an environment with restricted access, keep its dependencies patched and log actions without writing secrets or unnecessary personal data to the logs. Move only the fields the receiving system actually needs, which reduces both risk and the work of keeping mappings current. If the connector handles personal data, record what it moves and why, so it can be included in your data protection records. When someone with access to the credentials leaves, rotate them. Finally, agree with the business what should happen when the connector is unavailable for a day: whether data can simply catch up later, or whether staff need a manual fallback.

Testing and maintenance

• Test against a sandbox or test account where the provider offers one
• Write tests for mapping logic using recorded sample responses
• Monitor run success, record counts and error rates, with alerts on failure
• Track the provider's API changelog and deprecation notices
• Document the connector: purpose, mappings, configuration, credentials owner and runbook

A connector is a long-lived component. Budget for maintenance when the provider changes its API, and assign an owner.

Common mistakes

• Hard-coding credentials or field mappings
• Fetching everything on every run instead of syncing incrementally
• Ignoring rate limits until the provider blocks the connector
• Saving checkpoints before data is safely written
• No idempotency, so reruns duplicate records
• No owner or monitoring after go-live

If you are weighing a custom connector against an integration platform, our comparison of Zapier and custom API integration sets out the trade-offs. For an example of integrating a specific business application through its API, see our guide to Odoo API integration.

Frequently Asked Questions

What is a custom SaaS connector?

Software built to move data between a SaaS application and your other systems when no suitable pre-built connector exists or the existing one falls short.

When should we build rather than use an integration platform?

When no reliable connector exists, the logic is too complex for the platform, volumes make task pricing expensive, or the integration is core enough to need full control and testing.

How do custom connectors handle API rate limits?

By throttling requests to stay within documented limits, reading rate-limit headers and backing off with increasing delays when the provider signals too many requests.

How much maintenance does a custom connector need?

Ongoing monitoring plus updates when the provider changes or deprecates API features, so assign an owner and budget time for it.

Get the connector you need

We build custom SaaS connectors with secure authentication, incremental sync, monitoring and documentation. See our CRM and API integration services, or talk to us about your connector.

About the Author

Manav Sharma is the founder of Insyrge and a CRM solutions architect. He works across Zoho, Salesforce, HubSpot, Odoo and more, designing the CRM setups, integrations and automations that keep sales and operations teams working from the same data.