Profile management with Person APIs

This guide will walk you through the steps required to update profile with persons API. Persons API allows you to create, delete or update person profiles. In this guide we will focus on updating.

Prerequisites

• configured Onegini IdP environment as described in the setup section,
• have access to Onegini IdP APIs and know the Persons API Basic Authentication credentials.

Create a person

Let' assume that you want to create the profile given following user's data:

Name: John William Doe
Date of birth: 24 May 1995
Email addresses: [email protected] (primary), [email protected] (alternative)
Mobile: +31 654 321 098
Language: English

To create the profile with the profile please execute the following request:

curl -i --user <username>:<password>
-H "Content-Type: application/json" 
-H "Accept: application/json" 
-d 
'{
    "gender":"M",
    "name":{
       "first_name":"John William",
       "last_name":"Doe",
       "initials":"J.W.D",
       "display_name":"Mr John W. Doe, Msc."
    },
    "date_of_birth":"1995-05-24",
    "email_addresses":[
       {
          "primary":true,
          "verified":false,
          "value":"[email protected]"
       },
       {
          "primary":false,
          "verified":false,
          "value":"[email protected]"
       }
    ],
    "phone_numbers":[
       {
          "primary":true,
          "verified":true,
          "tag":"MOBILE",
          "value":"+31 654 321 098"
       }
    ],
    "preferred_locale":"en_US"
 }'
-X POST http://idp-core.dev.onegini.me:8081/api/persons/

where <username> and <password> should be replaced with the Basic Auth credentials configured for the Person API.

As a response the reference id is returned with 201 Created status code:

HTTP/1.1 201 

{
   "reference_id":"8a742ac4-fabd-4580-924c-0281777e3d39"
} 

To be sure that profile has been created please execute the following request to get fetch the profile details:

curl -i --user <username>:<password> -X GET http://dev.onegini.me:8081/api/persons/<reference-id>

where <reference-id> is the value returned in previous step.

As a response profile object is returned with 200 Ok status:

HTTP/1.1 200 

{
   "person_id":"8a742ac4-fabd-4580-924c-0281777e3d39",
   "profile":{
      "gender":"M",
      "name":{
         "first_name":"John William",
         "last_name":"Doe",
         "display_name":"Mr John W. Doe, Msc.",
         "initials":"J.W.D"
      },
      "email_addresses":[
         {
            "primary":true,
            "tag":"",
            "verified":false,
            "value":"[email protected]"
         },
         {
            "primary":false,
            "tag":"ALT1",
            "verified":false,
            "value":"[email protected]"
         }
      ],
      "phone_numbers":[
         {
            "primary":true,
            "tag":"MOBILE",
            "value":"+31654321098"
         }
      ],
      "date_of_birth":"1995-05-24",
      "preferred_locale":"en_US"
   },
   "events":[
      {
         "event_identifier":"e6b13b60-f906-49b4-8258-028dd7dd83a1",
         "occurred":1516627020817,
         "event_type":"AttributesUpdatedEvent",
         "person_id":"8a742ac4-fabd-4580-924c-0281777e3d39",
         "client_ip":"127.0.0.1",
         "user_agent":"curl/7.52.1",
         "event_name":"Attributes of person updated",
         "event_agent_user":"persons_api_rest_user"
      },
      {
         "event_identifier":"b8bb6777-eed3-4ca7-a7fd-870b55986a60",
         "occurred":1516627020817,
         "event_type":"UsernameAddedEvent",
         "person_id":"8a742ac4-fabd-4580-924c-0281777e3d39",
         "client_ip":"127.0.0.1",
         "user_agent":"curl/7.52.1",
         "event_name":"New username for person added",
         "event_agent_user":"persons_api_rest_user"
      },
      {
         "event_identifier":"b9cd2cf6-6e93-4d98-a175-0dd32b6b923c",
         "occurred":1516627020817,
         "event_type":"UsernameAddedEvent",
         "person_id":"8a742ac4-fabd-4580-924c-0281777e3d39",
         "client_ip":"127.0.0.1",
         "user_agent":"curl/7.52.1",
         "event_name":"New username for person added",
         "event_agent_user":"persons_api_rest_user"
      },
      {
         "event_identifier":"e3d87053-68cc-4465-ace3-9109a60f854d",
         "occurred":1516627020811,
         "event_type":"PersonCreatedEvent",
         "person_id":"8a742ac4-fabd-4580-924c-0281777e3d39",
         "client_ip":"127.0.0.1",
         "user_agent":"curl/7.52.1",
         "event_name":"Person created",
         "event_agent_user":"persons_api_rest_user"
      }
   ],
   "identities":[

   ],
   "creation_date":1516627020811,
   "status":"CREATED",
   "last_login":0,
   "logins":0
}

Update email address

To update person's email address you need to execute a request with email_addresses property defined in the body. Currently it is possible to have two email addresses (primary and alternative).

In case you want to update person's alternative email following request should be executed:

curl -i --user username:password
-H "Content-Type: application/json"
-H "Accept: application/json"
-d
'{
    "email_addresses":[
       {
          "primary":false,
          "verified":false,
          "value":"[email protected]"
       }
    ]
 }'
-X PUT http://idp-core.dev.onegini.me:8081/api/persons/<reference-id>

Please note that the property primary is set to false, it tells the Onegini IdP to modify the alternative email address.

Server responds with 204 Created status code after successfully completed operation. As mentioned before you can load person's profile to view updated data.

Delete email address

To remove person's email address you need to execute a request with an empty value for the email address. As an example let's assume that user want to delete alternative address.

It can be done by executing the following request:

curl -i --user username:password
-H "Content-Type: application/json"
-H "Accept: application/json"
-d
'{
    "email_addresses":[
       {
          "primary":false,
          "value":""
       }
    ]
 }'
-X PUT http://idp-core.dev.onegini.me:8081/api/persons/<reference-id>

Server responds with 204 Created status after successfully completed operation.