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 AddressesPhones 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.

Person methods

View also Custom Attributes and Tags

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

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

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
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   256 characters max
lastName string Person's last name   256 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   2048 characters max
origin string The information which describes the origin of the 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 256 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 256 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). 256 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.)

Methods details

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:

{
   "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"
   ],
   "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:

{
    "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"
    ],
    "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":[
      {
         "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"
               }
            ]
         }
      }
   ]
}

Include total count of persons

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

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:

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

Managed contact information

Please note, that only contact information managed by API (phones and emails) will be affected by this method

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:

{
   "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"
         }
      ],      
      "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

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:

{
   "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",
   "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"
          }
        }
      ]
   }
}

Managed contact information

Please note, that only contact information managed by API (phones and emails) and used in the request body will be affected by this method. In the example below only email is updated and phone, push and facebook information remains as it was.

Bulk partial person update

Bulk partial update query

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.

Use this method to update multiple persons. It works similar to a partial update. 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]'"
}