Person

A person represents your end user's unique profile.

A person consists of the following information:

  • standard data (i.e. First Name, Last Name, Address...)
  • additional data (any type of information that describes a person or his or hers behavior i.e. Contract Expiry Date, Anniversary etc.)
  • tags (used to group persons in lists)
  • contacts (i.e. phone numbers, e-mail address, push registrations, chat app profiles etc.)

On this page you will learn how to insert, filter, update and delete your persons data.

Person methods:

View also Additional Field and Tags

RESOURCE

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

MODEL

Parameters

Body Params


 

Property name Type Description
id string ID assigned for a person returned in method response.
createdAt string Date and time when person was created returned in method response.
modifiedAt string Date and time when person was modified returned in method response.
externalId string Unique ID for a person from your or other external system.
firstName string Person's first name.
lastName string Person's last name.
address string Person's address.
city string Person's city.
country string Person's country
gender string Person's gender. Supported values are MALE or FEMALE.
birthDate string Person's date of birth.
middleName string Person's middle name.
profilePicture string URL for person's profile picture.
origin string Information which describes the origin of the record returned in method response.
tags array List of tags that this person has.
 
Property name Type Description
name string Tag name.
additionalData object List of additional data for person.
 
Property name Type Description
name string Name of a field.
value string Value.
contacts array Person's contacts on which they can be contacted.
 
Property name Type Description
Phone string

Person's phone numbers on which they can be contacted.

 
Property name Type Description
number string Person's number. Phone numbers must be in international format (Example: 41793026727)
Email string Person's email addresses on which they can be contacted.
 
Property name Type Description
address string person's email address. Email addresses must be in following format: name@example.com
Push string

Person's push application profiles on which they can be contacted.

 
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 user's profile.
Facebook string Person's Facebook profiles on which they can be contacted.
 
Property name Type Description
applicationId string Application Id on which theuser is subscribed.
userId string Unique user ID for a person.
systemData systemData System data collected from user's profile.
Telegram string Person's Telegram profiles on which they can be contacted.
 
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 user's profile.
Line string Person's Line profiles on which they can be contacted.
 
Property name Type Description
applicationId string Application Id on which user is subscribed.
userId string Unique user ID for a person.
systemData systemData System data collected from user's profile.
System data description string  
 
Property name Type Description
name string Name that describes the data collected from person's profile (i.e. "gender", "os", "deviceManufacturer" etc.).
value string A value assigned (i.e. "female", "Android", "Samsung" etc.).

 

 
 

Create new person 

Use this method to create new person:

POST /people/1/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"
   ],
   "additionalData":{
      "Contract Expiry":"2018-06-01",
      "Company":"Acme"
   },
   "contacts":{
      "phone":[
         {
            "number":"41793026727"
         },
         {
            "number":"41793026728"
         }
      ],
      "email":[
         {
            "address":"jane@acme.com"
         },
         {
            "address":"janesmith@acme.com"
         }
      ]
   }
}
POST /people/1/persons HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<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>
<tags>VIP Customers</tags>
<tags>New Customers</tags>
<additionalData>
    <Contract_Expiry>2018-06-01</Contract_Expiry>
    <Company>Acme</Company>
</additionalData>
<contacts>
    <phone>
        <number>41793026727</number>
    </phone>
    <phone>
        <number>41793026728</number>
    </phone>
    <email>
        <address>jane@acme.com</address>
    </email>
    <email>
        <address>janesmith@acme.com</address>
    </email>
</contacts>

Response:

{
   "id":"FA57F1D04DEC22E96CEE21DF99C47841",
   "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",
   "tags":[
      "VIP Customers",
      "New Customers"
   ],
   "additionalData":{
      "Contract Expiry":"2018-06-01",
      "Company":"Acme"
   },
   "contacts":{
      "phone":[
         {
            "number":"41793026727"
         },
         {
            "number":"41793026728"
         }
      ],
      "email":[
         {
            "address":"janesmith@acme.com"
         },
         {
            "address":"jane@acme.com"
         }
      ]
   }
}
<?xml version="1.0" encoding="UTF-8" ?>
    <id>FA57F1D04DEC22E96CEE21DF99C47841</id>
    <createdAt>2018-03-29T13:46:31</createdAt>
    <modifiedAt>2018-03-29T13:48:13</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>VIP Customers</tags>
    <tags>New Customers</tags>
    <additionalData>
        <Contract Expiry>2018-06-01</Contract Expiry>
        <Company>Acme</Company>
    </additionalData>
    <contacts>
        <phone>
            <number>41793026727</number>
        </phone>
        <phone>
            <number>41793026728</number>
        </phone>
        <email>
            <address>janesmith@acme.com</address>
        </email>
        <email>
            <address>jane@acme.com</address>
        </email>
    </contacts>

Duplicates handling

Each externalId, phone number, email address or userId must be unique in the system which means that one cannot be assigned to multiple persons. If you try to create a person with information that already exists in the system, you will get following response:

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

Get single person 

Use this method to get single person:

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

Response:

