Basic contact search criteria

Contact searches are executed using the POST /contact/v1/search/contacts endpoint. The request object must include a body, which specifies the search criteria. The request must also include a contact subtype and at least one of the following:

  • lastName (if the search is for an ABPerson or one of its subtypes)
  • name (if the search is for an ABCompany or ABPlace, or one of their subtypes)
  • taxId

Contact subtypes

For all contact searches, you must specify the contact subtype. This is specified using the following syntax:

...
        "contactSubtype": {
            "code": "<subtype>"
        }
...

For example, the following specifies a search for all ABDoctors:

{
  "data": {
    "attributes": {
        "contactSubtype": {
            "code": "ABDoctor"
        }
    }
  }
}

The ABContact data model entity is subtyped. When you specify a subtype, the search will include any contacts whose type is the specified subtype or a descendant of the specified subtype. For example, searches for ABPersonVendor will return ABPersonVendors, ABDoctors, and ABAttorneys.

If you specify a contact subtype and a field that is not available for that contact subtype, ContactManager returns an error. For example, if you execute a search for ABCompany contacts with a lastName of "Smith", the following error message is returned:

"The property 'firstName' and 'lastName' is not valid for subtype 'ABCompany'. Valid
      subtypes are: [ABAttorney, ABPersonVendor, ABPerson, ABAdjudicator, ABDoctor]"

If you want to execute a search for all contacts regardless of their subtype, specify ABContact as the search subtype.

Minimum search criteria

  • lastName (if the search is for an ABPerson or one of its subtypes)
  • name (if the search is for an ABCompany or ABPlace, or one of their subtypes)
  • taxId

Match types

A match type is an expression that is associated with a String search criteria field, such as the LastName field. The match type identifies how to use the search criteria value to find the appropriate search results. All InsuranceSuite applications, including ContactManager, support multiple match types, including:

  • Equals
  • Starts with
  • Starts with case sensitive
  • Contains

When you conduct a search through Cloud API, the match types for each String field are determined by the InsuranceSuite application. For example, in the ContactManager base configuration, searches on an ABContact's LastName use "starts with". To determine which match type is used for a given search criteria String in ContactManager, see the Contact Management Guide.

General search examples

The following executes a search for all ABDoctor contacts whose last name starts with "Smith".

{
  "data": {
    "attributes": {
        "contactSubtype": {
            "code": "ABDoctor"
        },
        "lastName": "Smith"
    }
  }
}

The following executes a search for all ABCompany contacts whose name is "Express Auto".

{
  "data": {
    "attributes": {
        "contactSubtype": {
            "code": "ABCompany"
        },
        "name": "Express Auto"
    }
  }
}

The following executes a search for all ABPerson contacts with a Tax ID of "000-00-1212".

{
  "data": {
    "attributes": {
        "contactSubtype": {
            "code": "ABPerson"
        },
        "taxId": "000-00-1212"
    }
  }
}

Note the following about taxId:

  • In the base configuration, the taxId field is masked and only the last four digits are returned in a GET payload. However, if you provide taxId in a contact search, you must provide the unmasked value.
  • In the base configuration, the taxId field uses a field validator that requires the format of the value to be either NNN-NN-NNNN (for ABPerson) or NN-NNNNNNN (for ABCompany), where N is a digit. ContactManager will not execute searches using tax IDs that do not match the field validator pattern.

Searching for contacts whose name is in kanji

If the instance of ContactManager uses the Japanese language, you can use the following alternate fields:

  • For lastName: lastNameKanji
  • For firstName: firstNameKanji
  • For name: companyNameKanji

Tag-based searches

You can include contact tags in search criteria. Tag criteria are specified using the following syntax:

...
        "tags": [
          {
            "type": {
              "code": "<tag>"
             }
          },
          {
            "type": {
              "code": "<tag>"
            }
          },
          ...
        ],
...

For example, the following executes a search for all ABPersons whose last name starts with "Newton" and who are tagged as a "client".

{
  "data": {
    "attributes": {
        "contactSubtype": {
            "code": "ABPerson"
        },
        "lastName": "Newton",
        "tags": [
          {
            "type": {
              "code": "client"
            }
          }
        ]
    }
  }
}

You can include multiple tags. By default, the search will return any contact with at least one of the tags. For example, the following executes a search for all ABPersons whose last name starts with "Newton" and who are tagged as either a "client" or "claim party".

{
  "data": {
    "attributes": {
        "contactSubtype": {
            "code": "ABPerson"
        },
        "lastName": "Newton",
        "tags": [
          {
            "type": {
              "code": "client"
            }
          },
          {
            "type": { 
              "code": "claimparty"
            }
          }
        ]
    }
  }
}

If you want the search to return only contacts with all specified tags, include the allTagsRequired field and set it to true. For example, the following executes a search for all ABPersons whose last name starts with "Newton" and who are tagged as both a "client" and a "claim party".

{
  "data": {
    "attributes": {
        "contactSubtype": {
            "code": "ABPerson"
        },
        "lastName": "Newton",
        "tags": [
          {
            "type": {
              "code": "client"
            }
          },
          {
            "type": {
              "code": "claimparty"
            }
          }
        ],
        "allTagsRequired": true
    }
  }
}

Include "pending create" contacts

Contacts are typically not created directly in ContactManager. Rather, they are created in BillingCenter, and BillingCenter sends the new contact to ContactManager.

BillingCenter has a "Create address book contacts" (abcreate) permission. If a BillingCenter user with this permission creates a contact, it is copied to ContactManager. The contact is returned in any search where the contact meets the search criteria.

If a BillingCenter user without the "Create address book contacts" creates a contact, the contact is still copied to ContactManager. However, it is flagged as "pending create". By default, the contact is not returned in any search, even if it meets the search criteria. ContactManager users with the "view pending" (abviewpending) permission can view and approve "pending create" contacts. Once a "pending create" contact is approved, it is treated as a normal contact.

The POST /contacts/search endpoint has an includePendingCreates filter. You can use this filter to override the default behavior and have "pending create" contacts included in the search results. For example, the following executes a search for all ABDoctor contacts whose last name starts with "Smith", including those contacts that are flagged as "pending create".

POST /contacts/v1/search/contacts?filter=includePendingCreates:eq:true

{
  "data": {
    "attributes": {
        "contactSubtype": {
            "code": "ABDoctor"
        },
        "lastName": "Smith"
    }
  }
}