Person Profile

A person represents your end user's unique profile

Person Profile

Build rich profiles for each person to be able to create audience segments for more precise targeting. A person consists of the following information:

Standard Attributes: 
List of fields is predefined and can be only set by API and Portal users.
Example: First Name, Last Name, Gender, Birthday, Address, External ID

Custom Attributes:
Custom Attributes can be configured per account and will be visible for each person - attributes can be set, get and named by their specific name. Can be used to additionally describe the person and their behavior. 
Example: Contract Expiry Date, Anniversary etc…

Contact Information:
This information is used for targeting and contacting persons. It consists of two types of information:

  • Can be changed by the customer: Email Addresses,  Phones via API and Portal.
  • Available for preview only: Push registrations, chat app profiles, etc.

Tags
Tags are used to group and organize people into the lists – interested in some service, sorted by importance, attribute or by some other input.
Can be only set by API and Portal users.

View also Custom Attributes and Tags

Person methods

Batch methods

Resource

https://api.infobip.com/people/2/persons

Model

Unique identifiers in query parameters

Each person can be addressed by one of the unique identifiers: phone number, email address, external ID or push registration ID. Each of these identifiers must be unique in the system which means that one cannot be assigned to multiple persons, other limitations for these parameters can be found in tables below. To address a particular person you need to use identifier type and URL encoded value, for example: phone=41793026727 or email=janesmith%4acme.com.

Please take notice that only one unique identifier should be passed for one request. If you send more than one identifier only the first one will be used.

Property name Type Description Case-insensitive
phone number Person’s phone number no
email string Person’s email address yes
externalId string Unique ID for a person from external system no
pushRegistrationId string Unique ID for push registration yes
id number Unique person’s internal ID no

Body parameters

Same model is used for both request and response except fields which are marked in Response only column

Property name Type Description Response only Limits
id number Unique internal ID generated on person creation yes -
createdAt string Date and time when the person was created yes -
modifiedAt string Date and time when the person was modified yes -
externalId string Unique ID for a person from your or another external system   256 characters max
firstName string Person's first name   255 characters max
lastName string Person's last name   255 characters max
address string Person's address   256 characters max
city string Person's city   50 characters max
country string Person's country   50 characters max
gender string Person's gender   MALE, FEMALE
birthDate string Person's date of birth   YYYY-MM-DD
middleName string Person's middle name   50 characters max
profilePicture string URL for the person's profile picture   2083 characters max
origin string The information which describes the origin of the record yes PORTAL, API, PUSH, FACEBOOK, LINE, TELEGRAM, VIBER_PA, VKONTAKTE
modifiedFrom string The information which describes the source of the last modification of record yes PORTAL, API, PUSH, FACEBOOK, LINE, TELEGRAM, VIBER_PA, VKONTAKTE
tags list of tags List of tags that this person has   See in Tags
customAttributes

list of custom attributes

 List of custom attributes for the person   See in Custom Attributes
contactInformation list of phones, emails etc.
List of phones, emails and other information how a person can be contacted
   See in the Contact information

Tags

Tags are used to segment persons. Tag's name is case-insensitive and unique in the system. If a tag does not exist it will be created. Below you can find brief information about the format of tags. You can find more information at Person Tags.

Property name Type Description Limits
name string Tag name 255 characters max

Custom attributes

Custom attributes are used to specify custom data for a person. You can find more information about them at Custom Attributes.

Property name Type Description Limits
name string Name of the attribute 255 characters max
value string, number, boolean, date Value

Max value for the number is 9223372036854775807. Max length for the string is 4096 characters. Date is YYYY-MM-DD.

Contact information

Contact information is a list of emails, phone numbers or other ways of contacting a particular person.

Property name Type Description
phone

list of phone numbers

 Person's phone numbers on which they can be contacted
email list of emails Person's email addresses on which they can be contacted
push

list of Push registrations

 Person's Push application profiles on which they can be contacted
