Integrations Best Practices
Recommended practices drawn from across the Integrations guides, covering how to connect other systems safely and keep the connection easy to maintain.
Overview
- Decide the direction first. Service accounts let outside systems call in, API integrations let UNICONNECT AI call out, and webhooks let events arrive. Pick the one that matches the need.
- Start with one read only endpoint. A lookup is easy to test and cannot change data in the outside system.
Service Accounts
See Service Account Configuration.
- Create one service account for each tool. An account can then be removed when its tool is retired, without affecting the others.
- Give each account a limited role. A reporting tool that only reads data does not need a role that can change records.
- Store the credential in one secure place. Request a token when needed instead of copying the credential into several tools.
- Watch the seat counter. Each active service account uses a license seat.
Collections
See Collections.
- Use one collection for each outside system. Shared settings are then kept in one place.
- Put shared headers and the base address on the collection. Each API then needs only its path.
- Name collections after the system. A name such as PolicyHub KYC is easy to recognize in a list.
APIs and Scripts
See Creating an API, Pre and Post Scripts and Collection Scripts and Authentication.
- Test every API with Send before using it. The response also records the schema the CRM needs.
- Let a collection script manage tokens. Reuse a saved token, fetch a new one when needed and retry after an expired token.
- Make every variable resolve. A call with an unresolved variable fails, so give a default only where a sensible default exists.
- Use
utils.getValuefor fields from outside responses. It returns a fallback when a field is missing.
Response Format
See Response Format the CRM Requires.
- Reshape in the Post Script, not in the CRM. The module expects a data array and a pagination object, so the API should return exactly that.
- Match field names to the module's field codes. The envelope is only half of the work.
- Run Send again after changing a script. The saved response schema should match the new shape.
External Modules
See Creating an External Module and Assigning APIs to a Module.
- Mark the primary key straight after saving. A module without one cannot load records.
- Assign only the APIs agents need. Leave Post, Update and Delete empty for a lookup module.
Workflows
- Set a timeout that suits the workflow. A lookup that should not hold up the process needs a short timeout.
- Handle a failed call. Add a Condition after the action so the workflow can continue when the outside system does not answer.
Webhooks
See Webhooks.
- Paste a complete sample payload. The schema is built from the sample, so a missing field is missing from the schema.
- Share the address only with the sending system. Anyone who has it can post to it.
LDAP Authentication
See LDAP Authentication.
- Use a dedicated search account. The LDAP account only needs to search the directory.
- Prefer
ldaps. The secure address protects the sign in traffic.
Permissions
- Switch API and Webhook on for a few administrators only. Collections and service accounts hold credentials.
- Use a dedicated role for each service account. Do not reuse an administrator role.