Verifying a customer's identity

Overview

Account Verification confirms that the person you are communicating with is the account holder. gaiia sends a one-time 6-digit PIN to the account's primary contact, and the customer reads it back to confirm their identity. Every verification is recorded in the account's activity, so you always have a clear record of the actions taken while an account was verified or unverified.

A customer can be verified in two ways:

• By an agent in gaiia, during a support session.
• Through the gaiia API, by an automated channel such as a chatbot or an IVR system.

This article covers both flows, how the verified session works, and how to follow up when a customer doesn't receive their PIN.

Account Verification must be enabled for your organization before it can be used. See Setting up account verification.

Verifying a customer during a support session

Verifying an account requires the Accounts > Edit verification permission. Users with the Accounts > View verification permission can only see the verification status.

A. Check the account's verification status

The verification status is displayed at the top-right corner of the account page:

• Unverified accounts: the verification button appears grey.
• Verified accounts: the verification button appears blue.

B. Send the PIN

The PIN is sent only to the method you select (email or SMS), never both.

1. Click the grey verification button on an unverified account.
2. In Send PIN to, select the primary contact's email address or mobile number.

   SMS is only offered when the primary contact has a mobile number and SMS is turned on in the account's communication preferences. If the SMS preference override is enabled for your organization, SMS is also offered when the preference is off: check I confirm the customer requested to receive this PIN via SMS before sending.

3. Click Send PIN.

C. Verify the customer's PIN

The PIN expires 10 minutes after it is sent. Sending a new PIN cancels the previous one.

Once the customer provides the 6-digit PIN:

1. Enter the PIN in Enter PIN provided by customer and click Verify PIN.
2. If the PIN is incorrect, re-enter it or restart the process.
3. If the PIN is correct, you receive a confirmation and can proceed to take action on the account.

Account Verification confirms the customer's identity; it does not block users from taking action on an unverified account.

When the customer doesn't receive the PIN

1. Ask the customer to check their spam or junk folder.
2. Click Resend the PIN in the verification modal.
3. Confirm the PIN was sent: open the account, click the Ellipsis menu, select Details, then View email. This shows the email exactly as gaiia sent it, PIN included.

   If the PIN appears in gaiia's copy but not in the customer's inbox, the customer's email client is hiding part of the message. Ask them to open it in a different email client or in webmail.

4. If SMS is not offered as an option, check that the primary contact has a mobile number and that SMS is turned on in the account's communication preferences.

Continuing an existing support session

A verification stays valid for the session duration configured for your organization (1 hour by default). The time it expires is shown on the verification button.

If the verification expires while you are still talking with the same customer, you can extend it without sending a new PIN:

1. Click the verification button, then click Extend previous session.
2. Check I accept full responsibility to confirm this is the same person you verified earlier.
3. Click Extend verification.

Only extend a session when you are certain you are speaking with the same person. If unsure, complete a new PIN verification.

Verifying a customer through the API

Automated channels such as chatbots and IVR systems can run the same verification through the gaiia GraphQL API (https://api.gaiia.com/api/v1). Any valid API key for your organization can call these operations; no specific permission group is required.

A. Send the PIN

Call initiatePinVerification with the account's global ID and the delivery method (EMAIL or SMS). Keep the returned verification id for the next step.

mutation {
  initiatePinVerification(
    entityId: "account_XXXXXXXXXXXXXXXXXXXXXX"
    input: { communicationMethod: EMAIL }
  ) {
    verification { id status pinExpiresAt }
    errors { code message }
  }
}

SMS follows the account's communication preferences. If SMS is turned off for the account and the SMS preference override is enabled for your organization, add smsOptions: { bypassPreferences: true } to the input. Only do this when the customer has asked to receive the PIN by SMS.

B. Submit the PIN

When the customer provides the PIN, call verifyPinVerification with the verification ID.

mutation {
  verifyPinVerification(
    verificationId: "pin_verification_XXXXXXXXXXXXXXXXXXXXXX"
    input: { pin: "123456" }
  ) {
    verification { id status verifiedAt verificationExpiresAt }
    errors { code message }
  }
}

A successful call returns the status "VERIFIED" and the time the verified session expires.

C. Check the verification status

Use the pinVerification query to check whether an account is currently verified, for example before sharing account details later in the conversation.

query {
  pinVerification(entityId: "account_XXXXXXXXXXXXXXXXXXXXXX") {
    status
    verificationExpiresAt
  }
}

Error codes

Expected errors are returned in the errors field with an HTTP 200 response.

A successful initiatePinVerification response means the PIN was created and queued for delivery. If the customer doesn't receive it, see When the customer doesn't receive the PIN.

Monitoring account activity

An activity log entry is automatically created when a PIN is sent, when an account is verified, and when it loses its verified status. Verifications completed through the API are labeled as such. These logs are available in the account's Activity tab, offering a clear record of the actions taken while in either state.