facebook list of Facebook registrations Person's Facebook profiles on which they can be contacted
telegram list of Telegram registrations Person's Telegram profiles on which they can be contacted
Phone numbers
Property name Type Description Limits
number string Person's number. Phone numbers must be in international format (Example: 41793026727) Should comply with international number format (https://en.wikipedia.org/wiki/E.164). 50 characters max.
Emails
Property name Type Description Limits
address string person's email address. Email addresses must be in the following format: name@example.com Should comply with email format (https://tools.ietf.org/html/rfc2822). 255 characters max.
Push registrations
Property name Type Description
applicationId string Application Id on which the user is subscribed
registrationId string Push registration ID
systemData systemData System data collected from the user's profile
isPrimary boolean

Set to true if this device is a primary device of a user among other devices
Facebook registrations
Property name Type Description
applicationId string Application Id on which the user is subscribed
userId string Unique user ID for a person
systemData systemData System data collected from the user's profile
Telegram registrations
Property name Type Description
applicationId string Application Id on which the user is subscribed
userId string Unique user ID for a person
systemData systemData System data collected from the user's profile
System data
Property name Type Description
name string Name that describes the data collected from a person's profile (i.e. "gender", "os", "deviceManufacturer" etc.)
value string A value assigned (i.e. "female", "Android", "Samsung" etc.)

Person methods

Managed contact information

Please note, that only contact information managed by API (phones and emails) will be affected by methods that change person

Create a new person

Use this method to create a new person:

Request:

POST /people/2/persons HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

{
   "externalId":"1",
   "firstName":"Jane",
   "lastName":"Smith",
   "address":"67 Farringdon Road",
   "city":"London",
   "country":"United Kingdom",
   "gender":"FEMALE",
   "birthDate":"1966-01-15",
   "middleName":"Janie",
   "profilePicture":"http://profile.com",
   "tags":[
      "VIP Customers",
      "New Customers"
   ],
   "customAttributes":{
      "Contract Expiry":"2018-06-01",
      "Company":"Acme"
   },
   "contactInformation":{
      "phone":[
         {
            "number":"41793026727"
         },
         {
            "number":"41793026728"
         }
      ],
      "email":[
         {
            "address":"jane@acme.com"
         },
         {
            "address":"janesmith@acme.com"
         }
      ]
   }
}

Response:

{
   "id": 1,
   "createdAt":"2018-03-29T13:46:31",
   "modifiedAt":"2018-03-29T13:48:13",
   "externalId":"1",
   "firstName":"Jane",
   "lastName":"Smith",
   "address":"67 Farringdon Road",
   "city":"London",
   "country":"United Kingdom",
   "gender":"FEMALE",
   "birthDate":"1966-01-15",
   "middleName":"Janie",
   "profilePicture":"http://profile.com",
   "origin":"API",
   "modifiedFrom":"API",
   "tags":[
      "VIP Customers",
      "New Customers"
   ],
   "customAttributes":{
      "Contract Expiry":"2018-06-01",
      "Company":"Acme"
   },
   "contactInformation":{
      "phone":[
         {
            "number":"41793026727"
         },
         {
            "number":"41793026728"
         }
      ],
      "email":[
         {
            "address":"janesmith@acme.com"
         },
         {
            "address":"jane@acme.com"
         }
      ]
   }
}
{
    "value": 40002,
    "message": "Duplicate"
}

DUPLICATES HANDLING

If you try to create a person with information that already exists in the system, you will get the following response:

{
    "value": 40002,
    "message": "Duplicate"
}

Get a single person

Use this method to get a single person:

Request:

GET /people/2/persons?phone=41793026727 HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

Response:

{
    "id": 1,
    "createdAt": "2018-03-29T13:46:31",
    "modifiedAt": "2018-03-29T13:48:13",
    "externalId": "1",
    "firstName": "Jane",
    "lastName": "Smith",
    "address":"67 Farringdon Road",
    "city":"London",
    "country":"United Kingdom",
    "gender": "FEMALE",
    "birthDate": "1966-01-15",
    "middleName": "Janie",
    "profilePicture": "http://profile.com",
    "origin": "API",
    "modifiedFrom":"API",
    "tags": [
        "VIP Customers",
        "New Customers"
    ],
    "customAttributes": {
        "Contract Expiry": "2018-06-01",
        "Company": "Acme"
    },
    "contactInformation": {
        "phone": [
            {
                "number": "41793026727"
            },
            {
                "number": "41793026728"
            }
        ],
        "email": [
            {
                "address": "janesmith@acme.com"
            },
            {
                "address": "jane@acme.com"
            }
        ]
    }
}

