Search for policy periods

You might need to find a specific policy period, but you do not know the policy period's ID. You can use the following endpoint to search for the policy period:

  • POST /billing/v1/search/policies

The request body can include various search parameters. The response returns an array of policy periods that match all the search parameters.

String and typekey search parameters

You can search for policy period using fields related to the policy itself, the account, the policy contacts, and producer codes.

Some search parameters are strings, such as accountName. For all string search parameter fields, BillingCenter supports partial string matching. The search value must match the beginning of the string.

For example, the following matches an account with a contact with the last name "Newton":

{
    "data": {
        "attributes": {
            "contactLastName": "newto"
        }
    }
}

The following does not match, because the beginning of the string is not included:

{
    "data": {
        "attributes": {
            "contactLastName": "ewton"
        }
    }
}
Note: You can search for policy periods based on both primary and non-primary contacts.

When searching by account number, BillingCenter identifies an account based on the partial string and returns all the account's policy periods. The following returns all policy periods owned by accounts whose account number starts with "monrovia."

{
  "data": {
    "attributes": {
      "accountNumber": "monrovia"
    }
  }
}

Policy periods are associated with producer codes that earn commission on the policy. You can perform a partial string search on producerCode to find all policy periods on which a producer code earns commission in any role. The following returns policy periods which have associated producer codes beginning with "allrisk."

{
  "data": {
    "attributes": {
      "producerCode": "allrisk"
    }
  }
}

The archived field

The Boolean field archived filters policy periods based on whether they are archived.

{
  "data": {
    "attributes": {
      "archived": true
    }
  }
}

In the BillingCenter user interface, this value appears on the policy search page as a check box with the label Include Archived Policies. The check box is always either checked or unchecked, so by default, the user interface search uses this field as a search parameter.

In Cloud API, archived is not used as a search parameter by default. If this field is not set in the request, both archived and non-archived policies are returned. Therefore, you have the following options for this field:

  • Not set (null): All policies are returned, regardless of whether they are archived or not
  • false: Only non-archived policies are returned
  • true: Only archived policies are returned

Searching without parameters

You can perform a search without any parameters by sending an empty data wrapper. 

{
  "data": {
    "attributes": {}
  }
}

If there are more than 300 policy periods to be returned, the request will fail.

Response details

BillingCenter returns a list of objects: one object for each policy period that matches the search criteria. Each object includes fields for that policy period, including the ID and the effective and expiration dates. There are also references to the account, the parent policy, the primary producer code, and the primary producer.

Below is an example request that returns one policy period:

Command 
POST /billing/v1/search/policies

Request body

{
  "data": {
    "attributes": {
      "producerCode": "allriskprodcode"
    }
  }
}

Response

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "account": {
                    "displayName": "Block-126-PA",
                    "id": "bc:SwV9HdPHBy_2n0HeNypVH",
                    "type": "Account",
                    "uri": "/billing/v1/accounts/bc:SwV9HdPHBy_2n0HeNypVH"
                },
                "archived": false,
                "closureStatus": {
                    "code": "open",
                    "name": "Open"
                },
                "currency": {
                    "code": "usd",
                    "name": "USD"
                },
                "effectiveDate": "2025-09-29T00:00:00.000Z",
                "expirationDate": "2026-09-29T00:00:00.000Z",
                "id": "bc:ScNZtpmEaX3ZYESc66xdu",
                "policy": {
                    "displayName": "KTLCSS-000105:0",
                    "id": "bc:Sd-1W0jDV6iXJbBo-2sA7",
                    "type": "Policy",
                    "uri": "/billing/v1/accounts/bc:SwV9HdPHBy_2n0HeNypVH/policies/bc:Sd-1W0jDV6iXJbBo-2sA7"
                },
                "policyNumberLong": "KTLCSS-000105:0-1",
                "producer": {
                    "displayName": "Donut-103-Zork",
                    "id": "bc:SIsAJ8N2OYxyoS47DTicI",
                    "type": "Producer",
                    "uri": "/billing/v1/producers/bc:SIsAJ8N2OYxyoS47DTicI"
                },
                "producerCode": {
                    "displayName": "Allrisk (AllriskProdCode1)",
                    "id": "bc:S5ukr6wCnz5VyB-GAgPMs",
                    "type": "ProducerCode",
                    "uri": "/billing/v1/producers/bc:SIsAJ8N2OYxyoS47DTicI/producer-codes/bc:S5ukr6wCnz5VyB-GAgPMs"
                }
            }
        }
    ],
    "links": {
        "first": {
            "href": "/billing/v1/search/policies",
            "methods": [
                "post"
            ]
        },
        "self": {
            "href": "/billing/v1/search/policies",
            "methods": [
                "post"
            ]
        }
    }
}