POST /contacts/v1/addresses/count

Retrieve the number of contacts who meet a set of search criteria.

Properties

The JSON request body contains this property.

Name	Type	Description
`queryFilter`	Object	Required. An object that defines the criteria to search for.

queryFilter Object

The queryFilter object has the properties described in this table.

Name	Type	Description
`hasCriteria`	Boolean	Required. Indicates whether the filter specifies search criteria. If the value is `false`, the response contains a count of all contacts in the account.
`rootExpressionSet`	Object	An object that contains the filter expressions.

rootExpressionSet Object

The rootExpressionSet object has the properties described in this table.

Name	Type	Description
`expressions`	Array	An array of objects that define the search criteria. This resource supports only one expression.

expressions Object

The object in the expressions array has the properties described in this table.

Name	Type	Description
`customerDataDefinitionID`	Short	An integer that represents the attribute type to use in the filter. Possible values: `101`: ContactKey `102`: LastModfiedDate `103`: Source `104`: Channel `105`: Status `106`: AudienceID
`operator`	String	The condition operator to use in the filter. The only possible value is `Equal`.
`values`	Array	An array of strings that define the values to filter results by. If the value of `CustomerDataDefinitionID` is `104`, these values are supported `MOBILE` `PUSH` `LINE` `EMAIL`

Response Properties

A successful request returns a 200 OK result. The response contains the properties in this table.

Name	Type	Description
`requestServiceMessageID`	String	A unique ID for the request.
`responseDateTime`	Datetime	The date and time when the API generated the response.
`resultMessages`	Array	An array of objects that contains messages generated while processing the request. The array is typically empty in a successful request.
`serviceMessageID`	String	A unique ID for the response.
`totalCount`	Integer	The number of contacts that meet the search criteria.

If an error occurs while processing the request, the response contains an additional property, hasErrors, with a value of true. In this situation, the objects in the resultMessages have the properties listed in this table.

Name	Type	Description
`resultClass`	String	A description of the result. If an error occurs, the value is `Error`.
`resultCode`	String	An error code.
`message`	String	A message that explains the error that occurred.
`resultType`	String	A description of the type of result.

Usage

You can use this resource to obtain a count of contacts with or without providing a filter.

Obtain a Count without a Filter

To retrieve the number of contacts without specifying a filter, set the value of queryFilter.hasCriteria to false. You can also omit the rootExpressionSet object from the request.

1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /contacts/v1/addresses/count
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7  "queryFilter": {
8    "hasCriteria": false
9  }
10}

The response contains the total number of contacts in the account.

1{
2  "totalCount": 1015,
3  "requestServiceMessageID": "b887c721-0610-4869-93b3-44430a4090af",
4  "responseDateTime": "2025-06-13T14:15:31.6733217-06:00",
5  "resultMessages": [],
6  "serviceMessageID": "568f95d3-570b-4a01-9565-8bef4553c79e"
7}

Obtain a Count with a Filter

This request returns the number of contacts who have a Channel attribute of Push. The value of customerDataDefinitionID (104) indicates that the results are filtered by the Channel attribute.

1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /contacts/v1/addresses/count
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7  "queryFilter": {
8    "hasCriteria": true,
9    "rootExpressionSet": {
10      "expressions": [
11        {
12          "customerDataDefinitionID": 104,
13          "operator": "Equal",
14          "values": [
15            "Push"
16          ]
17        }
18      ]
19    }
20  }
21}

The response indicates the number of contacts that meet the filter criteria.

1{
2  "totalCount": 1003,
3  "requestServiceMessageID": "4133c2b6-4eb2-49ca-84b1-5e9cee84e671",
4  "responseDateTime": "2025-06-13T14:20:40.962761-06:00",
5  "resultMessages": [],
6  "serviceMessageID": "321c5776-1050-40c8-a42a-b5f753be56f7"
7}

DID THIS ARTICLE SOLVE YOUR ISSUE?
Let us know so we can improve!