Get a list of persons

Use this method to get a list of persons with pagination:

Parameter Type Description
limit int If a limit count is given, no more than that many rows will be returned (but possibly less, if the query itself yields fewer rows). The default value is 100.
page int This parameter says to skip that many rows before beginning to return rows. If both *page *and *limit *appear, then page rows are skipped before starting to count the limit rows that are returned. The default value is 1.
orderBy string This parameter is used to order your results. If an order is not given, the default order modifiedAt:desc will be applied. Possible fields for ordering are firstName, middleName, lastName, modifiedAt, createdAt, externalId, birthDate, city, address

Request:

GET /people/2/persons HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

Response:

{
   "limit":100,
   "page":1,
   "orderBy":"modifiedAt:desc",
   "persons":[
      {
         "id": 1,
         "createdAt":"2018-03-29T13:46:31",
         "modifiedAt":"2018-03-29T14:34:26",
         "externalId":"1",
         "firstName":"Jane",
         "lastName":"Smith",
         "address":"67 Farringdon Road",
         "city":"London",
         "country":"United Kingdom",
         "gender":"FEMALE",
         "birthDate":"1966-01-15",
         "middleName":"Janie",
         "profilePicture":"http://profile.com",
         "origin":"API",
         "modifiedFrom":"API",
         "tags":[
            "VIP Customers",
            "New Customers"
         ],
         "customAttributes":{
            "Contract Expiry":"2018-06-01",
            "Company":"Acme"
         },
         "contactInformation":{
            "phone":[
               {
                  "number":"41793026727"
               },
               {
                  "number":"41793026728"
               }
            ],
            "email":[
               {
                  "address":"janesmith@acme.com"
               },
               {
                  "address":"jane@acme.com"
               }
            ]
         }
      }
   ]
}

Include total count of persons

Add &includeTotalCount=true as a parameter to get a total count together with a list of persons

Filter persons

Additionally, you can get persons according to any filter you want. Simply add URL encoded filter parameters to your method and segment your audience even deeper.

List of supported logical operators:
Logical Operator Description
#and Joins query clauses with a logical AND returns all records that match the conditions of both clauses.
#or Joins query clauses with a logical OR returns all records that match the conditions of either clause.
List of supported comparison operators:
Comparison Operator Supported Type Description
#eq string, integer, decimal, date Matches values that are equal to a specified value.
#ne string, integer, decimal, date Matches all values that are not equal to a specified value.
#contains string Matches the records that contain a specified value.
#startsWith string Matches the records that start with a specified value.
#endsWith string Matches the records that end with a specified value.
#gt integer, decimal, date Matches values that are greater than a specified value.
#lt integer, decimal, date Matches values that are less than a specified value.
#gte integer, decimal, date Matches values that are greater than or equal to a specified value.
#lte integer, decimal, date Matches values that are less than or equal to a specified value.
Paging and ordering
Parameter Type Description
limit int If a limit count is given, no more than that many rows will be returned (but possibly less, if the query itself yields fewer rows). The default value is 20.
page int This parameter says to skip that many rows before beginning to return rows. If both *page *and *limit *appear, then page rows are skipped before starting to count the limit rows that are returned. The default value is 1.
orderBy string This parameter is used to order your results. If an order is not given, the default order modifiedAt:desc will be applied.

Examples

Example 01 - Basic filter with one condition

Let’s say you want to send greetings to all employees who work for a company called Acme. In order to do that, you need to filter all people who have “Company” which equals “Acme”. This would be your JSON:

  • JSON
{  
   "#eq":{  
      "customAttributes":{  
         "Company": "Acme"
      }
   }
}

When you encode this filter, you will have a method like this:

