DOCUMENTATIONHome

Create Orders

Suggest Edits

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

Method: POST

Definitions

FieldTypeDescription
programidrequired
integer		The programid serves an identifier that determines the funding account and branding to use for this request.
clientidrequired
string(50)		Client provided unique identifier for the request. This field also serves as a duplicate transaction check. After a successful transaction is placed using this identifier, all subsequent requests using the same identifier are rejected as duplicate orders.
emailrequired
string(200)		Account holder email address.

Note: For anonymous rewards, please use a generic support email address, such as [email protected].
firstnamerequired
string(50)		Account holder first name.

Note: This field is displayed in the email and VRC salutation. For anonymous rewards, please use a generic name such as “Participant” or “Recipient”.
lastnamerequired
string(50)		Account holder last name.

Note: For anonymous rewards, please use a generic name such as “Participant” or “Recipient”.
skurequired
string(50)		Virtual prepaid product SKU requested.

Note: SKU document delivered separately.
amountrequired
decimal		The amount Denomination of the reward being issued.

Note: Currency is determined by the SKU requested.
address1string(100)Account holder address line 1.
address2string(50)Account holder address line 2.
citystring(50)Account holder city.
statestring(20)Account holder state abbreviation (ISO 3166-2, subdivision).
zipstring(10)Account holder zip code.
countrystring(2)Account holder country abbreviation (ISO 3166-2).
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.
phoneoptional
string(20)		Mobile phone number of the recipient. Used for SMS reward delivery. The number must be supplied as digits only.

Note: Required if reward delivery is SMS, or phone country is provided.
phonecountryoptional
string(2)		Mobile phone number country of origin. This is the 2-character country code (ISO 3166-2).

Note: Required if reward delivery is SMS, or phone number is provided.
w9eligibleoptional
string(5)		Determines the W9 Eligibility of a reward for 1099 reporting. Options are true or false.
w9idoptional
string(50)		The W9ID used for 1099 reporting.

Note: Required if w9eligible is true.
idresponse only
integer		Unique Account Holder ID.
numberresponse only
integer		Order number generated upon successful creation.
statusresponse only
string(50)		Order status of the requested order. See Appendix A for definitions.
linkresponse only
string(250)		Redemption link returned upon successful account creation.

Examples

Single Reward Request XML

<order> 
 <programid>26490</programid>
 <clientid>56258125</clientid>
 <accounts>
  <account>
  <firstname>John</firstname>
  <lastname>Doe</lastname>
  <email>[email protected]</email>
  <sku>UVC-V-A06</sku>
  <amount>10.00</amount>
  </account>
 </accounts>
</order>

Single Reward Response XML

<order>
 <programid>26490</programid>
 <clientid>56258125</clientid>
 <number>24681234</number>
 <status>completed</status>
 <accounts>
  <account>
   <id>88523</id>
   <firstname>John</firstname>
   <lastname>Doe</lastname>
   <email>[email protected]</email>
   <sku>UVC-V-A06</sku>
   <amount>10.00</amount>
   <link>
    https://www.virtualrewardcenter.com/
    Landing.aspx?id=88523&sid=093677BA-71FA-4137-B435-C17B1748E725
   </link>
  </account>
 </accounts>
</order>

Single Reward Request JSON

{
 "order": {
  "programid":"26490",
  "clientid":"56258125",
  "accounts":[
   {
   "firstname":"John",
   "lastname":"Doe",
   "email":"[email protected]",
   "sku":"UVC-V-A06",
   "amount":"10.00"
   }
  ]
 }
}

Single Reward Response JSON

{
 "order":{
  "programid":"26490",
  "clientid":"56258125",
  "number":"24681234",
  "status":"completed",
  "accounts":[
   {
    "id":"85425",
    "firstname":"John",
    "lastname":"Doe",
    "email":"[email protected]",
    "sku":"UVC-V-A06",
    "amount":"10.00",
    "link":"https://www.virtualrewardcenter.com/
     Landing.aspx?id=85425&sid=b173b47f-228c-4a97
     -8d68-e5835ca4ac66"
   }
  ]
 }
}

