# Batch fetch profiles by phone number - Operation ID: `FindClientsByPhone` - HTTP method: `GET` - Path: `/v4/clients/batch/by-phone/{phoneNumber}` - [Human-readable API reference](https://hub.synerise.com/api-reference/data-management#tag/Profile-management/operation/FindClientsByPhone) ## Self-contained OpenAPI method The fenced document below contains this method's documentation and all of its local references. It is self-contained; no category or master specification fetch is required. ```yaml openapi: 3.0.0 info: title: Synerise Public API version: 1.9.1 paths: /v4/clients/batch/by-phone/{phoneNumber}: get: summary: Batch fetch profiles by phone number description: |2 Returns a detailed list of profiles associated with the provided phone number. The number saved in the profile must exactly match the number from the request. If no profiles match the criteria, an empty list is returned. --- **API consumers:** Synerise User, Workspace (Business Profile) **API key permission required:** `API_BY_IDENTIFIER_CLIENT_READ` **User role permission required:** `client_info: read` operationId: FindClientsByPhone parameters: - name: phoneNumber in: path description: | The phone number to search for in profiles. Must be an exact match. The value must be URL-encoded. **Upcoming breaking change (effective July 6, 2026):** Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see [Upcoming changes to identifier and UUID handling](https://hub.synerise.com/docs/settings/configuration/identifier-standardization/). required: true schema: type: string example: 12065550100 - name: Content-Type in: header required: true style: simple explode: false schema: type: string enum: - application/json - name: Api-Version in: header required: true style: simple explode: false schema: type: string enum: - "4.4" responses: "200": description: Returns an array of profile details. content: application/json: schema: type: array items: type: object properties: clientId: description: | Unique ID. This ID is generated by the system during profile creation. **Upcoming breaking change (effective July 6, 2026):** Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see [Upcoming changes to identifier and UUID handling](https://hub.synerise.com/docs/settings/configuration/identifier-standardization/). type: integer format: int64 example: 433230297 email: type: string description: | The profile's e-mail address. - Must match the pattern (ECMA flavor): `/^(([^<>()[\]\\.,;:\s@\\"]+(\.[^<>()[\]\\.,;:\s@\\"]+)*)|(\\".+\\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/` - The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])|([\r\n\u2028\u2029\u00AD]|[\uFE00-\uFE0F]|[\u0000])/` By default, email is a unique identifier. If [non-unique emails](https://hub.synerise.com/docs/settings/configuration/non-unique-emails/) are enabled, this field should not be used. It is no longer an identifier. The configuration of non-unique emails includes creating an email parameter for communication. **Upcoming breaking change (effective July 6, 2026):** Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see [Upcoming changes to identifier and UUID handling](https://hub.synerise.com/docs/settings/configuration/identifier-standardization/). phone: type: string description: | Phone number of the profile - Must match the pattern (ECMA flavor): `/(^\+[0-9 \-()/]{6,19}$)|(^[0-9 \-()/]{6,20}$)/` - The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])|([\r\n\u2028\u2029\u00AD]|[\uFE00-\uFE0F]|[\u0000])/` **Upcoming breaking change (effective July 6, 2026):** Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see [Upcoming changes to identifier and UUID handling](https://hub.synerise.com/docs/settings/configuration/identifier-standardization/). example: "+48111222333" customId: type: string description: | A custom ID for the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])|([\r\n\u2028\u2029\u00AD]|[\uFE00-\uFE0F]|[\u0000])/` **Upcoming breaking change (effective July 6, 2026):** Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see [Upcoming changes to identifier and UUID handling](https://hub.synerise.com/docs/settings/configuration/identifier-standardization/). uuid: type: string description: | UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])|([\r\n\u2028\u2029\u00AD]|[\uFE00-\uFE0F]|[\u0000])/` **Upcoming breaking change (effective July 6, 2026):** Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see [Upcoming changes to identifier and UUID handling](https://hub.synerise.com/docs/settings/configuration/identifier-standardization/). example: 07243772-008a-42e1-ba37-c3807cebde8f firstName: type: string description: | Profile's first name. The value: - can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. - can't include the "null" control character (`\u0000`) lastName: type: string description: | Profile's last name The value: - can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. - can't include the "null" control character (`\u0000`) displayName: type: string description: Currently unused company: type: string description: | Profiles's company The value: - can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. - can't include the "null" control character (`\u0000`) address: type: string description: | Profile's street address. The value: - can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. - can't include the "null" control character (`\u0000`) city: type: string description: | Profile's city of residence. The value: - can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. - can't include the "null" control character (`\u0000`) province: type: string description: | Profile's province of residence The value: - can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. - can't include the "null" control character (`\u0000`) zipCode: type: string description: | Profile's zip code The value: - can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. - can't include the "null" control character (`\u0000`) countryCode: type: string description: Code of profile's country of residence in accordance with the ISO 3166 format example: PL birthDate: type: string description: "Date of birth in the profile. Must be in `yyyy-mm-dd` format and later than `1900-01-01`. Must be a date in the past.
**IMPORTANT**: Months and days must be zero-padded. For example: May 3, 1993 is `1993-05-03`." example: 1987-10-24 sex: type: string description: Profile's sex enum: - FEMALE - MALE - NOT_SPECIFIED - OTHER avatarUrl: type: string nullable: true description: | URL of the profile's avatar picture The value: - can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. - can't include the "null" control character (`\u0000`) whatsAppId: type: string nullable: true description: | WhatsApp identifier of the profile, used for WhatsApp communication. The value: - can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. - can't include the "null" control character (`\u0000`) example: TestWhatsappId anonymous: description: Information if the profile is anonymous type: boolean example: false agreements: description: |- This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false). type: object properties: email: type: boolean description: Permission to receive marketing information by e-mail. This field has no effect if [email is not a unique identifier](https://hub.synerise.com/docs/settings/configuration/non-unique-emails/). default: false sms: type: boolean description: Permission to receive marketing information by SMS default: false push: type: boolean description: Permission to receive push notifications default: false webPush: type: boolean description: Permission to receive webpush notifications default: false whatsApp: type: boolean description: Permission to receive marketing information via WhatsApp default: false bluetooth: type: boolean deprecated: true description: This field is ignored when sent. default: false rfid: type: boolean deprecated: true description: This field is ignored when sent. default: false wifi: type: boolean deprecated: true description: This field is ignored when sent. default: false attributes: type: object description: | This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: - can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. - can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: - The date/time should be formatted according to ISO 8601. - The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: - `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. - `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. - `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes cannot be sent in this object and will be ignored. Some of these are reserved for system use, and others must be sent as properties of the profile in the root object of the request body instead of inside the `attributes` object.
Click to expand the list of reserved attributes email
id
clientId
phone
customId
uuid
firstName
lastName
displayName
company
address
city
province
zipCode
countryCode
birthDate
sex
avatarUrl
anonymous
agreements
tags
businessProfileId
time
ip
source
newsletter_agreement
custom_identify
firstname
lastname
created
updated
last_activity_date
birthdate
external_avatar_url
displayname
receive_smses
receive_push_messages
receive_webpush_messages
receive_whatsapp_messages
whatsAppId
whatsapp_id
receive_btooth_messages
receive_rfid_messages
receive_wifi_messages
zipCode
anonymous_type
country_id
geo_loc_country
geo_loc_isp
geo_loc_lat
geo_loc_lon
club_card_id
type
confirmed
facebookId
deletedAt
deleted_unique
status
recognized
previous_clients
testProfile
apikey
apiKey
ApiKey
Apikey
tracker
snr_sdk_version
eventCreateTime
correlationId
additionalProperties: description: | The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: - can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. - can't include the "null" control character (`\u0000`) tags: type: array description: | Tags can be used to group profiles. Tag names (strings): - can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. - can't include the "null" control character (`\u0000`) items: type: string description: | Tag names (strings): - can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. - can't include the "null" control character (`\u0000`) previousClients: type: array description: | - When retrieving profile data, this field is always empty. - In the response after a profile merge, the format depends on the merge type. This field only provides information about the last merge. If a profile in the last merge was the result of another merge in the past, the data of the previous merge isn't included. items: oneOf: - type: integer title: Merged by ID description: IDs of the profiles which were merged into the target profile - type: object title: Merged by customId description: Profiles which were merged into the target profile properties: customId: type: string description: customId of a profile merged into the target profile lastActivityDate: deprecated: true type: string example: 2019-03-19T14:05:39Z description: "**Don't use** the values from this field. The last activity calculation mechanism is disabled and the value is always the profile's creation date. The field will be removed in a future release." "400": description: Bad Request content: application/json: schema: type: object properties: error: type: string description: Summary of the error status: type: integer format: int32 description: Status code timestamp: type: string description: Time when the message was sent path: type: string description: URL of the requested resource message: type: string description: Description of the problem errors: type: array description: Additional details of the errors, if applicable items: type: object properties: code: type: integer format: int32 example: 12082 description: A numeric identifier of the error type field: type: string example: countryCode description: Field in the request body that caused the error message: type: string example: Country Code must have 0 or 3 characters as per ISO format. description: A detailed description of the problem rejectedValue: type: string example: Poland description: The value that caused the error example: path: /clients/by-phone/+12065550100/batch message: Api-Version header is required error: Bad Request timestamp: 2018-06-07T09:33:59.183Z status: 400 "401": description: "Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc." content: application/json: schema: type: object properties: error: type: string description: Summary of the error status: type: integer format: int32 description: Status code timestamp: type: string description: Time when the message was sent path: type: string description: URL of the requested resource message: type: string description: Description of the problem errors: type: array description: Additional details of the errors, if applicable items: type: object properties: code: type: integer format: int32 example: 12082 description: A numeric identifier of the error type field: type: string example: countryCode description: Field in the request body that caused the error message: type: string example: Country Code must have 0 or 3 characters as per ISO format. description: A detailed description of the problem rejectedValue: type: string example: Poland description: The value that caused the error example: error: Bad Request status: 400 timestamp: 2020-10-29T13:08:16.235Z path: /exampleEndpoint message: Some fields did not pass validation errors: - code: 120 field: exampleField message: "120" rejectedValue: exampleValue "403": description: Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description) content: application/json: schema: type: object properties: error: type: string description: Summary of the error status: type: integer format: int32 description: Status code timestamp: type: string description: Time when the message was sent path: type: string description: URL of the requested resource message: type: string description: Description of the problem errors: type: array description: Additional details of the errors, if applicable items: type: object properties: code: type: integer format: int32 example: 12082 description: A numeric identifier of the error type field: type: string example: countryCode description: Field in the request body that caused the error message: type: string example: Country Code must have 0 or 3 characters as per ISO format. description: A detailed description of the problem rejectedValue: type: string example: Poland description: The value that caused the error example: timestamp: 2018-06-07T07:29:27.489+00:00 status: 403 error: Forbidden message: Forbidden path: /path_of_the_endpoint "404": description: Profile not found or access blocked by PII protection settings content: application/json: schema: type: string description: Description of the problem. If the access is blocked by insufficient PII permissions, the message is the same as when the profile doesn't exist. example: Client 5005535044 not found "415": description: Unsupported Media Type content: application/json: schema: type: object properties: error: type: string description: Summary of the error status: type: integer format: int32 description: Status code timestamp: type: string description: Time when the message was sent path: type: string description: URL of the requested resource message: type: string description: Description of the problem errors: type: array description: Additional details of the errors, if applicable items: type: object properties: code: type: integer format: int32 example: 12082 description: A numeric identifier of the error type field: type: string example: countryCode description: Field in the request body that caused the error message: type: string example: Country Code must have 0 or 3 characters as per ISO format. description: A detailed description of the problem rejectedValue: type: string example: Poland description: The value that caused the error example: timestamp: 2018-06-07T07:27:23.136+00:00 status: 415 error: Unsupported Media Type message: Content type 'application/xml' not supported path: /path_of_the_endpoint deprecated: false security: - JWT: [] tags: - Profile management x-snr-doc-urls: - /api-reference/data-management#tag/Profile-management/operation/FindClientsByPhone x-codeSamples: - lang: cURL label: cURL source: |- curl --request GET \ --url https://api.synerise.com/v4/clients/batch/by-phone/12065550100 \ --header 'Api-Version: SOME_STRING_VALUE' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'Content-Type: SOME_STRING_VALUE' - lang: Python label: Python source: |- import http.client conn = http.client.HTTPSConnection("api.synerise.com") headers = { 'Content-Type': "SOME_STRING_VALUE", 'Api-Version': "SOME_STRING_VALUE", 'Authorization': "Bearer REPLACE_BEARER_TOKEN" } conn.request("GET", "/v4/clients/batch/by-phone/12065550100", headers=headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) - lang: JavaScript label: JavaScript source: |- const data = null; const xhr = new XMLHttpRequest(); xhr.withCredentials = true; xhr.addEventListener("readystatechange", function () { if (this.readyState === this.DONE) { console.log(this.responseText); } }); xhr.open("GET", "https://api.synerise.com/v4/clients/batch/by-phone/12065550100"); xhr.setRequestHeader("Content-Type", "SOME_STRING_VALUE"); xhr.setRequestHeader("Api-Version", "SOME_STRING_VALUE"); xhr.setRequestHeader("Authorization", "Bearer REPLACE_BEARER_TOKEN"); xhr.send(data); - lang: Node.js label: Node.js source: |- const http = require("https"); const options = { "method": "GET", "hostname": "api.synerise.com", "port": null, "path": "/v4/clients/batch/by-phone/12065550100", "headers": { "Content-Type": "SOME_STRING_VALUE", "Api-Version": "SOME_STRING_VALUE", "Authorization": "Bearer REPLACE_BEARER_TOKEN" } }; const req = http.request(options, function (res) { const chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { const body = Buffer.concat(chunks); console.log(body.toString()); }); }); req.end(); - lang: PHP label: PHP source: |- setUrl('https://api.synerise.com/v4/clients/batch/by-phone/12065550100'); $request->setMethod(HTTP_METH_GET); $request->setHeaders([ 'Content-Type' => 'SOME_STRING_VALUE', 'Api-Version' => 'SOME_STRING_VALUE', 'Authorization' => 'Bearer REPLACE_BEARER_TOKEN' ]); try { $response = $request->send(); echo $response->getBody(); } catch (HttpException $ex) { echo $ex; } - lang: Java label: Java source: |- HttpResponse response = Unirest.get("https://api.synerise.com/v4/clients/batch/by-phone/12065550100") .header("Content-Type", "SOME_STRING_VALUE") .header("Api-Version", "SOME_STRING_VALUE") .header("Authorization", "Bearer REPLACE_BEARER_TOKEN") .asString(); servers: - description: Microsoft Azure EU url: https://api.synerise.com - description: Microsoft Azure USA url: https://api.azu.synerise.com - description: Google Cloud Platform url: https://api.geb.synerise.com tags: - name: Profile management components: securitySchemes: JWT: type: http scheme: bearer description: |- JWT Bearer token. The header looks like this: `Bearer {JWT}` Remember to include the space between 'Bearer' and the token. Generate a token via the **Authorization** endpoints. ```