# Batch add or update profiles - Operation ID: `BatchAddOrUpdateClients` - HTTP method: `POST` - Path: `/v4/clients/batch` - [Human-readable API reference](https://hub.synerise.com/api-reference/data-management#tag/Profile-management/operation/BatchAddOrUpdateClients) ## 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: post: summary: Batch add or update profiles description: |2 Enqueue a number of add/update operations in the Synerise application database.

If you don't have some information about a profile, don't insert a null-value parameter - omit the parameter entirely. Sending a null value deletes an attribute (if it's a custom attribute) or sets it to null/default value (if the attribute is Synerise-native). The body contains an array of objects to update. The objects are the same as in the *Create a Profile* and *Update a Profile* endpoints. IMPORTANT: The request body cannot contain more than 1000 items or exceed 1 MB in size. This is an asynchronous operation. After the request body is validated, the request is added to the queue (HTTP 202). --- **API consumers:** Synerise User, Workspace (Business Profile) **API key permission required:** `API_BATCH_CLIENT_CREATE` **User role permission required:** `client_management: create` operationId: BatchAddOrUpdateClients parameters: - name: Accept 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" requestBody: description: | Each profile must have at least one of the following identifiers: - `email` If [non-unique emails](https://hub.synerise.com/docs/settings/configuration/non-unique-emails/) are enabled, email is NOT an identifier. - `phone` Phone number is treated as an identifier only if no other identifier is provided. Then, if a profile with this phone number does not exist and non-unique emails are disabled, an anonymous profile is created. - `customId` - `uuid` - `clientId` (can be used only when updating an existing profile) content: application/json: schema: type: array minItems: 1 maxItems: 1000 items: type: object properties: clientId: type: integer format: int64 description: | This ID can be used only for updating an existing profile. If a profile does not exist and `clientId` is the only provided identifier, the operation returns HTTP 202 and **a profile is not created**. If another identifier is provided, a profile is created with that identifier and a `clientId` generated by the system. allOf: - type: object properties: 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/). 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 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 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`) 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 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`) 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`) 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`) 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`) 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`) countryCode: type: string description: Code of profile's country of residence in accordance with the ISO 3166 format example: PL sex: type: string description: Profile's sex enum: - FEMALE - MALE - NOT_SPECIFIED - OTHER 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 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`) required: true responses: "202": description: "Request accepted. IMPORTANT: this does not mean that all profiles were created/updated successfully. The data is sent for further processing in other elements of the infrastructure." "207": description: Invalid data in some entries. Correct entries are sent for further processing, the invalid ones are rejected. content: application/json: schema: type: array 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: - rejectedValue: de73b3490c4-bb8c0d8 field: list[0].uuid status: 400 message: UUID must be well-formed value as per RFC 4122 "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 "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/BatchAddOrUpdateClients x-codeSamples: - lang: cURL label: cURL source: |- curl --request POST \ --url https://api.synerise.com/v4/clients/batch \ --header 'Accept: SOME_STRING_VALUE' \ --header 'Api-Version: SOME_STRING_VALUE' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'content-type: application/json' \ --data '[{"clientId":0,"email":"string","phone":"+48111222333","customId":"string","firstName":"string","lastName":"string","displayName":"string","uuid":"07243772-008a-42e1-ba37-c3807cebde8f","avatarUrl":"string","birthDate":"1987-10-24","company":"string","city":"string","address":"string","zipCode":"string","province":"string","countryCode":"PL","sex":"FEMALE","whatsAppId":"TestWhatsappId","agreements":{"email":false,"sms":false,"push":false,"webPush":false,"whatsApp":false,"bluetooth":false,"rfid":false,"wifi":false},"attributes":{"property1":null,"property2":null},"tags":["string"]}]' - lang: Python label: Python source: |- import http.client conn = http.client.HTTPSConnection("api.synerise.com") payload = "[{\"clientId\":0,\"email\":\"string\",\"phone\":\"+48111222333\",\"customId\":\"string\",\"firstName\":\"string\",\"lastName\":\"string\",\"displayName\":\"string\",\"uuid\":\"07243772-008a-42e1-ba37-c3807cebde8f\",\"avatarUrl\":\"string\",\"birthDate\":\"1987-10-24\",\"company\":\"string\",\"city\":\"string\",\"address\":\"string\",\"zipCode\":\"string\",\"province\":\"string\",\"countryCode\":\"PL\",\"sex\":\"FEMALE\",\"whatsAppId\":\"TestWhatsappId\",\"agreements\":{\"email\":false,\"sms\":false,\"push\":false,\"webPush\":false,\"whatsApp\":false,\"bluetooth\":false,\"rfid\":false,\"wifi\":false},\"attributes\":{\"property1\":null,\"property2\":null},\"tags\":[\"string\"]}]" headers = { 'Accept': "SOME_STRING_VALUE", 'Api-Version': "SOME_STRING_VALUE", 'Authorization': "Bearer REPLACE_BEARER_TOKEN", 'content-type': "application/json" } conn.request("POST", "/v4/clients/batch", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) - lang: JavaScript label: JavaScript source: |- const data = JSON.stringify([ { "clientId": 0, "email": "string", "phone": "+48111222333", "customId": "string", "firstName": "string", "lastName": "string", "displayName": "string", "uuid": "07243772-008a-42e1-ba37-c3807cebde8f", "avatarUrl": "string", "birthDate": "1987-10-24", "company": "string", "city": "string", "address": "string", "zipCode": "string", "province": "string", "countryCode": "PL", "sex": "FEMALE", "whatsAppId": "TestWhatsappId", "agreements": { "email": false, "sms": false, "push": false, "webPush": false, "whatsApp": false, "bluetooth": false, "rfid": false, "wifi": false }, "attributes": { "property1": null, "property2": null }, "tags": [ "string" ] } ]); const xhr = new XMLHttpRequest(); xhr.withCredentials = true; xhr.addEventListener("readystatechange", function () { if (this.readyState === this.DONE) { console.log(this.responseText); } }); xhr.open("POST", "https://api.synerise.com/v4/clients/batch"); xhr.setRequestHeader("Accept", "SOME_STRING_VALUE"); xhr.setRequestHeader("Api-Version", "SOME_STRING_VALUE"); xhr.setRequestHeader("Authorization", "Bearer REPLACE_BEARER_TOKEN"); xhr.setRequestHeader("content-type", "application/json"); xhr.send(data); - lang: Node.js label: Node.js source: |- const http = require("https"); const options = { "method": "POST", "hostname": "api.synerise.com", "port": null, "path": "/v4/clients/batch", "headers": { "Accept": "SOME_STRING_VALUE", "Api-Version": "SOME_STRING_VALUE", "Authorization": "Bearer REPLACE_BEARER_TOKEN", "content-type": "application/json" } }; 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.write(JSON.stringify([ { clientId: 0, email: 'string', phone: '+48111222333', customId: 'string', firstName: 'string', lastName: 'string', displayName: 'string', uuid: '07243772-008a-42e1-ba37-c3807cebde8f', avatarUrl: 'string', birthDate: '1987-10-24', company: 'string', city: 'string', address: 'string', zipCode: 'string', province: 'string', countryCode: 'PL', sex: 'FEMALE', whatsAppId: 'TestWhatsappId', agreements: { email: false, sms: false, push: false, webPush: false, whatsApp: false, bluetooth: false, rfid: false, wifi: false }, attributes: {property1: null, property2: null}, tags: ['string'] } ])); req.end(); - lang: PHP label: PHP source: |- setUrl('https://api.synerise.com/v4/clients/batch'); $request->setMethod(HTTP_METH_POST); $request->setHeaders([ 'Accept' => 'SOME_STRING_VALUE', 'Api-Version' => 'SOME_STRING_VALUE', 'Authorization' => 'Bearer REPLACE_BEARER_TOKEN', 'content-type' => 'application/json' ]); $request->setBody('[{"clientId":0,"email":"string","phone":"+48111222333","customId":"string","firstName":"string","lastName":"string","displayName":"string","uuid":"07243772-008a-42e1-ba37-c3807cebde8f","avatarUrl":"string","birthDate":"1987-10-24","company":"string","city":"string","address":"string","zipCode":"string","province":"string","countryCode":"PL","sex":"FEMALE","whatsAppId":"TestWhatsappId","agreements":{"email":false,"sms":false,"push":false,"webPush":false,"whatsApp":false,"bluetooth":false,"rfid":false,"wifi":false},"attributes":{"property1":null,"property2":null},"tags":["string"]}]'); try { $response = $request->send(); echo $response->getBody(); } catch (HttpException $ex) { echo $ex; } - lang: Java label: Java source: |- HttpResponse response = Unirest.post("https://api.synerise.com/v4/clients/batch") .header("Accept", "SOME_STRING_VALUE") .header("Api-Version", "SOME_STRING_VALUE") .header("Authorization", "Bearer REPLACE_BEARER_TOKEN") .header("content-type", "application/json") .body("[{\"clientId\":0,\"email\":\"string\",\"phone\":\"+48111222333\",\"customId\":\"string\",\"firstName\":\"string\",\"lastName\":\"string\",\"displayName\":\"string\",\"uuid\":\"07243772-008a-42e1-ba37-c3807cebde8f\",\"avatarUrl\":\"string\",\"birthDate\":\"1987-10-24\",\"company\":\"string\",\"city\":\"string\",\"address\":\"string\",\"zipCode\":\"string\",\"province\":\"string\",\"countryCode\":\"PL\",\"sex\":\"FEMALE\",\"whatsAppId\":\"TestWhatsappId\",\"agreements\":{\"email\":false,\"sms\":false,\"push\":false,\"webPush\":false,\"whatsApp\":false,\"bluetooth\":false,\"rfid\":false,\"wifi\":false},\"attributes\":{\"property1\":null,\"property2\":null},\"tags\":[\"string\"]}]") .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. ```