Read Person
Introduction
This API retrieves the full person information for the specified person identifier.
Method | Service Name | Service Type |
---|---|---|
GET | personManagement/v1/person |
- Post-Production URI:
https://api.certification.blackhawknetwork.com/personManagement/v1/person/{personId}
- Production URI:
https://api.blackhawknetwork.com/personManagement/v1/person/{personId}
Request Header Attributes
All of these header attributes are optional; however, if a client wants idempotency support then they should specify all three on every request.
Name | Type | Mandatory | Description |
---|---|---|---|
requestorId | String | N | A value defined by the client application that can be used to uniquely identify that client application. If the client application does not specify a value, a globally unique identifier will be filled in automatically. |
requestId | String | N | A value defined by the client application that can be used to uniquely identify that specific request from the client. This value should be set if the client application wants to take advantage of an idempotent operation on a service. |
previousAttempts | Integer | N | The number of times this same request has been attempted unsuccessfully before. A value that is greater than zero will cause the service to view this request as a retry attempt and it will be treated idempotently. |
Request Elements
Name | Type | Required | Description |
---|---|---|---|
personId | String | Yes | The internal identifier of the person |
Response Elements
Name | Type | Description |
---|---|---|
person | person | The fully initialized newly created person. |
Person
Person Summary
Name | Type | Max. Length | Mandatory | Description |
---|---|---|---|---|
entityId | URI | 255 | N | A reference to the URI for the person |
firstName | String | 255 | N | First name of the person |
middleName | String | 255 | N | Middle name of the person |
lastName | String | 255 | N | Last name of the person |
emailAddress | String | 255 | N | Email address of the person. It is a read only field. |
phoneNumber | String | 255 | N | Phone number of the person. It is a read only field. |
street | String | 255 | N | Street address of the person. It is a read only field. |
addressLine1 | String | 255 | N | Address Line1 of the person. It is a read only field. |
addressLine2 | String | 255 | N | Address Line2 of the person. It is a read only field. |
addressLine3 | String | 255 | N | Address Line3 of the person. It is a read only field. |
city | String | 255 | N | City of the person. It is a read only field. |
stateOrProvince | String | 255 | N | State or Province of the person. It is a read only field. |
postalCode | String | 20 | N | The postal code |
Person Details
Name | Type | Max. Length | Mandatory | Description |
---|---|---|---|---|
creatorId | URI | 255 | N | A reference to the URI for the person that created the entity |
updaterId | URI | 255 | N | A reference to the URI for the person that last updated the entity |
notes | String | 255 | N | Any notes associated with the last update of the entity |
createdTimestamp | Date | N | The date and time that this entity was created | |
updatedTimestamp | Date | N | The date and time that this entity was last updated | |
additionalAttributes | List | N | List of PersonEntityAttribute entity | |
gender | Enum | N | The Gender enumeration value | |
birthDate | String | N | Birth date of the person | |
socialSecurityNumber | String | 100 | N | Social security number of the person |
languagePreferenceCode | String | 30 | N | Preferred language code of the person |
addresses | List | N | List of Person Address entities | |
phoneNumbers | List | N | List of Person Phone Number entities | |
emailAddresses | List | N | List of Person Email entities | |
personIdentifications | List | N | List of Person Identification entities |
Gender
Enum Value | Description |
---|---|
FEMALE | Female |
MALE | Male |
Person Address
Name | Type | Max. Length | Mandatory | Description |
---|---|---|---|---|
id | String | 26 | N | The primary key for this entity |
name | String | 255 | Y | The name of the person at the address |
street | String | 255 | Y | The street address |
city | String | 255 | Y | The city |
addressLine1 | String | 255 | N | Address Line1 |
addressLine2 | String | 255 | N | Address Line2 |
addressLine3 | String | 255 | N | Address Line3 |
countyOrDistrict | String | 255 | N | The county or district |
stateOrProvince | String | 255 | Y | The state or province |
country | String | 100 | Y | The country |
postalCode | String | 20 | Y | The postal code |
addressType | Enum | Y | The Address Type enumeration value | |
isPreferred | Boolean | N | Whether or not this address is the person's preferred address. Allowed values: true/false (case sensitive) | |
isVerified | Boolean | N | If this address is verified or not |
Address Type
Enum Value | Description |
---|---|
HOME | Home |
WORK | Work |
BILLING | Billing |
SHIPPING | Shipping |
OTHER | Other |
Person Phone Number
Name | Type | Max. Length | Mandatory | Description |
---|---|---|---|---|
id | String | 26 | N | The primary key for this entity |
phoneNumber | String | 20 | Y | The person's phone number |
phoneNumberType | Enum | Y | The Phone Number Type enumeration value | |
isPreferred | Boolean | N | Whether or not this phone number is this person's preferred phone number Allowed values: true/false (case sensitive) | |
isVerified | Boolean | N | If this phone number is verified or not |
Phone Number Type
Enum Value | Description |
---|---|
HOME | Home Phone |
MOBILE | Mobile Phone |
WORK | Work Phone |
FAX | Fax Machine Number |
OTHER | Other Phone |
Person Email
Name | Type | Max. Length | Mandatory | Description |
---|---|---|---|---|
id | String | 26 | N | The primary key for this entity |
emailAddress | String | 255 | Y | Person's email address |
isPreferred | Boolean | N | Whether or not this email address is this person's preferred email. Allowed values: true/false (case sensitive) | |
isVerified | Boolean | N | If this email is verified or not | |
emailType | Enum | Y | The Email Type enumeration value |
Email Type
Enum Value | Description |
---|---|
PERSONAL | Personal Email Address |
WORK | Work Email Address |
OTHER | Other Email Address |
Person Identification
Name | Type | Max. Length | Mandatory | Description |
---|---|---|---|---|
id | String | 26 | N | The primary key for this entity |
createdTimestamp | Date | N | The date and time that this Person Identification entity was created. | |
updatedTimestamp | Date | N | The date and time that this Person Identification entity was last updated. | |
identificationNumber | String | 255 | Y | identification number |
issuingAuthority | String | 255 | Y | who issued the identification number |
isVerified | Boolean | N | If this identification is verified or not. | |
identification Type | Enum | Y | The Identification Type enumeration value |
Identification Type
Enum Value | Description |
---|---|
PARTNER_ID | Partner ID |
DRIVERS_LICENSE | Driver License |
PASSPORT | Passport |
GOVERMENT_ID_CARD | Government Issued ID Card |
AMERICAN_INDIAN_TRIBAL_ID | American Indian Tribal ID |
GREEN_CARD | USCIS Permanent Resident Card (Green Card) |
MILITARY_ID | Military ID |
Error Codes
HTTP Status Code | Error Code | Description |
---|---|---|
404 | attempt.to.retrieve.nonexistent.enity | Entity does not exist. |
Sample Request and Response
GET https://apipp.blackhawknetwork.com/personManagement/v1/person/X5T3FM3MZZ23CHMZDC7M2Q4LKH HTTP/1.1
Accept-Encoding: gzip,deflate
requestorId: 8YQ1LV7VW3J88DQFNJ0VNX8NG4
tenantId: NWFZKLN0ATAFPWQWG3X62A6LP4
Host: apipp.blackhawknetwork.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
{
"entityId": "https://apipp.blackhawknetwork.com/personManagement/v1/person/X5T3FM3MZZ23CHMZDC7M2Q4LKH",
"summary": {
"entityId": "https://apipp.blackhawknetwork.com/personManagement/v1/person/X5T3FM3MZZ23CHMZDC7M2Q4LKH",
"firstName": "Jim",
"middleName": "Bob",
"lastName": "Jameson",
"emailAddress": "[email protected]",
"phoneNumber": "555-1212",
"street": "123 Main Street",
"addressLine1": "123 Main Street",
"addressLine2": "Apartment number 3A",
"addressLine3": "3rd Floor",
"city": "Anytown",
"stateOrProvince": "Illinois",
"postalCode": "12345"
},
"details": {
"creatorId": "https://apipp.blackhawknetwork.com/personManagement/v1/person/HPCDKMSV763K2VGHCKQQ09QSGM",
"updaterId": "https://apipp.blackhawknetwork.com/personManagement/v1/person/HPCDKMSV763K2VGHCKQQ09QSGM",
"createdTimestamp": "2014-11-18T18:50:31.526+0000",
"updatedTimestamp": "2014-11-18T18:50:31.526+0000",
"additionalAttributes": [ {
"id": "F948A4P826JC8ASF65LWAAPLA4",
"name": "optIn",
"type": "boolean",
"value": "false",
"createdTimestamp": "2014-11-18T18:50:31.526+0000",
"updatedTimestamp": "2014-11-18T18:50:31.526+0000"
}],
"gender": "MALE",
"birthDate": "2012-03-05",
"socialSecurityNumber": "123-45-6789",
"languagePreferenceCode": "en_US",
"addresses": [ {
"id": "ZQRK1V83NJG17B9L705F4C94WW",
"name": "Jim Jameson",
"street": "123 Main Street",
"addressLine1": "123 Main Street",
"addressLine2": "Apartment number 3A",
"addressLine3": "3rd Floor",
"city": "Anytown",
"stateOrProvince": "Illinois",
"country": "USA",
"postalCode": "12345",
"addressType": "HOME",
"isPreferred": true,
"createdTimestamp": "2014-11-18T18:50:31.526+0000",
"updatedTimestamp": "2014-11-18T18:50:31.526+0000"
}],
"phoneNumbers": [ {
"id": "BS20RPX1GFS46KWAGX0RK8X7Y8",
"phoneNumber": "555-1212",
"phoneNumberType": "HOME",
"isPreferred": true,
"createdTimestamp": "2014-11-18T18:50:31.526+0000",
"updatedTimestamp": "2014-11-18T18:50:31.526+0000"
}],
"emailAddresses": [ {
"id": "2CJY86J5ZZPVYXLSMAQ5R2360W",
"emailAddress": "[email protected]",
"emailType": "WORK",
"isPreferred": true,
"createdTimestamp": "2014-11-18T18:50:31.526+0000",
"updatedTimestamp": "2014-11-18T18:50:31.526+0000"
}],
"personIdentifications": []
}
}
{
"entityId":"http//api.blackhawknetwork.com:/personManagement/v1/person/1WPWXFT3AHT19P2QGPZ90B9A3M",
"summary":{
"entityId":"http//api.blackhawknetwork.com:/personManagement/v1/person/1WPWXFT3AHT19P2QGPZ90B9A3M",
"firstName":"Jim",
"middleName":"Bob",
"lastName":"Jameson",
"emailAddress":"[email protected]",
"phoneNumber":"555-1212",
"street":"123 Main Street",
"addressLine1": "123 Main Street",
"addressLine2": "Apartment number 3A",
"addressLine3": "3rd Floor",
"city":"Anytown",
"stateOrProvince":"Illinois",
"postalCode":"12345"
},
"details":{
"creatorId":"RZ2JMRQW0SM680Q0MF2M8FBFMR",
"updaterId":"RZ2JMRQW0SM680Q0MF2M8FBFMR",
"createdTimestamp":"2012-09-25T19:21:44.911+0000",
"updatedTimestamp":"2012-09-25T19:21:44.911+0000",
"additionalAttributes":[
{
"id":"WVTTZF13BQV4HVTKBKH0Q643LH",
"name":"optIn",
"type":"boolean",
"value":"false",
"createdTimestamp":"2012-09-25T19:21:44.912+0000",
"updatedTimestamp":"2012-09-25T19:21:44.912+0000"
}
],
"gender":"MALE",
"birthDate":"2012-03-05",
"socialSecurityNumber":"123-45-6789",
"languagePreferenceCode":"en_US",
"addresses":[
{
"id":"LJKM3AV7C2C8CFZ2077TJY7R8H",
"name":"Jim Jameson",
"street":"123 Main Street",
"addressLine1": "123 Main Street",
"addressLine2": "Apartment number 3A",
"addressLine3": "3rd Floor",
"city":"Anytown",
"stateOrProvince":"Illinois",
"country":"USA",
"postalCode":"12345",
"addressType":"HOME",
"isPreferred":true,
"createdTimestamp":"2012-09-25T19:21:44.911+0000",
"updatedTimestamp":"2012-09-25T19:21:44.911+0000"
}
],
"phoneNumbers":[
{
"id":"3ALAL33J1D0S5Y5ARY9ZSPQJY4",
"phoneNumber":"555-1212",
"phoneNumberType":"HOME",
"isPreferred":true,
"createdTimestamp":"2012-09-25T19:21:44.911+0000",
"updatedTimestamp":"2012-09-25T19:21:44.911+0000" }
],
"emailAddresses":[
{
"id":"CYF8T0MBHF1JCHSGTDVSTM3S2R",
"emailAddress":"[email protected]",
"emailType":"WORK",
"isPreferred":true,
"createdTimestamp":"2012-09-25T19:21:44.911+0000",
"updatedTimestamp":"2012-09-25T19:21:44.911+0000"
}
]
}
}
Updated 4 months ago