Update Person

Introduction

This API updates one or more attributes of the specified person.

Method

Service Name

Service Type

PUT

personManagement/v1/person

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

Name

Type

Max. Length

Mandatory

Description

entityId

URI

255

N

A reference to the URI for the person

summary

Entity

N

The Person Summary entity

details

Entity

N

The Person Details entity

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 CodeError CodeDescription
400person.address.invalid.entityMultiple preferred addresses selected.
400person.email.invalid.entityMultiple preferred e-mail addresses selected.
400bhn.com.service.passed.invalid.entityMultiple preferred phone numbers selected.
400person.summary.nullSummary attribute is null.
400person.details.socialSecurityNumber.emptySocial Security number is empty.
400person.details.languagePreferenceCode.emptyLanguage preference code is empty.
400person.details.languagePreferenceCode.invalidLengthLanguage preference code length is is invalid. Maximum allowed length is 30
400person.details.socialSecurityNumber.invalidLengthSocial Security number length is invalid.
400person.summary.firstName.emptyFirstname is empty.
400person.summary.firstName.invalidLengthFirstname length is invalid. Maximum allowed length is 255.
400person.summary.middleName.emptyMiddlename is empty.
400person.summary.middleName.invalidLengthMiddlename length is invalid. Maximum allowed length is 255.
400person.summary.lastName.emptyMiddlename is empty.
400person.summary.lastName.invalidLengthMiddlename length is invalid. Maximum allowed length is 255.
400person.summary.emailAddress.invalidLengthE-mail address length is invalid. Maximum allowed length is 255.
400person.summary.emailAddress.invalidInvalid e-mail address.
400person.summary.phoneNumber.invalidLengthPhone number length is invalid. Maximum allowed length is 20.
400person.summary.street.invalidLengthStreet length is invalid. Maximum allowed length is 255.
400person.summary.addressline1.invalidLengthAddress Line1 length is invalid. Maximum allowed length is 255.
400person.summary.addressline2.invalidLengthAddress Line2 length is invalid. Maximum allowed length is 255.
400person.summary.addessline3.invalidLengthAddress Line3 length is invalid. Maximum allowed length is 255.
400person.summary.city.invalidLengthCity address length is invalid. Maximum allowed length is 255.
400person.summary.stateOrProvince.invalidLengthState or Province address length is invalid. Maximum allowed length is 255.
400person.summary.postalCode.invalidLengthPostal code length is invalid. Maximum allowed length is 255.
400person.details.addresses.name.invalidLengthName length is invalid. Allowed name length is 1-255.
400person.details.addresses.street.invalidLengthStreet length is invalid. Allowed name length is 1-255.
400person.details.addresses.addressline1.invalidLengthAddress Line1 length is invalid. Allowed name length is 1-255.
400person.details.addresses.addressline2.invalidLengthAddress Line2 length is invalid. Allowed name length is 1-255.
400person.details.addresses.addressline3.invalidLengthAddress Line3 length is invalid. Allowed name length is 1-255.
400person.details.addresses.city.invalidLengthCity length is invalid. Allowed name length is 1-255.
400person.details.addresses.countyOrDistrict.invalidLengthCounty/District length is invalid. Allowed name length is 1-255.
400person.details.addresses.stateOrProvince.invalidLengthState/Province length is invalid. Allowed name length is 1-255.
400person.details.addresses.country.invalidLengthCountry length is invalid. Allowed name length is 1-100.
400person.details.addresses.postalCode.invalidLengthPostal code length is invalid. Allowed name length is 1-20.
400person.details.addresses.addressType.nullAddress type is null. Allowed address type values are [HOME, WORK, BILLING, SHIPPING, OTHER].
400person.details.birthDate.invalidBirthdate field has a value less than or equal to 150 years in the past.
400person.details.phoneNumbers.phoneNumber.emptyPhone number is empty
400person.details.phoneNumbers.phoneNumber.invalidLengthPhone number length is invalid. Maximum allowed length is 20.
400person.details.phoneNumbers.phoneNumber.nullPhone number is null
400person.details.emailAddresses.emailAddress.nullEmail address is null
400person.details.emailAddresses.emailAddress.emptyEmail address is empty
400person.details.emailAddresses.emailAddress.invalidLengthEmail address length is invalid. Maximum allowed length is 255
400person.details.emailAddresses.emailAddress.invalidEmail address invalid
400person.details.emailAddresses.emailType.nullEmail type is null
400person.details.identificationNumber.emptyIdentification number is empty
400person.details.identificationNumber.invalidLengthIdentification number length is invalid. Maximum allowed length is 100
400person.details.issuingAuthority.emptyIssuing authority is empty
400person.details.issuingAuthority.invalidLengthIssuing authority length is is invalid. Maximum allowed length is 100
400person.details.phoneNumbers.phoneNumberType.nullPhone Number type is null
404attempt.to.update.nonexistent.enityEntity 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"
         }
      ]
   }
}

Did this page help you?