Update Person
Introduction
This API updates one or more attributes of the specified person.
Method | Service Name | Service Type |
---|---|---|
PUT | 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 |
person | Person | Yes | The person to be updated |
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 Code | Error Code | Description |
---|---|---|
400 | person.address.invalid.entity | Multiple preferred addresses selected. |
400 | person.email.invalid.entity | Multiple preferred e-mail addresses selected. |
400 | bhn.com.service.passed.invalid.entity | Multiple preferred phone numbers selected. |
400 | person.summary.null | Summary attribute is null. |
400 | person.details.socialSecurityNumber.empty | Social Security number is empty. |
400 | person.details.languagePreferenceCode.empty | Language preference code is empty. |
400 | person.details.languagePreferenceCode.invalidLength | Language preference code length is is invalid. Maximum allowed length is 30 |
400 | person.details.socialSecurityNumber.invalidLength | Social Security number length is invalid. |
400 | person.summary.firstName.empty | Firstname is empty. |
400 | person.summary.firstName.invalidLength | Firstname length is invalid. Maximum allowed length is 255. |
400 | person.summary.middleName.empty | Middlename is empty. |
400 | person.summary.middleName.invalidLength | Middlename length is invalid. Maximum allowed length is 255. |
400 | person.summary.lastName.empty | Middlename is empty. |
400 | person.summary.lastName.invalidLength | Middlename length is invalid. Maximum allowed length is 255. |
400 | person.summary.emailAddress.invalidLength | E-mail address length is invalid. Maximum allowed length is 255. |
400 | person.summary.emailAddress.invalid | Invalid e-mail address. |
400 | person.summary.phoneNumber.invalidLength | Phone number length is invalid. Maximum allowed length is 20. |
400 | person.summary.street.invalidLength | Street length is invalid. Maximum allowed length is 255. |
400 | person.summary.addressline1.invalidLength | Address Line1 length is invalid. Maximum allowed length is 255. |
400 | person.summary.addressline2.invalidLength | Address Line2 length is invalid. Maximum allowed length is 255. |
400 | person.summary.addessline3.invalidLength | Address Line3 length is invalid. Maximum allowed length is 255. |
400 | person.summary.city.invalidLength | City address length is invalid. Maximum allowed length is 255. |
400 | person.summary.stateOrProvince.invalidLength | State or Province address length is invalid. Maximum allowed length is 255. |
400 | person.summary.postalCode.invalidLength | Postal code length is invalid. Maximum allowed length is 255. |
400 | person.details.addresses.name.invalidLength | Name length is invalid. Allowed name length is 1-255. |
400 | person.details.addresses.street.invalidLength | Street length is invalid. Allowed name length is 1-255. |
400 | person.details.addresses.addressline1.invalidLength | Address Line1 length is invalid. Allowed name length is 1-255. |
400 | person.details.addresses.addressline2.invalidLength | Address Line2 length is invalid. Allowed name length is 1-255. |
400 | person.details.addresses.addressline3.invalidLength | Address Line3 length is invalid. Allowed name length is 1-255. |
400 | person.details.addresses.city.invalidLength | City length is invalid. Allowed name length is 1-255. |
400 | person.details.addresses.countyOrDistrict.invalidLength | County/District length is invalid. Allowed name length is 1-255. |
400 | person.details.addresses.stateOrProvince.invalidLength | State/Province length is invalid. Allowed name length is 1-255. |
400 | person.details.addresses.country.invalidLength | Country length is invalid. Allowed name length is 1-100. |
400 | person.details.addresses.postalCode.invalidLength | Postal code length is invalid. Allowed name length is 1-20. |
400 | person.details.addresses.addressType.null | Address type is null. Allowed address type values are [HOME, WORK, BILLING, SHIPPING, OTHER]. |
400 | person.details.birthDate.invalid | Birthdate field has a value less than or equal to 150 years in the past. |
400 | person.details.phoneNumbers.phoneNumber.empty | Phone number is empty |
400 | person.details.phoneNumbers.phoneNumber.invalidLength | Phone number length is invalid. Maximum allowed length is 20. |
400 | person.details.phoneNumbers.phoneNumber.null | Phone number is null |
400 | person.details.emailAddresses.emailAddress.null | Email address is null |
400 | person.details.emailAddresses.emailAddress.empty | Email address is empty |
400 | person.details.emailAddresses.emailAddress.invalidLength | Email address length is invalid. Maximum allowed length is 255 |
400 | person.details.emailAddresses.emailAddress.invalid | Email address invalid |
400 | person.details.emailAddresses.emailType.null | Email type is null |
400 | person.details.identificationNumber.empty | Identification number is empty |
400 | person.details.identificationNumber.invalidLength | Identification number length is invalid. Maximum allowed length is 100 |
400 | person.details.issuingAuthority.empty | Issuing authority is empty |
400 | person.details.issuingAuthority.invalidLength | Issuing authority length is is invalid. Maximum allowed length is 100 |
400 | person.details.phoneNumbers.phoneNumberType.null | Phone Number type is null |
404 | attempt.to.update.nonexistent.enity | Entity does not exist. |
Sample Request and Response
PUT /personManagement/v1/person/0WXHWZQ7KJ2WQFAMQG1A0FVX8H HTTP/1.1
requestorId: RZ2JMRQW0SM680Q0MF2M8FBFMR
Content-Type: application/json; charset=UTF-8
Accept: application/json; charset=UTF-8
Content-Length: 759
Host: api.blackhawknetwork.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.2 (java 1.5)
{
"summary":{
"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":{
"additionalAttributes": [{
"name": "optIn",
"type": "boolean",
"value": "false"
}],
"gender": "MALE",
"birthDate": "2012-03-05",
"socialSecurityNumber": "123-45-6789",
"languagePreferenceCode": "en_US",
"addresses": [{
"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
}],
"phoneNumbers": [{
"phoneNumber": "555-1212",
"phoneNumberType": "HOME",
"isPreferred": true
}],
"emailAddresses": [{
"emailAddress": "[email protected]",
"emailType": "WORK",
"isPreferred": true
}]
}
}
HTTP/1.1 200 OK
Date: Fri, 06 Jul 2012 21:04:35 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 1722
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
{
"entityId":http://api.blackhawknetwork.com:/personManagement/v1/person/0WXHWZQ7KJ2WQFAMQG1A0FVX8H,
"summary":{
"entityId":http://api.blackhawknetwork.com:/personManagement/v1/person/0WXHWZQ7KJ2WQFAMQG1A0FVX8H,
"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