Overview

When integrating with Totango’s search users API, we need to ensure we can properly map users and accounts between Totango and our system (cast.app). This document explains how to handle the required identifier fields in your Totango queries.

The Challenge

• Customers provide their own Totango queries
• Field names for user and account identifiers may not be consistent
• We need reliable ways to map users and accounts between systems

The Solution

We automatically add two essential identifier fields to every query:

1. totango_user_id for user identification
2. totango_account_id for account identification

How to Implement

1. Add User ID Field

Add this to the fields section of your query if not already present:

{
  "type": "string",
  "term": "identifier",
  "field_display_name": "totango_user_id"
}

2. Add Account ID Field

Add this to the parent_account_fields section of your query if not already present:

{
  "type": "string",
  "term": "identifier",
  "field_display_name": "totango_account_id",
  "index": 0
}

Example: Before and After

Before (Original Query)

{
  "object": "users",
  "query": {
    "terms": [
      {
        "type": "string_attribute",
        "attribute": "contact_account_role",
        "in_list": ["Customer"]
      }
    ],
    "fields": [
      {
        "type": "string_attribute",
        "attribute": "Email",
        "field_display_name": "Email"
      }
    ],
    "parent_account_fields": [
      {
        "type": "simple_date_attribute",
        "attribute": "Contract Start Date",
        "field_display_name": "Contract Start Date"
      }
    ]
  }
}

After (With Required ID Fields)

{
  "object": "users",
  "query": {
    "terms": [
      {
        "type": "string_attribute",
        "attribute": "contact_account_role",
        "in_list": ["Customer"]
      }
    ],
    "fields": [
      {
        "type": "string",
        "term": "identifier",
        "field_display_name": "totango_user_id"
      },
      {
        "type": "string_attribute",
        "attribute": "Email",
        "field_display_name": "Email"
      }
    ],
    "parent_account_fields": [
      {
        "type": "string",
        "term": "identifier",
        "field_display_name": "totango_account_id",
        "index": 0
      },
      {
        "type": "simple_date_attribute",
        "attribute": "Contract Start Date",
        "field_display_name": "Contract Start Date"
      }
    ]
  }
}

Important Notes

1. The field names must be exactly as shown:
   • Use totango_user_id for user identification
   • Use totango_account_id for account identification
2. For account ID, always set index: 0 in the parent_account_fields
3. These fields are required for proper system integration

Benefits

• Consistent user and account mapping between systems
• Prevents integration issues due to missing identifiers
• Works regardless of custom fields in customer queries

---

Totango Integration