GET /people/2/persons?filter=%7B%20%20%0A%20%20%20%22%23eq%22%3A%7B%20%20%0A%20%20%20%20%20%20%22customAttributes%22%3A%7B%20%20%0A%20%20%20%20%20%20%20%20%20%22Company%22%3A%20%22Acme%22%0A%20%20%20%20%20%20%7D%0A%20%20%20%7D%0A%7D HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json
GET /people/1/persons?filter=%7B%20%20%0A%20%20%20%22%23eq%22%3A%7B%20%20%0A%20%20%20%20%20%20%22additionalData%22%3A%7B%20%20%0A%20%20%20%20%20%20%20%20%20%22Company%22%3A%20%22Acme%22%0A%20%20%20%20%20%20%7D%0A%20%20%20%7D%0A%7D HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/xml

Response:

{
   "limit":20,
   "page":1,
   "orderBy":"modifiedAt:desc",
   "persons":[
      {
         "id":"FA57F1D04DEC22E96CEE21DF99C47841",
         "createdAt":"2018-03-29T13:46:31",
         "modifiedAt":"2018-03-29T14:34:26",
         "externalId":"1",
         "firstName":"Jane",
         "lastName":"Smith",
         "address":"67 Farringdon Road",
         "city":"London",
         "country":"United Kingdom",
         "gender":"FEMALE",
         "birthDate":"1966-01-15",
         "middleName":"Janie",
         "profilePicture":"http://profile.com",
         "origin":"API",
         "tags":[
            "VIP Customers",
            "New Customers"
         ],
         "customAttributes":{
            "Contract Expiry":"2018-06-01",
            "Company":"Acme"
         },
         "contactInformation":{
            "phone":[
               {
                  "number":"41793026727"
               },
               {
                  "number":"41793026728"
               }
            ],
            "email":[
               {
                  "address":"janesmith@acme.com"
               },
               {
                  "address":"jane@acme.com"
               }
            ]
         }
      }
   ]
}
<?xml version="1.0" encoding="UTF-8" ?>
<String>
   <limit>20</limit>
   <page>1</page>
   <orderBy>modifiedAt:desc</orderBy>
   <persons>
      <persons>
         <id>FA57F1D04DEC22E96CEE21DF99C47841</id>
         <createdAt>2018-03-29T13:46:31</createdAt>
         <modifiedAt>2018-03-29T14:34:26</modifiedAt>
         <externalId>1</externalId>
         <firstName>Jane</firstName>
         <lastName>Smith</lastName>
         <address>67 Farringdon Road</address>
         <city>London</city>
         <country>United Kingdom</country>
         <gender>FEMALE</gender>
         <birthDate>1966-01-15</birthDate>
         <middleName>Janie</middleName>
         <profilePicture>http://profile.com</profilePicture>
         <origin>API</origin>
         <tags>
            <tags>VIP Customers</tags>
            <tags>New Customers</tags>
         </tags>
         <customAttributes>
            <Contract_Expiry>2018-06-01</Contract_Expiry>
            <Company>Acme</Company>
         </additionalData>
         <contactInformation>
            <phone>
               <phone>
                  <number>41793026727</number>
               </phone>
               <phone>
                  <number>41793026728</number>
               </phone>
            </phone>
            <email>
               <email>
                  <address>janesmith@acme.com</address>
               </email>
               <email>
                  <address>jane@acme.com</address>
               </email>
            </email>
         </contacts>
      </persons>
   </persons>
</String>
Example 02 - Advanced filter with multiple conditions

Let’s say you want to send a campaign to all females in your All Customers list because today is International Women’s Day. In order to do that, you need to filter all persons whose gender is “Female”, have “All Customers” tag and having custom attribute “Category” starting with “Premium…”. This would be your JSON:

  • JSON
{
    "#and": [
        {
            "#eq": {
                "gender": "FEMALE"
            }
        },
        {
            "#contains": {
                "tags": "All Customers"
            }
        },
        {
            "#startsWith": {
                "customAttributes": {
                    "Category": "Premium"
                }
            }
        }
    ]
}
Example 03 - Advanced filter with multiple conditions

Let’s say you want to find a person with a specific phone number. This would be your JSON:

  • JSON
{
  "contactInformation": {
    "phone": [
      {
        "number": "41793026727"
      }
    ]
  }
}

Update person

Use this method to update person data:

Request:

PUT /people/2/persons?email=jane%40acme.com HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

