Decide what to expose
Not every endpoint the API offers — only the operations a process will actually use. A connector exposing forty operations has thirty-five untested paths and a much larger surface to maintain when the API changes.
Nintex API & Integration Services
A good connector makes someone else's API look like it always belonged here.
The alternative is a raw web request buried in a workflow, with the URL hard-coded, the token pasted in, and nobody able to tell what it does. Twopir Consulting builds proper connectors with the Nintex Xtensions framework — defined in OpenAPI, authenticated as a managed connection, reusable across the estate, and honest about how they fail. Connector engineering, authentication, pagination, rate limits and retries.
Connector Contract Stack Twopir · 2πr
Layer 01
The System's REST API
Endpoints Payloads Status codes Limits
Layer 02 · 2πr
OpenAPI Definition & Xtension Connector
Operations Connection & Auth Error Mapping
Layer 03
Actions in the Designer
Reusable Typed Predictable
Rule No credential ever lives inside a workflow
What is API integration, in Nintex terms?
An API is the published contract by which one system lets another ask it for something or tell it to do something. API integration is the work of consuming that contract reliably. In Nintex, that means turning a service reachable by RESTful call into a connector using the Xtensions framework: you supply an OpenAPI specification — which can be imported from a reachable URL — and the operations it describes become actions a builder drags onto a canvas, with typed inputs and outputs and the authentication handled as a managed connection rather than pasted into a workflow.
This page is the engineering layer. The programme question — which systems should connect, who owns which field, and how divergence is detected — is covered on Nintex integration services. A connector is also one option on the ladder covered in Nintex customization services, and both sit inside the wider Nintex consulting practice.
| Web request inside a workflow | Custom connector | |
|---|---|---|
| Where the credential lives | In the workflow, or in a variable someone can read. Rotating it means editing every workflow that uses it. | In one managed connection. Rotation is a single change and nothing else moves. |
| What a builder sees | A URL, a method, headers and a JSON body they must construct and parse by hand. | A named action with typed inputs and outputs, like every other action in the designer. |
| Reuse | Copied into the next workflow, where it immediately begins to diverge. | Built once, used across the estate. A fix applies everywhere. |
| When the API changes | Every copy has to be found. Some will not be, and they fail silently. | The definition is updated in one place and the change is versioned deliberately. |
| Error handling | Whatever the builder thought to add — usually nothing, because the response was not inspected. | Failures mapped to retryable or fatal, so the workflow's error handling can act on them. |
| When it is fine anyway | A genuine one-off, in one workflow, against a stable internal endpoint, with no credential of consequence. | Everything else, and certainly anything a second workflow will ever need. |
Getting in, and staying in
Authentication is where most connector projects lose their first week, and where most of the long-term operational risk sits. The pattern is chosen by what the API supports and by whose identity the process should act under.
| Pattern | Use when | What to watch |
|---|---|---|
| API key | The API offers nothing better, and the process acts as an application rather than as a person. | Rotation. A key with no expiry and no owner is a key that will still be valid when the person who issued it has left. |
| OAuth 2.0, user-delegated | The action must happen as a specific person and the API enforces that person's permissions. | Refresh token expiry, and what happens when the authorising user leaves — this is the most common cause of a connector that worked for a year and then stopped. |
| OAuth 2.0, service identity | The process acts as itself, at machine scale, with a scoped permission set of its own. | Scope creep. Grant the minimum the operations need, and review it when new operations are added rather than broadening once and forgetting. |
| Certificate or signed request | Finance, health and public-sector APIs where a shared secret is not acceptable. | Certificate expiry dates, which are a scheduled outage nobody has in their calendar until the first time it happens. |
| Basic authentication | Legacy internal systems that support nothing else. | Treat it as a temporary state, require transport encryption, and use an account created for the purpose rather than a person's login. |
Whichever pattern applies, the credential is held in the connection rather than in a workflow, the identity is one created for the integration, and the expiry date exists somewhere a human will see it before it passes.
Seven things that decide whether a connector survives production
The happy path is an afternoon. These are the rest of the estimate, and skipping them is why an integration that passed testing fails in its second month.
| Concern | What goes wrong | How we handle it |
|---|---|---|
| Pagination | The first page is read and the rest is never fetched. Testing passed because the test data fitted on one page. | Implement the API's own paging contract, test against a data set large enough to need several pages, and bound the total to avoid an unintended full extract. |
| Rate limits | Fine in testing, rejected at month-end when a loop starts making calls far faster than the API allows. | Read the published limits for that API, keep calls out of tight loops, batch where supported, and back off on a throttling response rather than retrying immediately. |
| Idempotency | A retry after a timeout creates a second record. The first call had actually succeeded; only the response was lost. | Use the API's idempotency mechanism where it has one, otherwise check-then-act with a business key so a repeat is detectable rather than duplicated. |
| Error semantics | Every failure is treated identically, so a permanent validation error is retried five times and a transient network error is not retried at all. | Map responses explicitly to retryable and fatal, surface the API's own message rather than a generic one, and let the workflow decide what to do with each class. |
| Timeouts | A slow endpoint holds an instance open, and at volume that becomes a queue nobody is watching. | Explicit timeouts on every call, an asynchronous pattern for genuinely long operations, and a defined behaviour when the timeout is reached. |
| Payload size | An attachment or a large collection exceeds what the platform or the API will carry, and only in production. | Establish the real limits against your tenant and the target API, then design for them — chunking, references instead of embedded content, or a different transport. |
| Versioning | The vendor ships a change, the definition no longer matches, and every workflow using the connector fails at once. | Pin to a versioned API path where one exists, version the connector deliberately, subscribe to the vendor's change notices, and test against a sandbox before the change reaches production. |
We state no numeric limits here on purpose. Platform quotas differ by edition and change between releases, and the target API has its own. Both get verified against your tenant during design rather than taken from a datasheet.
How a custom connector gets built
Six steps. The first one is the one teams skip, and it is the one that keeps the connector small enough to maintain.
Produce the definition
An OpenAPI specification for those operations — imported from the vendor's published definition where one exists, drafted where it does not. Nintex provides an in-product editor with schema validation, and an AI-assisted generator that can produce a starting schema from a description.
Configure the connection
Authentication established as a managed connection, with a purpose-created identity, the minimum scope the operations need, and the expiry recorded where somebody will act on it.
Handle the unhappy paths
Pagination, throttling, timeouts, idempotency and error classification implemented and tested deliberately — against a data set large enough and a rate fast enough to actually provoke them.
Make it readable
Operations, inputs and outputs named the way a business builder would describe them, not the way the API documents them. A connector nobody can interpret gets bypassed with a raw web request, which defeats the purpose.
Document and hand over
What each operation does, which credential it uses and when that expires, what each error class means, and how to update the definition when the vendor changes the API. Then your team can own it.
The systems that usually need a connector built
Mainstream platforms usually ship with a connector already. These are the cases where one has to be made.
In-house applications
The system your organisation built and depends on, which no vendor will ever ship a connector for. Usually the highest-value connector in the estate, because it holds data nothing else has.
Industry and vertical platforms
Core banking, practice management, clinical systems, logistics platforms — APIs that are real and well documented but serve too narrow a market for a ready-made connector to exist.
Data and enrichment services
Credit checks, address and identity verification, sanctions screening, pricing and tax services — called at a decision point in a process, where latency and failure behaviour matter more than throughput.
Internal service layers
Where an organisation has its own API gateway or service layer, the connector targets that rather than the systems behind it — which keeps the estate insulated from changes further down.
Event and webhook receivers
Where the other system can push rather than be polled, a workflow can be started by an inbound call — which is cheaper and fresher than polling, provided duplicates and out-of-order delivery are designed for.
Replacing a bot with an API
A screen-level automation that exists because nobody looked for an interface. When one turns out to exist, replacing the bot with a connector removes an entire class of fragility permanently.
Connector questions engineers ask us
Yes. Where a definition can be imported from a published URL that is the fastest route, but where none exists we write one for the operations you need, working from the API documentation and from observed responses. Nintex provides an editor with schema validation, and an AI-assisted generator that can produce a starting schema from a description — useful as a draft, though every generated schema still needs checking against the API's real behaviour before anyone relies on it.
One per system, exposing only the operations that are genuinely needed, and extended as new needs appear. One per use case produces several connectors against the same API that drift apart and all have to be updated when the vendor changes something. The opposite failure — exposing every endpoint "for completeness" — leaves you maintaining and re-testing operations nobody has ever called. Start narrow and grow deliberately.
You cannot prevent the change, only make it survivable. Pin to a versioned API path where the vendor offers one, so a new version does not arrive underneath you. Subscribe to their change notices and assign that mailbox to a person rather than a shared inbox nobody reads. Keep a sandbox connection so a change can be tested before it reaches production. And define the failure behaviour, so if a field disappears the workflow fails loudly and immediately rather than continuing with an empty value.
Webhooks where the source system supports them: fresher data, far fewer calls, and no polling interval to argue about. The cost is that events can be delivered twice, out of order, or not at all, so the receiving workflow has to be idempotent and you need a catch-up mechanism for anything missed. Polling is simpler and more predictable but wastes calls and adds latency equal to the interval. A common compromise is webhooks for freshness plus a low-frequency reconciliation sweep to catch what was dropped.
That is the intent, and it is realistic if someone on your side is comfortable reading an OpenAPI definition. We hand over the definition, the connection configuration, the error mapping and a short runbook covering how to add an operation, rotate the credential and respond to a vendor change. If nobody on your team has that background, we would rather say so during design and agree a support arrangement than hand over something that quietly becomes unmaintained.
Four things, and the first two decide most of the estimate: the API documentation including its authentication method and published limits, a sandbox or test environment with credentials, the list of operations a process actually needs, and the expected call volume and pattern. The last one matters more than teams expect — an operation called twice a day and the same operation called four thousand times in a batch window are different engineering problems even though the API call is identical.
Next Step
Send us the API documentation, and we will tell you what it takes
Most connectors are scoped from the documentation, the authentication method and the expected call volume. If the API has real problems — no pagination contract, unclear error semantics, undocumented limits — it is better to know that before the build than during it.
Connectors that are reusable, readable and predictable when the API is not
