---
title: "Batch full people upsert"
method: PUT
path: "/people/3/persons/upsert"
tags: ["customer-engagement", "people", "person-profile"]
---

# Batch full people upsert

`PUT /people/3/persons/upsert`

## 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/upsert`
- 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 create or fully replace person profiles by matching on identifiers such as external ID, email, or phone. If a match is identified, the existing profile is entirely replaced with the provided data; any fields excluded from the request will be cleared. If no match is identified, a new profile is created. The operation returns a status for each profile: CREATED, UPDATED, or NOT_MODIFIED.<br>**Notes:** <br>1. The batch size limit is 1000 persons. <br>2. Contact information (emails and phone numbers) in the request is checked only for formal validity. Ensure accuracy and absence of errors.

## Request body

- 41037c0c5bdf4509c49aaf5c9a141a8857afc7b3859839aa4c690d84fb75d2e2UpsertRequestDocsSchema
  - `persons` 41037c0c5bdf4509c49aaf5c9a141a8857afc7b3859839aa4c690d84fb75d2e2UpsertPersonV3DocsSchema[], 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` 41037c0c5bdf4509c49aaf5c9a141a8857afc7b3859839aa4c690d84fb75d2e2UpsertContactInformationV3DocsSchema[]: List of phones, emails and other information how a person can be contacted.
      - `type` 'PHONE' | 'EMAIL': 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.
    - `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` 41037c0c5bdf4509c49aaf5c9a141a8857afc7b3859839aa4c690d84fb75d2e2UpsertSuccessResult: Successful result for a person upsert operation.
    - `id` integer, required: Unique identifier of the upserted person profile.
    - `index` integer, required: Index position of this person in the original request batch.
    - `status` 'CREATED' | 'UPDATED' | 'NOT_MODIFIED': Status indicating the type of operation performed on a person profile during upsert

## 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)