{
    "id": "FA57F1D04DEC22E96CEE21DF99C47841",
    "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",
    "tags": [
        "VIP Customers",
        "New Customers"
    ],
    "additionalData": {
        "Contract Expiry": "2018-06-01",
        "Company": "Acme"
    },
    "contacts": {
        "phone": [
            {
                "number": "41793026727"
            },
            {
                "number": "41793026728"
            }
        ],
        "email": [
            {
                "address": "janesmith@acme.com"
            },
            {
                "address": "jane@acme.com"
            }
        ]
    }
}
<?xml version="1.0" encoding="UTF-8" ?>
    <id>FA57F1D04DEC22E96CEE21DF99C47841</id>
    <createdAt>2018-03-29T13:46:31</createdAt>
    <modifiedAt>2018-03-29T13:48:13</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>VIP Customers</tags>
    <tags>New Customers</tags>
    <additionalData>
        <Contract Expiry>2018-06-01</Contract Expiry>
        <Company>Acme</Company>
    </additionalData>
    <contacts>
        <phone>
            <number>41793026727</number>
        </phone>
        <phone>
            <number>41793026728</number>
        </phone>
        <email>
            <address>janesmith@acme.com</address>
        </email>
        <email>
            <address>jane@acme.com</address>
        </email>
    </contacts>

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:

{  
   "#eq":{  
      "additionalData":{  
         "Company": "Acme"
      }
   }
}	
  

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

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/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"
         ],
         "additionalData":{
            "Contract Expiry":"2018-06-01",
            "Company":"Acme"
         },
         "contacts":{
            "phone":[
               {
                  "number":"41793026727"
               },
               {
                  "number":"41793026728"
               }
            ],
            "email":[
               {
                  "address":"janesmith@acme.com"
               },
               {
                  "address":"jane@acme.com"
               }
            ]
         }
      }
   ]
}
<?xml version="1.0" encoding="UTF-8" ?>
<limit>20</limit>
<page>1</page>
<orderBy>modifiedAt:desc</orderBy>
<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>VIP Customers</tags>
    <tags>New Customers</tags>
    <additionalData>
        <Contract_Expiry>2018-06-01</Contract_Expiry>
        <Company>Acme</Company>
    </additionalData>
    <contacts>
        <phone>
            <number>41793026727</number>
        </phone>
        <phone>
            <number>41793026728</number>
        </phone>
        <email>
            <address>janesmith@acme.com</address>
        </email>
        <email>
            <address>jane@acme.com</address>
        </email>
    </contacts>
</persons>

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” and have “All Customers” tag. This would be your JSON:

{  
   "#and":[  
      {  
         "#eq":{  
            "gender":"FEMALE"
         }
      },
      {  
         "#contains":{  
            "tags":"All Customers"
         }
      }
   ]
}	
  

Example 03 - Advanced filter with multiple groups of conditions

Let’s say you want to send a campaign to all of your end users who live either in London or Reading and are in your January Sales Customer list to inform them about new store openings and special January sales offers. In order to do that, you need to filter all persons who live either in London or Reading and have been tagged with “January Sales Customer List”. This would be your JSON:

{  
   "#or":[  
      {  
         "#and":[  
            {  
               "city":"London"
            },
            {  
               "#contains":{  
                  "tags":"January Sale Customer List"
               }
            }
         ]
      },
      {  
         "#and":[  
            {  
               "city":"Reading"
            },
            {  
               "#contains":{  
                  "tags":"January Sale Customer List"
               }
            }
         ]
      }
   ]
}	
  

Include total count

Add &includes=totalCount as a parameter to get a total count together with a list of persons.

Update Person 

Use this method to update person data:

PUT /people/1/persons/FA57F1D04DEC22E96CEE21DF99C47841 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"
   ],
   "additionalData":{
      "Contract Expiry":"2018-06-01",
      "Company":"Acme"
   },
   "contacts":{
      "phone":[
         {
            "number":"41793026727"
         },
         {
            "number":"41793026729"
         }
      ],
      "email":[
         {
            "address":"janesmith@acme.com"
         },
         {
            "address":"jane@acme.com"
         }
      ]
   }
}
PUT /people/1/persons/FA57F1D04DEC22E96CEE21DF99C47841 HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<externalId>3</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>
<tags>VIP Customers</tags>
<tags>New Customers</tags>
<additionalData>
    <Contract_Expiry>2018-06-01</Contract_Expiry>
    <Company>Acme</Company>
</additionalData>
<contacts>
    <phone>
        <number>41793026727</number>
    </phone>
    <phone>
        <number>41793026729</number>
    </phone>
    <email>
        <address>janesmith@acme.com</address>
    </email>
    <email>
        <address>jane@acme.com</address>
    </email>
</contacts>

Response:

{
   "id":"FA57F1D04DEC22E96CEE21DF99C47841",
   "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"
   ],
   "additionalData":{
      "Contract Expiry":"2018-06-01",
      "Company":"Acme"
   },
   "contacts":{
      "phone":[
         {
            "number":"41793026727"
         },
         {
            "number":"41793026729"
         }
      ],
      "email":[
         {
            "address":"janesmith@acme.com"
         },
         {
            "address":"jane@acme.com"
         }
      ]
   }
}
<?xml version="1.0" encoding="UTF-8" ?>
<id>FA57F1D04DEC22E96CEE21DF99C47841</id>
<createdAt>2018-03-29T13:46:31</createdAt>
<modifiedAt>2018-03-30T11:25:13</modifiedAt>
<externalId>3</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>VIP Customers</tags>
<tags>New Customers</tags>
<additionalData>
    <Contract_Expiry>2018-06-01</Contract_Expiry>
    <Company>Acme</Company>
</additionalData>
<contacts>
    <phone>
        <number>41793026727</number>
    </phone>
    <phone>
        <number>41793026729</number>
    </phone>
    <email>
        <address>janesmith@acme.com</address>
    </email>
    <email>
        <address>jane@acme.com</address>
    </email>
</contacts>

Delete Person 

Use this method to delete person:

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

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"
}