Query People By Criteria

Introduction

This API returns a list of summary information about a subset of the people that meet the specified criteria and cursor view parameters.

Method

Service Name

Service Type

GET

personManagement/v1/people

URI: https://api.blackhawknetwork.com/personManagement/v1/people?{summary|details}.{attributeName}={attributeValue}&{first}={firstIndex}&{maximum}={maximumNumofEntries}&{sortKey}=(summary|details).{attributeName}&{ascending}={true|false}

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

first

String

No

The index of the first entity in this cursor view of the list. The default first index is zero referring to the first entity in the full list.

maximum

String

No

The maximum number of entities to be shown in this cursor view of the list.

sortKey

String

No

The name of the attribute that should be used for ordering the results. If this value is not provided, then there is no explicit sorting of the results.

ascending

String

No

Whether or not the results are sorted in ascending order.

Response Elements

Name

Type

Description

personSummaryList

List

List of matching Person Summary entities

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

Sample Request and Response

GET /personManagement/v1/people?first=0&maximum=10&sortKey=summary.lastName&ascending=true&exactMatch=false&caseSensitive=false&eq(summary.firstName,ji)&ge(details.createdTimestamp,2011-01-01T21:12:00.000%2B0000)&le(details.createdTimestamp,2020-01-01T21:12:00.000%2B0000) HTTP/1.1
requestorId: RZ2JMRQW0SM680Q0MF2M8FBFMR
Content-Type: application/json; charset=UTF-8
Accept: application/json; charset=UTF-8
Host: api.blackhawknetwork.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.2 (java 1.5)
HTTP/1.1 200 OK
Content-Type: application/json;charset=ISO-8859-1 
Date=Tue, 15 Jan 2013 22:27:33 GMT
Content-Length=2016
Keep-Alive: timeout=5, max=100 
Connection: Keep-Alive
 
{ 
  "parameters" : { 
    "ascending" : true, 
    "first" : 0, 
    "maximum" : 10, 
    "sortKey" : "summary.lastName" 
  }, 
  "results" : [ 
      { 
        "city" : "Anytown", 
        "emailAddress" : [email protected], 
        "entityId" : "https://api.blackhawknetwork.com/personManagement/v1/person/JV9TVQXZ9QD904SGWBZQ4XCSXH", 
        "firstName" : "Jim", 
        "lastName" : "Jameson", 
        "phoneNumber" : "555-1212", 
        "stateOrProvince" : "Illinois", 
        "street" : "123 Main Street",
        "postalCode":"12345" 
      }, 
      { 
        "city" : "Anytown", 
        "emailAddress" : [email protected], 
        "entityId" : "https://api.blackhawknetwork.com/personManagement/v1/person/NCVFVZRWKS5TT6QVFMR0Y4QA1W", 
        "firstName" : "Jim", 
        "lastName" : "Jameson", 
        "phoneNumber" : "555-1212", 
        "stateOrProvince" : "Illinois", 
        "street" : "123 Main Street",
        "postalCode":"12345" 
      } 
  ], 
  "total" : 2 
}

Did this page help you?