Endpoint: https://rest.virtualincentives.com/{version}/{format}/recipients

Method: GET

Filtering Recipients by Email, UDF, and Order Number

You can filter the recipients through the query string parameters using any combination of Email, UDF, and Order Number. See these specific pages for more information.

📘
Filtering by email, UDF, and Order Number is only available with your production credentials.

Paging and Limiting Results: The API supports returning a maximum of 1,000 results per page. You can limit the number of results by specifying the number in the “limit” query string. The default number of results returned is 100.

Your initial call will return the following variables

page: this is the current page of results you are viewing
count: number of results on the current page
more: this is a boolean value which specifies whether there are more pages available
total: this is the total number of recipients from your specific query

Definitions

Field	Type	Description
id	integer	The unique id for this recipient.
email	string(200)	Account holder email address.
udf1	string(100)	Additional User Defined field. Note: See ‘udf1’ for definition.
udf2	string(100)	Additional User Defined field. Note: See ‘udf1’ for definition.
udf3	string(1000)	Additional User Defined field. Note: See ‘udf1’ for definition.
udf4	string(1000)	Additional User Defined field. Note: See ‘udf1’ for definition.
udf5	string(1000)	Additional User Defined field. Note: See ‘udf1’ for definition.
udf6	string(4000)	Additional User Defined field. Note: See ‘udf1’ for definition.
udf7	string(4000)	Additional User Defined field. Note: See ‘udf1’ for definition.
udf8	string(4000)	Additional User Defined field. Note: See ‘udf1’ for definition.
udf9	string(4000)	Additional User Defined field. Note: See ‘udf1’ for definition.
udf10	string(4000)	Additional User Defined field. Note: See ‘udf1’ for definition.
ordernumber	integer	Order number that this recipient is related to.

Examples

XML Example

<response>
  <page>1</page>
  <more>false</more>
  <count>2</count>
  <total>2</total>

  <recipients>
    <recipient>
      <id>77549</id>
      <email>[email protected]</email>
      <ordernumber>24683267</ordernumber>
    </recipient>
    <recipient>
      <id>77550</id>
      <email>[email protected]</email>
      <udf1>Sample</udf1>
      <ordernumber>24683267</ordernumber>
    </recipient>
    </recipients>
   </response>

JSON Example

{"response":{
"Page":1,
"More":false,
"Count":2,
"Total":2,

"Recipients":[
{"id":"77549",
"email":"[email protected]",
"Ordernumber":"24683267"},
{"id":"77550",
"email":"[email protected]",
"udf1":"Sample",
"Ordernumber":"24683267"}]}}

XML ‘page’ Example

<response>
  <page>10</page>
  <more>true</more>
  <count>2</count>
  <total>157101</total>

  <recipients>
    <recipient>
      <id>78456</id>
      <email>[email protected]</email>
      <ordernumber>24683280</ordernumber>
    </recipient>
    <recipient>
      <id>78457</id>
      <email>[email protected]</email>
      <ordernumber>24683280</ordernumber>
    </recipient>
</recipients>
</response>

JSON ‘page’ Example

{"response":{
"Page":10,
"More":true,
"Count":2,
"Total":157101,

"Recipients":[
{"id":"78456",
"email":"[email protected]",
"Ordernumber":"24683280"},

{"id":"78457",
"email":"[email protected]",
"Ordernumber":"24683280"}]}}

XML ‘limit’ Example

<response>
  <page>1</page>
  <more>true</more>
  <count>3</count>
  <total>157101</total>

  <recipients>
    <recipient>
      <id>77549</id>
      <email>[email protected]</email>
      <ordernumber>24683267</ordernumber>
    </recipient>
    <recipient>
      <id>77550</id>
      <email>[email protected]</email>
      <udf1>Sample</udf1>
      <ordernumber>24683267</ordernumber>
    </recipient>
    <recipient>
      <id>77551</id>
      <email>[email protected]</email>
      <ordernumber>24683268</ordernumber>
    </recipient>
  </recipients>
</response>

JSON ‘limit’ Example

{"response":{
"Page":1,
"More":true,
"Count":3,
"Total":157101,

"Recipients":[
{"id":"77549",
"email":"[email protected]",
"Ordernumber":"24683267"},

{"id":"77550",
"email":"[email protected]",
"udf1":"Sample",
"Ordernumber":"24683267"},

{"id":"77551",
“email”:”[email protected]”,
"ordernumber":"24683268"}]}}