Custom API integration is how you connect a system that has no pre-built connector in your integration platform: you call its API directly and map its data into your workflows. Every platform's connector catalogue has gaps, whether it's a niche industry tool, a regional payroll provider, an internal service your developers built, or a brand-new SaaS product. If the system has an API, you can still integrate it.
This guide covers how to plan and build a custom API integration, the parts that usually go wrong (authentication, pagination, rate limits, errors), and how to keep it maintainable. For the basics of how APIs connect systems, see what API integration is.
When you need a custom API integration
- No connector exists for the system in your platform's catalogue.
- The connector doesn't cover what you need, such as a newer endpoint, a custom object, or a field the connector doesn't map.
- The system is internal: your own microservices, data services, or legacy applications wrapped in an API.
- A partner exposes an API specifically for your business relationship.
A connector is a convenience; the API is what actually does the work. A good integration platform lets you call any REST API with the same mapping, error handling, and monitoring you get with native connectors.
What you need before you start
| Item | Why it matters | Where to find it |
|---|---|---|
| API documentation | Endpoints, fields, and behaviour | The vendor's developer portal |
| An OpenAPI (Swagger) file, if available | Lets you import endpoints and data structures instead of typing them | Developer portal or vendor support |
| Credentials | API key, OAuth 2.0 client, or certificate | Admin console of the target system |
| A sandbox environment | Test without touching production data | Ask the vendor; many SaaS tools provide one |
| Rate limits | How fast you can call it | Documentation and response headers |
| Field mapping | Which source fields map to which target fields | Business owners of both systems |
How to build a custom API integration, step by step
- Set up authentication once. Store the API key, OAuth client, or certificate in your platform's secrets store, not in the workflow, and handle token refresh automatically.
- Define the requests. For each operation, set the method (GET, POST, PUT, PATCH, DELETE), the URL with path and query parameters, and any required headers.
- Map the data. Map your source fields to the API's request body, and the response back into your workflow. Handle data types, dates, and enumerations explicitly.
- Handle pagination. List endpoints return results in pages using offsets, page numbers, or cursors. Loop until there are no more pages, or you'll silently miss records.
- Respect rate limits. Back off on 429 responses and batch where the API allows it. See handling API rate limits.
- Handle errors deliberately. Retry temporary failures (timeouts, 429, 5xx); don't retry validation errors (400, 422) without fixing the data first; route failed records somewhere they can be fixed.
- Test in the sandbox, including bad data, expired credentials, and an empty response.
- Monitor in production with the same tracing and alerting as your other integrations.
Common authentication patterns
- API key: a static key in a header. Simple; rotate it regularly and store it securely.
- OAuth 2.0 client credentials: the integration exchanges a client ID and secret for a short-lived token. The usual choice for system-to-system access.
- OAuth 2.0 authorization code: a user grants access once and the integration refreshes the token. Common for SaaS apps acting on a user's behalf.
- Basic auth: username and password, still found on older APIs; use only over HTTPS.
- Mutual TLS or signed requests: certificates or request signatures, common in banking and partner APIs.
Keeping a custom integration maintainable
- Version the API contract. Keep the OpenAPI file or request definitions in version control and note which API version you call.
- Watch for deprecations. Subscribe to the vendor's changelog and plan upgrades before old versions are switched off.
- Write down the mapping. Document which fields map where and why, so the next person doesn't reverse-engineer it.
- Alert on change. A sudden rise in 4xx errors often means the API changed underneath you.
Frequently asked questions
What is a custom API integration?
It's an integration built by calling a system's API directly, rather than using a pre-built connector. You configure authentication, requests, and data mapping for that specific API.
Do I need developers to build a custom API integration?
Not always. With a platform that offers a generic REST client and visual mapping, an integration specialist can configure it. Developers help with unusual authentication, complex pagination, or poorly documented APIs.
How long does a custom API integration take?
A simple integration with good documentation can take days. Complex ones with custom authentication, large data volumes, or many endpoints take weeks. See how long an API integration takes.
What if the system has no API at all?
Look for other options: database access, file exports over SFTP, webhooks, or a vendor-provided integration layer. Screen-based automation (RPA) is a last resort. See iPaaS vs RPA.
Is a custom API integration less reliable than a connector?
Not if it's built well. Reliability comes from authentication handling, pagination, retries, and monitoring, which apply equally to connectors and custom integrations.
Connect the systems your catalogue doesn't list
Every enterprise has a few systems no connector covers. With a generic REST client, careful mapping, and proper monitoring, they integrate as reliably as the rest. To see Koodisi connect a system without a native connector, book a demo.