{
   "externalId":"3",
   "firstName":"Jane",
   "lastName":"Smith",
   "address":"67 Farringdon Road",
   "city":"London",
   "country":"United Kingdom",
   "gender":"FEMALE",
   "birthDate":"1966-01-15",
   "middleName":"Janie",
   "profilePicture":"http://profile.com",
   "tags":[
      "VIP Customers",
      "New Customers"
   ],
   "customAttributes":{
      "Contract Expiry":"2018-06-01",
      "Company":"Acme"
   },
   "contactInformation":{
      "phone":[
         {
            "number":"41793026727"
         },
         {
            "number":"41793026729"
         }
      ],
      "email":[
         {
            "address":"janesmith@acme.com"
         },
         {
            "address":"jane@acme.com"
         }
      ]
   }
}

Response:

{
   "id": 1,
   "createdAt":"2018-03-29T13:46:31",
   "modifiedAt":"2018-03-30T11:25:13",
   "externalId":"3",
   "firstName":"Jane",
   "lastName":"Smith",
   "address":"67 Farringdon Road",
   "city":"London",
   "country":"United Kingdom",
   "gender":"FEMALE",
   "birthDate":"1966-01-15",
   "middleName":"Janie",
   "profilePicture":"http://profile.com",
   "origin":"API",
   "modifiedFrom":"API",
   "tags":[
      "VIP Customers",
      "New Customers"
   ],
   "customAttributes":{
      "Contract Expiry":"2018-06-01",
      "Company":"Acme"
   },
   "contactInformation":{
      "phone":[
         {
            "number":"41793026727"
         },
         {
            "number":"41793026729"
         }
      ],
      "email":[
         {
            "address":"janesmith@acme.com"
         },
         {
            "address":"jane@acme.com"
         }
      ]
   }
}

Request:

PUT /people/2/persons?email=jane%40acme.com HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

{
   "externalId":"3",
   "firstName":"Jane",
   "lastName":"Smith",
   "address":"67 Farringdon Road",
   "city":"London",
   "country":"United Kingdom",
   "gender":"FEMALE",
   "birthDate":"1966-01-15",
   "middleName":"Janie",
   "profilePicture":"http://profile.com",
   "tags":[
      "VIP Customers",
      "New Customers"
   ],
   "customAttributes":{
      "Contract Expiry":"2018-06-01",
      "Company":"Acme"
   },
   "contactInformation":{
      "phone":[
         {
            "number":"41793026727"
         }
      ]
   }
}

Response:

{
   "id": 1,
   "createdAt":"2018-03-29T13:46:31",
   "modifiedAt":"2018-03-30T11:25:13",
   "externalId":"3",
   "firstName":"Jane",
   "lastName":"Smith",
   "address":"67 Farringdon Road",
   "city":"London",
   "country":"United Kingdom",
   "gender":"FEMALE",
   "birthDate":"1966-01-15",
   "middleName":"Janie",
   "profilePicture":"http://profile.com",
   "origin":"API",
   "modifiedFrom":"API",
   "tags":[
      "VIP Customers",
      "New Customers"
   ],
   "customAttributes":{
      "Contract Expiry":"2018-06-01",
      "Company":"Acme"
   },
   "contactInformation":{
      "phone":[
         {
            "number":"41793026727"
         }
      ],      
      "push": [
        {
          "applicationId": "FDCC8516470A3AE97FB8AC218D5D0D3D",
          "registrationId": "c5db0c47-465c-4e1c-abf8-7cedc275dd19",
          "additionalData": {
            "birthdate": "1988-07-31",
            "email": "test@test.com",
            "firstName": "Jane",
            "gender": "F",
            "lastName": "Smith",
            "middleName": "Janie"
          },
          "systemData": {
            "cloudType": "GCM",
            "registrationEnabled": true,
            "sdkName": "MobileMessaging SDK",
            "os": "Android"
          }
        }
      ],
      "facebook": [
        {
          "applicationId": "FD88AF1115A15C1E3E07A2B5A567BF99",
          "userId": "BA23BB5E09C5205DB4A7B9B06595EB3C28C12E83BC83D449BC4A9F32F1AE3C3E",
          "systemData": {
            "gender": "female",
            "lastName": "Smith",
            "firstName": "Jane"
          }
        }
      ]
   }
}

