Search for accounts

You might need to access a specific account, but you do not know the account's ID. You can use the following endpoint to search for the account:
  • POST /billing/v1/search/accounts

In the request body, you can specify search parameters. The response contains an array of accounts that match all the search parameters.

String and typekey search parameters

You can search for accounts using certain account fields, as well as fields for the policies and contacts on that account.

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 accounts based on both primary and non-primary contacts.

You can also search using typekey references, such as account segment. Typekey references do not match on partial strings. However, they are case-insensitive.

For example, you can use the following request payload to search for accounts whose primary contacts reside in California.

{
    "data": {
        "attributes": {
            "contactState": {
                "code": "ca"
            }
        }
    }
}

The hasChargeHolds field

The Boolean field hasChargeHolds filters accounts based on whether there are charge holds on the account.

{
    "data": {
        "attributes": {
            "hasChargeHolds": true
        }
    }
}

In the BillingCenter user interface, this value appears on the account search page as a check box with the label Has Charge Holds. 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, hasChargeHolds is not used as a search parameter by default. If this field is not set in the request, both accounts with charge holds and without charge holds are returned. Therefore, you have the following options for this field:

  • Not set (null): Accounts with charge holds and without charge holds are returned
  • false: Only accounts without charge holds are returned
  • true: Only accounts with charge holds are returned

Searching with no search parameters

You can also search without including any criteria using an empty data wrapper. 

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

If there are more than 300 accounts to be returned, BillingCenter throws an error.

Response details

BillingCenter returns a list of accounts. The returned accounts do not necessarily contain the information sent as search parameters. For example, if searching by an account contact, BillingCenter does not return information about that account contact.

The following is an example of a request that returns one account:

Command 
POST /billing/v1/search/accounts

Request body

{
  "data": {
    "attributes": {
      "accountName": "johnson"
    }
  }
}

Response

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "accountName": "Johnson Metalworking",
                "accountNumber": "Johnson Metalworking",
                "accountType": {
                    "code": "insured",
                    "name": "Insured"
                },
                "billDateOrDueDateBilling": {
                    "code": "BillDateBilling",
                    "name": "Bill Date"
                },
                "billingLevel": {
                    "code": "Account",
                    "name": "Account/Default Unapplied"
                },
                "billingPlan": {
                    "displayName": "Test Billing Plan Weekly HMZIZR114",
                    "id": "bc:Stkyr0v0ygUQ6lUK1pJRL",
                    "type": "BillingPlan",
                    "uri": "/admin/v1/billing-plans/bc:Stkyr0v0ygUQ6lUK1pJRL"
                },
                "chargeHeld": false,
                "collecting": false,
                "createTime": "2025-12-25T15:30:21.923Z",
                "currency": {
                    "code": "usd",
                    "name": "USD"
                },
                "defaultPaymentInstrument": {
                    "displayName": "Responsive",
                    "id": "bc:SP2iQK__cfE73qBgpVVot",
                    "type": "UniversalPaymentInstrument",
                    "uri": "/billing/v1/universal-payment-instruments/bc:SP2iQK__cfE73qBgpVVot"
                },
                "defaultUnappliedFund": {
                    "displayName": "Default",
                    "id": "bc:SmxqFoUtn0MeM8gwwYE5l",
                    "type": "UnappliedFund",
                    "uri": "/billing/v1/accounts/bc:ShMMylkLxH997OdhJ6Atf/unapplied-funds/bc:SmxqFoUtn0MeM8gwwYE5l"
                },
                "delinquencyPlan": {
                    "displayName": "QA1DELINQUENCYPLAN07",
                    "id": "bc:SaQh7DjJXpGxEm3JKdBPM",
                    "type": "DelinquencyPlan",
                    "uri": "/admin/v1/delinquency-plans/bc:SaQh7DjJXpGxEm3JKdBPM"
                },
                "delinquencyStatus": {
                    "code": "InGoodStanding",
                    "name": "In Good Standing"
                },
                "everyOtherWeekInvoiceAnchorDate": "2025-12-25",
                "firstTwicePerMonthInvoiceDayOfMonth": 1,
                "heldForInvoiceSending": false,
                "id": "bc:ShMMylkLxH997OdhJ6Atf",
                "invoiceDayOfMonth": 15,
                "invoiceDayOfWeek": {
                    "code": "Friday",
                    "name": "Friday"
                },
                "newPolicyPaymentDistributable": true,
                "paymentAllocationPlan": {
                    "displayName": "Default Payment Allocation Plan",
                    "id": "cash_plan:1",
                    "type": "PaymentAllocationPlan",
                    "uri": "/admin/v1/payment-allocation-plans/cash_plan:1"
                },
                "secondTwicePerMonthInvoiceDayOfMonth": 15,
                "segment": {
                    "code": "mediumbusiness",
                    "name": "Medium Business"
                }
            },
            "checksum": "8",
            "links": {
                "issuance-preview": {
                    "href": "/billing/v1/accounts/bc:ShMMylkLxH997OdhJ6Atf/issuance-preview",
                    "methods": [
                        "post"
                    ]
                },
                "self": {
                    "href": "/billing/v1/accounts/bc:ShMMylkLxH997OdhJ6Atf",
                    "methods": [
                        "get",
                        "patch"
                    ]
                }
            }
        }
    ],
    "links": {
        "first": {
            "href": "/billing/v1/search/accounts",
            "methods": [
                "post"
            ]
        },
        "self": {
            "href": "/billing/v1/search/accounts",
            "methods": [
                "post"
            ]
        }
    }
}