Skip to main content

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​

See Integrations 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.getValue for 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​

See Using APIs in 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​

See Integrations 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.