Delete person

Use this method to delete a person:

Request:

DELETE /people/2/persons?externalId=1 HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

Response:

{
    "errorCode": 40401,
    "errorMessage": "Person does not exist"
}

Deleting a person which doesn't exist

If you try to delete a person which does not exist, you will get the following response:

{
    "errorCode": 40401,
    "errorMessage": "Person does not exist"
}

Partial person update

Partial person update method is used for updating part of the profile fields. When you submit any field - it will be replaced in the specified person. When you submit Phone or Email it will be added to the existing set of phones and emails. To rewrite profile Contact info use method “Set Contact Information”.

Request:

PATCH /people/2/persons?externalId=3 HTTP/1.1
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

{
   "lastName":"Williams",
   "address":"10 York Street",
   "contactInformation":{
      "email":[
         {
            "address":"janewilliams@acme.com"
         }
      ]
   }
}

Response:

{
   "id": 1,
   "createdAt":"2018-03-29T13:46:31",
   "modifiedAt":"2018-03-30T11:25:13",
   "externalId":"3",
   "firstName":"Jane",
   "lastName":"Williams",
   "address":"10 York Street",
   "city":"London",
   "country":"United Kingdom",
   "gender":"FEMALE",
   "birthDate":"1966-01-15",
   "middleName":"Janie",
   "profilePicture":"http://profile.com",
   "origin":"API",
   "modifiedFrom":"API",
   "tags":[
      "VIP Customers",
      "New Customers"
   ],
   "customAttributes":{
      "Contract Expiry":"2018-06-01",
      "Company":"Acme"
   },
   "contactInformation":{
      "phone":[
         {
            "number":"41793026727"
         }
      ],
      "email":[
         {
            "address":"janewilliams@acme.com"
         },
         {
            "address":"janesmith@acme.com"
         },
         {
            "address":"jane@acme.com"
         }
      ], 
      "push": [
        {
          "applicationId": "FDCC8516470A3AE97FB8AC218D5D0D3D",
          "registrationId": "c5db0c47-465c-4e1c-abf8-7cedc275dd19",
          "additionalData": {
            "birthdate": "1988-07-31",
            "email": "test@test.com",
            "firstName": "Jane",
            "gender": "F",
            "lastName": "Smith",
            "middleName": "Janie"
          },
          "systemData": {
            "cloudType": "GCM",
            "registrationEnabled": true,
            "sdkName": "MobileMessaging SDK",
            "os": "Android"
          }
        }
      ],
      "facebook": [
        {
          "applicationId": "FD88AF1115A15C1E3E07A2B5A567BF99",
          "userId": "BA23BB5E09C5205DB4A7B9B06595EB3C28C12E83BC83D449BC4A9F32F1AE3C3E",
          "systemData": {
            "gender": "female",
            "lastName": "Smith",
            "firstName": "Jane"
          }
        }
      ]
   }
}

Set contact information to person

Use this method to replace contact information for particular person. This methods will replace all existing emails and mobile phones with provided contact information. Please notice that old contact information will be removed.

Request:

PUT /people/2/persons/contactInformation?externalId=1 HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

{
   "contactInformation":{
      "phone":[
         {
            "number":"41793026727"
         },
         {
            "number":"41793026729"
         }
      ],
      "email":[
         {
            "address":"janesmith@acme.com"
         },
         {
            "address":"jane@acme.com"
         }
      ]
   }
}

Response:

{
   "id": 1,
   "createdAt":"2018-03-29T13:46:31",
   "modifiedAt":"2018-03-30T11:25:13",
   "externalId":"3",
   "firstName":"Jane",
   "lastName":"Smith",
   "address":"67 Farringdon Road",
   "city":"London",
   "country":"United Kingdom",
   "gender":"FEMALE",
   "birthDate":"1966-01-15",
   "middleName":"Janie",
   "profilePicture":"http://profile.com",
   "origin":"API",
   "tags":[
      "VIP Customers",
      "New Customers"
   ],
   "customAttributes":{
      "Contract Expiry":"2018-06-01",
      "Company":"Acme"
   },
   "contactInformation":{
      "phone":[
         {
            "number":"41793026727"
         },
         {
            "number":"41793026729"
         }
      ],
      "email":[
         {
            "address":"janesmith@acme.com"
         },
         {
            "address":"jane@acme.com"
         }
      ]
   }
}
{
    "errorCode": 40401,
    "errorMessage": "Person does not exist"
}

