Fetch Profiles (Bulk)

Share
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback

Overview

This API allows you to search and retrieve profile data from Data Cloud. You can fetch profiles based on various search criteria, such as profileId or specific attributes like FirstName.

Endpoint URL

The API endpoint where you send data is:

/cxs/profiles/search

HTTP Method

The method to be used for the request:

POST

Request Body Structure

To search for profile data, structure your request body as follows:

Example 1: The following example depicts a search by ProfileID.

{
    “limit”: 1,
    “condition”: {
        “type”: “booleanCondition”,
        “parameterValues”: {
            “operator”: “AND”,
            “subConditions”: [
                {
                    “type”: “profilePropertyCondition”,
                    “parameterValues”: {
                        “propertyName”: “itemId”,
                        “comparisonOperator”: “in”,
                        “propertyValues”: [
                            “9354e371-e5ce-4bee-bed7-20755967ad2b”,
                            “cee89ee3-e6f9-49ca-bec4-68df14e989cf”
                        ]
                    }
                }
            ]
        }
    }
}

Sample:

{
    "limit": 1,
    "condition": {
        "type": "booleanCondition",
        "parameterValues": {
            "operator": "AND",
            "subConditions": [
                {
                    "type": "profilePropertyCondition",
                    "parameterValues": {
                        "propertyName": "properties.PhoneNumbers",
                        "comparisonOperator": "equals",
                        "propertyValue": "+12198471542"
                    }
                }
            ]
        }
    }
}

{
    "limit": 1,
    "condition": {
        "type": "booleanCondition",
        "parameterValues": {
            "operator": "AND",
            "subConditions": [
                {
                    "type": "profilePropertyCondition",
                    "parameterValues": {
                        "propertyName": "properties.Emails",
                        "comparisonOperator": "equals",
                        "propertyValue": "joe.jacobs@adams.com"
                    }
                }
            ]
        }
    }
}

Example 2: The following example depicts a search by FirstName.

{
    "limit": 1,
    "condition": {
        "type": "booleanCondition",
        "parameterValues": {
            "operator": "AND",
            "subConditions": [
                {
                    "type": "profilePropertyCondition",
                    "parameterValues": {
                        "propertyName": "properties.FirstName.keyword",
                        "comparisonOperator": "equals",
                        "propertyValue": "Joe"
                    }
                }
            ]
        }
    }
}

Request Field Description

This table outlines the required fields for the API request, including their types, whether they are mandatory, and their descriptions.

Field Name	Data Type	Required	Description
Limit	Integer	Yes	Specifies the maximum number of records per API request.
Type	String	Yes	Should always be profilePropertyCondition
parameterValues	String	Yes	Specifies the condition for a profile property, such as a comparison or logical operation, depending on the context in which it is used.
Operator	String	Yes	Logical operator: either “and” or “or.”
parameterValues	String	Yes	Defines a condition used to construct the query and retrieve the corresponding records. This condition is formed by combining three elements: propertyName: Specifies the property being queried. For example, systemProperties.CreatedTimestamp refers to the creation timestamp stored in the system metadata. comparisonOperator: Indicates the condition to filter data. Operators like lessThan, greaterThan, or equals are used to define the filtering criteria. propertyValue: Provides the timestamp for comparison in ISO 8601 format. In this case, it represents the timestamp to which the CreatedTimestamp is compared.

Sample Response

{
    “list”: [
        {
            “itemId”: “9354e371-e5ce-4bee-bed7-20755967ad2b”,
            “itemType”: “profile”,
            “scope”: “1-1”,
            “version”: 1,
            “objectType”: null,
            “properties”: {
                “Age”: 54,
                “ContactID”: “003GA000044SR2RYAW”,
                “Email”: “joesmith@acqueon.com”,
                “Emails”: [
                    “joesmith@acqueon.com”
                ],
                “FirstName”: “Joe”,
                “Home”: “18287716924”,
                “LastName”: “Smith”,
                “Mobile”: “18287716924”,
                “Office”: “18287716924”,
                “PhoneNumbers”: [
                    “18287716924”
                ],
                “Primary”: “0017F00000nqkLTQAY”
            },
            “systemProperties”: {
                “ProfileCreatedTimestamp”: “2024-10-16T16:53:31Z”,
                “ProfileUpdatedTimestamp”: “2024-10-16T16:53:31Z”
            },
            “segments”: [],
            “scores”: null
        }
    ],
    “offset”: 0,
    “pageSize”: 1,
    “totalSize”: 1,
    “totalSizeRelation”: “EQUAL”,
    “scrollIdentifier”: null,
    “scrollTimeValidity”: null,
    “sort”: [
        “9354e371-e5ce-4bee-bed7-20755967ad2b”
    ]
}

Note:
In the response, all date-time values are converted based on the time zone configured on the Global Settings page. If the configured time zone is updated, the change is reflected in API responses after approximately 10 minutes.

Response Field Description

This table outlines the response fields for the API request, including their types, whether they are, and their descriptions.

Field Name	Data Type	Description
ItemId	String	Specifies the Profile ID.
itemType	String	Specifies the type of item. In this case, it is Profile.
Scope	String	Specifies the tenant to which the operation applies.
Version	String	Specifies the version of the document.
objectType		Null
Properties	String	Represents key details about a profile, such as age, unique identifiers, and contact information.
systemProperties	Object	Specifies these system properties: CreatedTimestamp -The date and time when the record or interaction was first created in the system UpdatedTimestamp – The date and time when the record or interaction was last modified or updated in the system.
Offset	Integer	Specifies the number of records skipped in the query result. It is the same value as sent in the query and defaults to 0 if not specified.
pageSize	Integer	Defines the number of records returned in the current response.
totalSize	Integer	Represents the total number of records that match the query criteria.
totalSizeRelation	String	Represents the relationship of the total size in the query. The value can be either “EQUAL” or “GREATER_THAN_OR_EQUAL TO”, indicating whether the total size is exactly equal to or greater than the total number of matching records.

Limit

The following table outlines the limit and how child entities are handled for the Data Ingestion API.

Parameter	Limit	Notes
Maximum response size	10 MB or 10,000 records	Responses include up to 10,000 profiles or a total size of 10MB, whichever is reached first. If the 10MB limit is reached, the number of profiles is reduced to stay within this size.

Error Response

The following table outlines the error responses for the API with descriptions.

Error Response	Description
401 – Unauthorized	Indicates that the authentication token provided is either invalid or has expired.
405 – Method not allowed	Indicates that the HTTP method used in the request is not allowed for the specified resource.
400 -Bad Request	The input format is incorrect. Refer to the documentation for the correct format.

To know how pagination is handled for these API responses, refer here.

Was this article helpful?

What's Next

Create Attributes (Bulk) - Submit

Table of contents

Overview
Endpoint URL
HTTP Method
Request Body Structure
Request Field Description
Sample Response
Response Field Description
Limit
Error Response