WorkOS by Befocusy WorkOS Help center

Connect GNS and sync its customers with Companies

If your account has the GNS plugin enabled, a GNS card appears in Settings → Integrations. It connects WorkOS with GNS+ and, roughly every 15 minutes, brings its customers into the CRM Companies. GNS is the source of truth: WorkOS never writes anything to GNS.

Who can set it up

Only people with Technical administration permissions. Everyone else sees the card with a notice.

How to connect it

  1. Ask GNS support for the API key and API secret (they identify the target database: testing or production).
  2. In the GNS card, paste them and press Save. They are stored encrypted and never shown again; if you leave a field blank when saving again, the current one is kept.
  3. Press Test connection to check that GNS accepts the credentials.
  4. Press Review and sync (the first time, see "First sync" below) or, once the review is validated, Sync now to run a pass without waiting for the automatic cycle.

First sync: review to avoid duplicate companies

Before the first real sync you need to review the matches with the companies you already have in WorkOS. Until you validate it, the sync neither creates nor changes anything (the automatic one included).

  1. Click Review and sync. A two-column screen opens: on the left, each GNS customer; on the right, the WorkOS company that looks like the same one.
  2. WorkOS compares the Code, email, trade name, legal name and phone (ignoring accents, capitals and forms such as "S.A." or "LLC"). Clear matches come already selected; doubtful ones show as "Possible match" with a Use button.
  3. In the right column you can change the company by searching by name, code or legal name, choose Create as a new company or Do not sync this customer. A company can only be linked to one GNS customer.
  4. Click Validate and sync. The chosen companies are linked and updated with the official GNS data (Code, phone, country, legal name and email) without changing their name; customers marked as new are created when syncing and the ones you marked "Do not sync" are never created.

The review is done once. If you leave it halfway, what was already applied is kept and when you return you will only see what is left. In simulation mode you can review and validate, but nothing is saved until simulation is turned off. After validating it, the button is called Sync now and Review matches stays available for new GNS customers that are not linked yet. The review is only considered finished when every GNS customer has a decision (link, create or do not sync). If any is missing, WorkOS tells you and you can reopen the review to complete them. A suggestion based only on a matching email or phone is not pre-selected unless the name looks alike: check it before accepting.

How customers are synced

Each GNS customer is matched with a Company through its Code, which must contain the customer's document number in GNS (dots, dashes and spaces are ignored; if a Company has several codes separated by "|", any of them works).

  • New Company: if no Company has that Code, it is created with its name, Code, phone and country (when those properties are set up and the country already exists as an option). It starts in the first status of the Companies Kanban.
  • Existing Company: the first time it is only linked, with no changes. After that, name, phone and country are updated only when they change in GNS; a manual edit made in WorkOS is kept as long as GNS does not change that customer again.
  • Skipped: customers without a document number or name, those marked as not a customer (for example, supplier only), document numbers repeated in GNS, overly long or malformed data, document numbers shorter than 5 characters, and document numbers that match several Companies (review them and keep a single Code per Company).
  • A Company that was already linked and is archived or loses its Code is not created again.

Simulation mode

If your workspace is in simulation mode, the sync only counts what it would do, without creating or changing anything. The card says so and shows the result of the last pass.

If something fails

  • GNS rejected the credentials: check the API key and API secret with GNS support.
  • "Code" is not mapped: set up the Companies Code property in Databases.
  • No initial status: define the Companies statuses in their Kanban.

Clients with several emails in GNS

GNS stores a single email field per client, which may hold several addresses separated by «;». If that field mixes the client's addresses with those of your own team (for example internal copies), ask technical support to set your company's own email domains: WorkOS ignores them and keeps the client's first address on the Company. If every address is internal, the Company's email stays empty. Without own domains, the first address is used.