Setting up account verification

Nicolas Audet
Nicolas Audet
  • Updated

Guide: Account verification

This article is part of a larger guide going over the concept of verifying a customer's identity with a PIN.

Overview

Account Verification lets your team, or an automated channel such as a chatbot or an IVR system, confirm a customer's identity by sending a one-time 6-digit PIN to the account's primary contact. Before anyone can verify a customer, the feature needs to be enabled for your organization and a few settings need to be in place.

This article covers how to request the feature, grant permissions, set up the email and SMS templates, and prepare accounts and API access so PINs reach your customers. Once setup is complete, see Verifying a customer's identity for the verification flow itself.

 

How it works

PIN 6 digits, sent by email or SMS to the account's primary contact. Only the selected method is used, never both.
PIN expiry 10 minutes after it is sent. Sending a new PIN cancels the previous one.
Verified session Configured for your organization when the feature is enabled (1 hour by default). After that, the account returns to unverified.
Cost Included at no additional cost. PINs are sent through your existing email and SMS integrations.
Scope Verification confirms identity only. It does not prevent users from taking action on an unverified account.

 

Setting up account verification

Complete these steps in order. Steps A and B are done by gaiia; the others are done in your instance.

A. Request the feature

Contact gaiia at support@gaiia.com to enable Account Verification. In your request, include:

  1. The instances to enable (for example, your sandbox first, then production).
  2. The verified session duration you want, if different from the 1-hour default.
  3. Whether you want the SMS preference override (see step E).

Until the feature is enabled, API calls return the FEATURE_NOT_ENABLED error and the verification button doesn't appear on accounts.

B. Grant permissions

Verification permissions are part of the Accounts permission group.

  • Grant the Edit verification permission to users who verify customers.
  • Grant the View verification permission to users who only need to see the verification status.

C. Set up the email and SMS templates

The PIN is sent with the Verification PIN system message, which has an email and an SMS version. Customize both to match your branding and legal requirements.

  1. Go to Settings > System messages > Verification PIN.
  2. Open the Email template, edit the subject and body, and make sure it is Enabled.
  3. Open the SMS template, edit the message, and make sure it is Enabled.
  4. Repeat for each language your customers use. A PIN is only sent if the template is enabled in the account's language.

Both templates must include the pin merge tag. The following merge tags are available:

Merge tag Value
{{pin}} The 6-digit PIN. Required.
{{customerName}} The primary contact's first name.
{{entity.firstName}} The primary contact's first name, from the account.

For all other available tags, see Merge Tags.

If you mention the expiry in your template (for example, "This PIN will expire in 10 minutes"), keep it in line with the actual expiry. Your customers and any chatbot scripts rely on it.

D. Test the templates

  1. In the template editor, click Send test and confirm the PIN appears where expected.
  2. Send a real PIN to a test account whose contact details you control.
  3. Check what was sent: open the account, click the Ellipsis menu, select Details, then View email.
    If the PIN appears in gaiia's copy but not in your inbox, your email client is hiding part of the message. Open it in a different email client or in webmail, and consider simplifying the styling of the block that holds the PIN.

E. Prepare accounts for SMS

Email PINs work for any account with a primary contact email. SMS PINs have two additional requirements:

  1. The primary contact has a mobile number.
  2. SMS is turned on in the account's communication preferences. If it is off, SMS is not offered in gaiia, and a PIN requested by SMS through the API is not delivered.

To turn SMS on for an account, open the account and go to its Preferences tab.

If your customers often don't have SMS turned on, ask gaiia to enable the SMS preference override. With it, users can send a PIN by SMS even when the preference is off, after confirming the customer asked for it. API callers can do the same with smsOptions: { bypassPreferences: true }.

F. Set up API access (chatbots and IVR)

If an automated channel will verify customers, create an API key for it. Any valid API key for your organization can call initiatePinVerification, verifyPinVerification, and the pinVerification query; no specific permission group is required. To look up the account first, the key also needs permission to read accounts.

For the API calls and error codes, see Verifying a customer's identity.

 

Setup checklist

  • Account Verification is enabled by gaiia on each instance.
  • Users have the Accounts > Edit or Accounts > View verification permission.
  • The Verification PIN email and SMS templates are enabled in every language and include {{pin}}.
  • A test PIN was received by email and, if used, by SMS.
  • Accounts that will receive SMS PINs have SMS turned on in their communication preferences, or the SMS preference override is enabled.
  • Automated channels have an API key.

Related to

Was this article helpful?

Have more questions? Submit a request