Get Recipients

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

FieldTypeDescription
idintegerThe unique id for this recipient.
emailstring(200)Account holder email address.
udf1string(100)Additional User Defined field.

Note: See ‘udf1’ for definition.
udf2string(100)Additional User Defined field.

Note: See ‘udf1’ for definition.
udf3string(1000)Additional User Defined field.

Note: See ‘udf1’ for definition.
udf4string(1000)Additional User Defined field.

Note: See ‘udf1’ for definition.
udf5string(1000)Additional User Defined field.

Note: See ‘udf1’ for definition.
udf6string(4000)Additional User Defined field.

Note: See ‘udf1’ for definition.
udf7string(4000)Additional User Defined field.

Note: See ‘udf1’ for definition.
udf8string(4000)Additional User Defined field.

Note: See ‘udf1’ for definition.
udf9string(4000)Additional User Defined field.

Note: See ‘udf1’ for definition.
udf10string(4000)Additional User Defined field.

Note: See ‘udf1’ for definition.
ordernumberintegerOrder 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"}]}}