Searching for accounts

Searching for accounts

When using the /account/v1/search/accounts endpoint, the request object must include a body. The body must specify at least one of the following search parameters using the following syntax:

{
  "data": {
    "attributes": {
      "accountNumber": "stringValue",
      "companyName": "stringValue",
      "firstName": "stringValue",
      "lastName": "stringValue",
      "organization": {
        "id": "stringValue"
      },
      "phoneNumber": "stringValue",
      "producerCode": {
        "id": "stringValue"
      },
      "taxId": "stringValue"
    }
  }
}

Note the following requirements and restrictions:

• The request object must include at least one of the required parameters.
  • There are also optional search parameters that can be added. For a complete list, refer to the API definition of the endpoint.
• When searching by companyName:
  • The request object cannot include firstName or lastName.
  • The search returns only accounts where the account holder is an exact match of the named company.
• When searching by first and last name:
  • The request object must include both firstName and lastName.
  • The request object must omit companyName.
  • The search returns only accounts where the account holder is an exact match of the named person.

For example, the following payload will query for all accounts with account number C000143542:

{
  "data": {
    "attributes": {
      "accountNumber": "C000143542"
    }
  }
}

The following payload will query for all accounts where the account holder has a first name of "Ray" and a last name of "Newton":

{
  "data": {
    "attributes": {
      "firstName": "Ray",
      "lastName": "Newton"
    }
  }
}

Searching by producer

The /account/v1/search/accounts endpoint allows you to search using two criteria pertaining to producers: producerCode and organization.

If you know a producer's code, you can search for all accounts associated with that producer by including producerCode as a search criteria. For example, the following searches for accounts associated with producer code pc:16 (ACV Property Insurance).

{
  "data": {
    "attributes": {
      "producerCode": {
        "id": "pc:16"
      }
    }
  }
}

In the base configuration, producers are stored in the Organization entity. If you know a producer's ID, you can search for accounts associated with that producer by including the organization as search criteria. For example, the following searches for accounts associated with the producer whose id is pc:4 (ACV Property Insurance).

{
  "data": {
    "attributes": {
      "organization": {
        "id": "pc:4"
      }
    }
  }
}

Providing no search parameters

PolicyCenter will not execute an account search with no query parameters. If you attempt to execute an account search without query parameters, either from the user interface or through Cloud API, PolicyCenter returns the following error message:

Please enter enough search information: first name or last name, company name, account number, 
phone number, producer information, or an official ID. If searching by last name with partial 
match, either city and state, or ZIP are required. At least three letters are required for 
names (five for companies) with partial match."

Note that this message is intended primarily for user interface account searches. This is why it makes reference to partial matches and a minimum number of required letters.

Searching in Japanese

The search endpoint also supports certain Japanese locale-specific fields:

• companyNameKanji: Complete company name, in Japanese
• firstNameKanji: Complete first name, in Japanese. Can be used in combination with firstName or lastNameKanji.
• lastNameKanji: Complete last name, in Japanese. Can be used in combination with lastName or firstNameKanji.
• particle: Particle used in account holder names (matching the particle property of an AccountContact resource)

The following code block is a request body for a search based on first name and first name in Japanese:

{
  "data": {
    "attributes": {
      "firstNameKanji": "太郎",
      "firstName": "Taro"
    }
  }
}