Multiple Rewards Request XML

<order> 
 <programid>26490</programid>
 <clientid>56258125</clientid>
 <accounts>
  <account>
   <firstname>John</firstname>
   <lastname>Doe</lastname>
   <email>[email protected]</email>
   <address1>123 Any Street</address1>
   <address2>Apt 212</address2>
   <city>Any City</city>
   <state>NY</state>
   <zip>98625</zip>
   <country>US</country>
   <sku>UVC-V-A06</sku>
   <amount>10.00</amount>
  </account>
  <account>
   <firstname>Jane</firstname>
   <lastname>Doe</lastname>
   <email>[email protected]</email>
   <sku>UVC-V-A06</sku>
   <amount>25.00</amount>
  </account>
 </accounts>
</order>

Multiple Rewards Response XML

<order>
 <programid>26490</programid>
 <clientid>56258125</clientid>
 <number>24681234</number>
 <status>completed</status>
 <accounts>
  <account>
   <id>88523</id>
   <firstname>John</firstname>
   <lastname>Doe</lastname>
   <email>[email protected]</email>
   <address1>123 Any Street</address1>
   <address2>Apt 212</address2>
   <city>Any City</city>
   <state>NY</state>
   <zip>98625</zip>
   <country>US</country>
   <sku>UVC-V-A06</sku>
   <amount>10.00</amount>
   <link>
    https://www.virtualrewardcenter.com/
    Landing.aspx?id=88523&sid=093677BA-71FA-4137-B435-C17B1748E725
   </link>
  </account>
  <account>
   <id>88523</id>
   <firstname>Jane</firstname>
   <lastname>Doe</lastname>
   <email>[email protected]</email>
   <sku>UVC-V-A06</sku>
   <amount>25.00</amount>
   <link>
    https://www.virtualrewardcenter.com/
    Landing.aspx?id=88523&sid=093677BA-71FA-4137-B435-C17B1748E725
   </link>
  </account>
 </accounts>
</order>

Multiple Rewards Request JSON

{
 "order": {
  "programid":"26490",
  "clientid":"56258125",
  "accounts":[
   {
    "firstname":"John",
    "lastname":"Doe",
    "email":"[email protected]",
    "address1":"123 Any Street",
    "address2":"Apt 212",
    "city":"Any City",
    "state":"NY",
    "zip":"98625",
    "country":"US",
    "sku":"UVC-V-A06",
    "amount":"10.00",
    "udf1":"",
    "udf2":""
   },
   {
    "firstname":"Jane",
    "lastname":"Doe",
    "email":"[email protected]",
    "sku":"UVC-V-A06",
    "amount":"25.00",
    "udf1":"",
    "udf2":""
   }
  ]
 }
}

Multiple Rewards Response JSON

{
 "order":{
  "programid":"26490",
  "clientid":"56258125",
  "number":"24681234",
  "status":"completed",
  "accounts":[
   {
    "id":"85425",
    "firstname":"John",
    "lastname":"Doe",
    "email":"[email protected]",
    "sku":"UVC-V-A06",
    "amount":"10.00",
    "link":"https://www.virtualrewardcenter.com/
     Landing.aspx?id=85425&sid=b173b47f-228c-4a97
     -8d68-e5835ca4ac66"
   }
   {
    "id":"85425",
    "firstname":"Jane",
    "lastname":"Doe",
    "email":"[email protected]",
    "sku":"UVC-V-A06",
    "amount":"10.00",
    "link":"https://www.virtualrewardcenter.com/
     Landing.aspx?id=85425&sid=b173b47f-228c-4a97
     -8d68-e5835ca4ac66"
   }
  ]
 }
}

Updated about 1 year ago