Add contact information to person

Use this method to add specified emails and mobile phones to particular person:

Request:

PATCH /people/2/persons/contactInformation?externalId=1 HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

{
   "contactInformation":{
      "phone":[
         {
            "number":"41793026728"
         }
      ],
      "email":[
         {
            "address":"jane@acme.org"
         }
      ]
   }
}

Response:

{
   "id": 1,
   "createdAt":"2018-03-29T13:46:31",
   "modifiedAt":"2018-03-30T11:25:13",
   "externalId":"3",
   "firstName":"Jane",
   "lastName":"Smith",
   "address":"67 Farringdon Road",
   "city":"London",
   "country":"United Kingdom",
   "gender":"FEMALE",
   "birthDate":"1966-01-15",
   "middleName":"Janie",
   "profilePicture":"http://profile.com",
   "origin":"API",
   "tags":[
      "VIP Customers",
      "New Customers"
   ],
   "customAttributes":{
      "Contract Expiry":"2018-06-01",
      "Company":"Acme"
   },
   "contactInformation":{
      "phone":[
         {
            "number":"41793026727"
         },
         {
            "number":"41793026729"
         },
         {
            "number":"41793026728"
         },
      ],
      "email":[
         {
            "address":"janesmith@acme.com"
         },
         {
            "address":"jane@acme.com"
         } ,
         {
            "address":"jane@acme.org"
         }
      ]
   }
}
{
    "errorCode": 40401,
    "errorMessage": "Person does not exist"
}

Delete contact information from person

Use this method to delete specified emails and mobile phones for particular person:

Request:

DELETE /people/2/persons/contactInformation?externalId=1 HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

{
   "contactInformation":{
      "phone":[
         {
            "number":"41793026727"
         }
      ],
      "email":[
         {
            "address":"jane@acme.com"
         }
      ]
   }
}

Response:

{
   "id": 1,
   "createdAt":"2018-03-29T13:46:31",
   "modifiedAt":"2018-03-30T11:25:13",
   "externalId":"3",
   "firstName":"Jane",
   "lastName":"Smith",
   "address":"67 Farringdon Road",
   "city":"London",
   "country":"United Kingdom",
   "gender":"FEMALE",
   "birthDate":"1966-01-15",
   "middleName":"Janie",
   "profilePicture":"http://profile.com",
   "origin":"API",
   "tags":[
      "VIP Customers",
      "New Customers"
   ],
   "customAttributes":{
      "Contract Expiry":"2018-06-01",
      "Company":"Acme"
   },
   "contactInformation":{
      "phone":[
         {
            "number":"41793026729"
         }
      ],
      "email":[
         {
            "address":"janesmith@acme.com"
         }
      ]
   }
}
{
    "errorCode": 40401,
    "errorMessage": "Person does not exist"
}

Batch methods

Batch methods

You can address a person by passing unique identifiers in query field. For example "query": { "externalId": "1" } or "query": { "email": "johnhancock@mail.com" } Take notice, that you don’t need to URL encode these identifiers and the maximum number of entries is 1000

Batch people create

Use this method to create multiple persons. It works similar to create a new person method. The response will contain a list of error results addressing persons by array indices from request.

Multi-status model

If request was successfully processed and all people was created than no response will be returned. If there was problems with creating people, list of failed results will be returned. For example if one of unique person identifiers already exists, list of results will contain entry for this person with message `Key (externalId)=(1) already exists.`

Property name Type Description
results list of results List of unsuccessful results for persons who cannot be created. For created persons result is not returned

Results

Result contain index of failed person and list of error why person cannot be created . Results are returned only for people who cannot be created.

Property name Type Description
index number Index of person in request starting from zero
errors list of errors List of errors describing why this person cannot be created
status number HTTP status code for error

Errors

Errors describe problems why person cannot be created.

Property name Type Description
message string Text which describes the problem with person profile

Request:

