--- title: "Batch merge profiles" method: POST path: "/people/3/persons/merge" tags: ["customer-engagement", "people", "person-profile"] --- # Batch merge profiles `POST /people/3/persons/merge` ## Request - Base URL: `https://api.infobip.com` (the document declares no server; this is the origin it was published from) - URL: `https://api.infobip.com/people/3/persons/merge` - Auth: one of: - OAuth 2 - Client credentials - Token URL: `https://api.infobip.com/auth/1/oauth2/token` - API key in header `Authorization` - API key in header `Authorization` - HTTP basic Use this method to merge multiple person profiles belonging to the same user based on matching identifiers such as external ID, email, phone, and other contact information. The standard merge logic applies: the system selects a primary profile and consolidates fields and events from the secondary profiles into it. More information about the merge logic is available in the [People documentation](https://www.infobip.com/docs/people/synchronize-your-audience#merge-duplicate).
Any data included in the merge request overrides what is already stored. If the request provides a new external ID or new contact information, it is written into the resulting profile, either replacing the existing identifier or being added to the contact list, depending on the type.
If the merge request includes only new identifiers or contact information that match no existing profile, the system creates a new profile and populates it entirely with the data from the request.
**Notes:**
1. The batch size limit is 1000 persons.
2. Contact information in the request is checked only for formal validity (emails and phone numbers). Ensure its correctness, alignment with configured senders, and absence of errors. ## Request body - 41037c0c5bdf4509c49aaf5c9a141a8857afc7b3859839aa4c690d84fb75d2e2MergeRequestDocsSchema - `persons` 41037c0c5bdf4509c49aaf5c9a141a8857afc7b3859839aa4c690d84fb75d2e2MergePersonV3DocsSchema[], required - `id` integer: Unique id of the entity. - `externalId` string: Unique ID for a person from your or another external system, 256 characters max. - `type` 'CUSTOMER' | 'LEAD': Person's type, default type is CUSTOMER. - `firstName` string: Person's first name, 255 characters max. - `middleName` string: Person's middle name, 50 characters max. - `lastName` string: Person's last name, 255 characters max. - `nickName` string: Person's nick name, 50 characters max. - `country` string: Person's country, 50 characters max. - `city` string: Person's city, 50 characters max. - `address` string: Person's address, 256 characters max. - `gender` 'MALE' | 'FEMALE': Person's gender. - `preferredLanguage` string: Person's preferred language. Must be in two letter ISO (xx) or language-region BCP-47 (xx-YY) format. - `birthDate` string, date: Person's date of birth, format `YYYY-MM-DD`. - `profilePicture` string, url: URL for the person's profile picture, 2083 characters max. - `tags` string[]: List of tags that this person has. - `contactInformation` 41037c0c5bdf4509c49aaf5c9a141a8857afc7b3859839aa4c690d84fb75d2e2MergeContactInformationV3DocsSchema[]: List of phones, emails and other information how a person can be contacted. - `type` 'PHONE' | 'EMAIL' | 'FACEBOOK' | 'LINE' | 'TELEGRAM' | 'PUSH' | 'WEB_PUSH' | 'LIVE_CHAT' | 'VIBER_BOTS' | 'INSTAGRAM' | 'TWITTER' | 'INSTAGRAM_DM' | 'KAKAO_SANGDAM' | 'APPLE_BUSINESS_CHAT' | 'OPEN_CHANNEL' | 'ZALO_FOLLOWER' | 'TIKTOK_BM' | 'WHATSAPP' | 'KAKAO_TALK': Type of the person ID. - `identifier` string: Person ID. ID type must match the type parameter. Some channels (e,g., Apple Business Chat) use identifiers that contain unsafe characters. Make sure you URL-encode them in your API request. 255 characters max. - `sender` string: Sender or application ID. Sender is required for all identifier types except PHONE and EMAIL. 255 characters max. - `primary` boolean: Indicates if this ID is preferred for communication. This flag only applies to PHONE and EMAIL. - `customAttributes` object: List of custom attributes for the person, 4096 characters max per value. - `computedAttributes` object: Person's computed attributes grouped by type. - `createdFrom` 'API' | 'PORTAL' | 'WEB_SDK' | 'INTEGRATION' | 'PUSH' | 'FACEBOOK' | 'LINE' | 'TELEGRAM' | 'SALESFORCE' | 'DYNAMICS' | 'ZAPIER' | 'FORMS' | 'AMS' | 'COMPUTED' | 'ANSWERS' | 'CONVERSATIONS' | 'IMPORT' | 'INSTAGRAM_DM' | 'FLOW' | 'LIVE_CHAT' | 'VKONTAKTE' | 'ZALO_FOLLOWER' | 'TIKTOK_BM' | 'WHATSAPP' | 'KAKAO_TALK' | 'UNKNOWN': Source system that last modified this person record. - `createdBy` string: Identifier of the user who created this person record. - `createdAt` string, date-time: Date and time of creation. Has the following format: yyyy-MM-dd'T'HH:mm:ss. - `modifiedFrom` 'API' | 'PORTAL' | 'WEB_SDK' | 'INTEGRATION' | 'PUSH' | 'FACEBOOK' | 'LINE' | 'TELEGRAM' | 'SALESFORCE' | 'DYNAMICS' | 'ZAPIER' | 'FORMS' | 'AMS' | 'COMPUTED' | 'ANSWERS' | 'CONVERSATIONS' | 'IMPORT' | 'INSTAGRAM_DM' | 'FLOW' | 'LIVE_CHAT' | 'VKONTAKTE' | 'ZALO_FOLLOWER' | 'TIKTOK_BM' | 'WHATSAPP' | 'KAKAO_TALK' | 'UNKNOWN': Source system that last modified this person record. - `modifiedBy` string: Identifier of the user who last modified this person record. - `modifiedAt` string, date-time: Date and time of last modification. Has the following format: yyyy-MM-dd'T'HH:mm:ss. ## Response `207` Multi-Status - Batch operation completed with individual results - object: Batch response for upsert operations - `errors` 41037c0c5bdf4509c49aaf5c9a141a8857afc7b3859839aa4c690d84fb75d2e2ErrorResponseV3: Error information for failed batch operation items. - `code` 400100 | 400101 | 400102 | 400103 | 400104 | 400105 | 400106 | 400107 | 404100 | 404101 | 405100 | 409100 | 500100, required: Error code identifying the type of error that occurred. - `message` string, required: Human-readable error message describing what went wrong. - `details` 41037c0c5bdf4509c49aaf5c9a141a8857afc7b3859839aa4c690d84fb75d2e2ErrorDetail[]: Additional validation error details with specific property-level information. - `property` string, required: Name of the property or field that caused the validation error. - `message` string, required: Specific error message describing the validation failure. - `payload` object: Additional context or metadata related to the validation error. - `index` integer: Index position of the failed item in the original request batch. - `results` 41037c0c5bdf4509c49aaf5c9a141a8857afc7b3859839aa4c690d84fb75d2e2MergeSuccessResult: Successful result for a person merge operation. - `id` integer, required: Unique identifier of the merged person profile. - `index` integer, required: Index position of this person in the original request batch. ## Other responses - `400`: Bad request - `401`: Unauthorized - `403`: Forbidden - `429`: Too Many Requests - `500`: Internal Server Error --- [API](https://skmtc.dev/infobip/apis/infobip-openapi-specification.md) - [All operations](https://skmtc.dev/infobip/apis/infobip-openapi-specification/llms.txt) - [OpenAPI document](https://skmtc.dev/infobip/apis/infobip-openapi-specification/revisions/9dcbbaf902de?raw)