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.
What you need?
- configured Onegini IDP environment as described in quick start
- 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 number",
"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.