POST /people/2/persons/batch HTTP/1.1
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json
{
    "people": [
        {
            "firstName": "Jane",
            "lastName": "Williams",
            "address": "10 York Street",
            "contactInformation": {
                "email": [
                    {
                        "address": "janewilliams@acme.com"
                    },
                    {
                        "address": "jane@acme.com"
                    }
                ]
            }
        },
        {
            "firstName": "James",
            "lastName": "Smith",
            "contactInformation": {
                "phone": [
                    {
                        "number": "41792232491"
                    }
                ]
            }
        },
        {
            "firstName": "Joseph",
            "lastName": "McCarthy",
            "contactInformation": {
                "phone": [
                    {
                        "number": "41792232492"
                    }
                ]
            }
        }
    ]
}

Response:


{
    "results": [
        {
            "index": 0,
            "errors": [
                {
                    "message": "Key (externalId)=(1) already exists."
                }
            ],
            "status": 409
        },
        {
            "index": 2,
            "errors": [
                {
                    "message": "[destinations[1].msisdn: number does not have valid country/network prefix]"
                }
            ],
            "status": 409
        },
        {
            "index": 5,
            "errors": [
                {
                    "message": "[destinations: may not be empty]"
                }
            ],
            "status": 409
        }
    ]
} 

{
    "errorCode": 40001,
    "errorMessage": "Bad Request"
}

Batch people delete

Use this method to delete multiple persons. It works similar to delete person method. The response will contain a list of error results with queries.

Request:

DELETE /people/2/persons/batch HTTP/1.1
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json
{
   "people": [
      {
         "query": {
            "externalId": "1"
         }
      },
      {
         "query": {
            "phone": "41793054678"
         }
      },
      {
         "query": {
            "email": "hancock@mail.com"
         }
      }
   ]
}

Response:


{
    "results": [
        {
            "query": {
                "phone": "41793054678"
            },
            "errors": [
                {
                    "message": "Person with (phone=385993235555) does not exist"
                }
            ],
            "status": 409
        },
        {
            "query": {
                "email": "hancock@mail.com"
            },
            "errors": [
                {
                    "message": "Can't delete person with push or ott destination"
                }
            ],
            "status": 409
        }
    ]
}

{
    "errorCode": 40016,
    "errorMessage": "Invalid delete entry: Incorrect unique key '[extrnalId:1]'"
}

Batch partial people update

Use this method to update multiple persons. It works similar to partial person update method. The response will contain a list of error results with queries.

Request:

PATCH /people/2/persons/batch HTTP/1.1
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json
{
   "people": [
      {
         "query": {
            "externalId": "1"
         },
         "update": {
            "lastName": "Williams",
            "address": "10 York Street",
            "contactInformation": {
               "email": [
                  {
                     "address": "janewilliams@acme.com"
                  },
                  {
                     "address": "jane@acme.com"
                  }
               ]
            }
         }
      },
      {
         "query": {
            "phone": "41793054678"
         },
         "update": {
            "externalId": 1
         }
      },
      {
         "query": {
            "email": "hancock@mail.com"
         },
         "update": {
            "contactInformation": {
               "phone": [
                  {
                     "number": "41792232491"
                  }
               ]
            }
         }
      },
      {
         "query": {
            "externalId": "3"
         },
         "update": {
            "contactInformation": {
               "phone": [
                  {
                     "number": "41792232492"
                  }
               ]
            }
         }
      }
   ]
}

Response:


{
    "results": [
        {
            "query": {
                "phone": "41793054678"
            },
            "errors": [
                {
                    "message": "Key (externalId)=(1) already exists."
                }
            ],
            "status": 409
        },
        {
            "query": {
                "email": "hancock@mail.com"
            },
            "errors": [
                {
                    "message": "Duplicated by [3]:identified by (externalId=3)"
                }
            ],
            "status": 409
        },
        {
            "query": {
                "externalId": "3"
            },
            "errors": [
                {
                    "message": "Duplicated by [2]:identified by (email=hancock@mail.com)"
                }
            ],
            "status": 409
        }
    ]
}

{
    "errorCode": 40014,
    "errorMessage": "Invalid update entry: Incorrect unique key '[extrnalId:1]'"
}
Prev: Introduction Next: Tags