Create Orders

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.
fulfillmentrequired
string(50)
Allowed values are bulk or individual.
For virtual rewards:
- bulk returns the reward link in the API response.
- individual rewards are emailed directly to the recipient.

For physical rewards:
- bulk rewards are shipped via courier to a single address specified in the shipping object.
- individual rewards are sent via USPS directly to the recipient.
shippingobjectThis field is required only for bulk physical rewards. It contains the address which the courier will deliver the bulk order.
shipping.companystring(100)The name of your company.
shipping.attentionstring(100)The name of the person within your organization who should receive the bulk package.
shipping.address1string(100)Courier address line 1.
shipping.address2string(50)Courier address line 2.
shipping.citystring(50)Courier city line.
shipping.statestring(20)Courier state abbreviation (ISO 3166-2, subdivision)..
string.zipstring(50)Courier zip code line.
string.countrystring(2)Courier country abbreviation line (ISO 3166-2).
emailstring(200)Account holder email address. Required for virtual rewards only.

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.

Pass a unique Reload ID here when creating or loading a Reloadable card or cash payout.

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.
identityobjectAccount holder information used for identity verification.

Note: Required for the initial order of a Cash Payout API First product. Do not provide for reload orders.
first_namestring(50)Legal first name of the account holder. This information must match what's on the account holder's government issued drivers license or ID card.
last_namestring(50)Legal last name of the account holder. This information must match what's on the account holder's government issued drivers license or ID card.
date_of_birthstring(10)Account holder's date of birth.

Format: MM/DD/YYYY
ssn_last_fourinteger (4)Last 4 digits of the account holder's social security number.
bankobjectAccount holder's checking account or debit card information in which payouts will be sent.

Note: Required for the initial order of a Cash Payout API First product. Do not provide for reload orders.
typestring(12)Type of payout destination. Options are bank_account or debit_card.
account_numberinteger (14)Account number associated with the account holder's checking account.
routing_numberinteger (9)Routing number associated with the account holder's checking account.
card_numberinteger (16)16 digit card number associated with the account holder's debit card.
expirationinteger (4)4 digit expiration associated with the account holder's debit card.

Format: MMYY
cvvinteger (3)3 digit security code associated with the account holder's debit card.
transfer_notestring (255)Custom note for the payout credit. Defaults to "Payout from {Customer Name}" if no note is provided.
payout_notestring (255)Custom note for the payout debit. Defaults to "Payment to Cardholder Account Ending {1234}" if no note is provided.
accepted_partner_termsstring (5)Confirmation that the account holder has reviewed and agreed to the terms and conditions. Options are true or false.

Note: Required for the initial order of a Cash Payout API First product. Optional for reload orders.
ip_addressstring (15)Account holder's IP address. Must be IPV4 formatted and a public IP Address. Ex: "24.98.120.43"

Note: Required for the initial order of a Cash Payout API First product. Optional for reload orders.
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>26002</programid>
  <clientid>REST v6</clientid>
  <fulfillment>Bulk</fulfillment> 
  <shipping>
	<company>Sample Company</company> 
	<attention>Sample Attention</attention>
	<address1>123 Any Street</address1> 
	<address2>Apt 212</address2>   
	<city>Any City</city> 
	<state>NY</state> 
	<zip>98625</zip> 
	<country>US</country> 
  </shipping>
 <accounts>
  <account>
   <firstname>Reward</firstname>
      <lastname>Recipient</lastname>
      <email>[email protected]</email>
      <address1>123 Any Address</address1>
      <city>Any City</city>
      <state>NY</state>
      <zip>98625</zip>
      <country>US</country>
      <sku>UVC-P-V03</sku>
      <currency>USD</currency>
      <amount>10.00</amount>
      <w9eligible>true</w9eligible>
      <w9id>261330</w9id>
  </account>
 </accounts>
</order>

Single Reward Response XML

<order>
  <programid>26002</programid>
  <clientid>REST v6</clientid>
  <fulfillment>bulk</fulfillment>
  <shipping>
    <company>Sample Company</company>
    <attention>Sample Attention</attention>
    <address1>123 Any Street</address1>
    <address2>Apt 212</address2>
    <city>Any City</city>
    <state>NY</state>
    <zip>98625</zip>
    <country>US</country>
  </shipping>
  <number>24693500</number>
  <status>processing</status>
  <accounts>
    <account>
      <id>261330</id>
      <firstname>Reward</firstname>
      <lastname>Recipient</lastname>
      <email>[email protected]</email>
      <address1>123 Any Address</address1>
      <city>Any City</city>
      <state>NY</state>
      <zip>98625</zip>
      <country>US</country>
      <sku>UVC-P-V03</sku>
      <currency>USD</currency>
      <amount>10.00</amount>
      <w9eligible>true</w9eligible>
      <w9id>261330</w9id>
      <link />
    </account>
  </accounts>
</order>

Single Reward Request JSON

{
    "order": {
        "programid": "26002",
        "clientid": "9749363",
        "fulfillment": "bulk",
        "shipping": {
            "company": "Sample Company",
            "attention": "Sample",
            "address1": "Any Address",
            "address2": "Apt 212",
            "city": "Any City",
            "state": "NY",
            "zip": "98625",
            "country": "US"
        },
        "accounts": [
            {
                "firstname": "Reward",
                "lastname": "Recipient",
                "email": "[email protected]",
                "sku": "UVC-P-V03",
                "amount": "10.00",
                "address1": "Any Address",
                "city": "Any City",
                "state": "NY",
                "zip": "98625",
                "country": "US"
            }
        ]
    }
}

Single Reward Response JSON

{
"Order":{
"Programid":"26002",
"Clientid":"9749363",
"Fulfillment":"bulk",
"Shipping":{
"company":"Sample Company",
"attention":"Sample",
"address1":"Any Address",
"address2":"Apt 212",
"city":"Any City",
"state":"NY",
"Zip":"98625",
"country":"US"
},
"Number":"24693503",
"Status":"processing",
"Accounts":[
{"id":"261333",
"firstname":"Reward",
"lastname":"Recipient",
"email":"[email protected]",
"address1":"Any Address","city":"Any City",
"state":"NY",
"Zip":"98625",
"country":"US",
"sku":"UVC-P-V03",
"currency":"USD",
"Amount":"10.00",
"Link":""
     }
    ]
   }
  }
}

Multiple Rewards Request XML

<order> 
 <programid>26002</programid>
 <clientid>56258126</clientid>
   <fulfillment>bulk</fulfillment>
   <shipping>
           <company>Sample Company</company>
           <attention>Sample</attention>
           <address1>123 Any Street</address1> 
	<address2>Apt 212</address2>   
	<city>Any City</city> 
	<state>NY</state> 
	<zip>98625</zip> 
	<country>US</country>
    </shipping>
 <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-P-V03</sku>
   <amount>10.00</amount>
  </account>
  <account>
   <firstname>Jane</firstname>
   <lastname>Doe</lastname>
   <email>[email protected]</email>
           <address1>124 Any Street</address1>
   <address2>Apt 214</address2>
   <city>Any City</city>
   <state>NY</state>
   <zip>98625</zip>
   <country>US</country>
   <sku>UVC-P-V03</sku>
   <amount>25.00</amount>
  </account>
 </accounts>
</order>

Multiple Rewards Response XML

<order>
  <programid>26002</programid>
  <clientid>56258126</clientid>
  <fulfillment>bulk</fulfillment>
  <shipping>
    <company>Sample Company</company>
    <attention>Sample</attention>
    <address1>123 Any Street</address1>
    <address2>Apt 212</address2>
    <city>Any City</city>
    <state>NY</state>
    <zip>98625</zip>
    <country>US</country>
  </shipping>
  <number>24693506</number>
  <status>processing</status>
  <accounts>
    <account>
      <id>261337</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-P-V03</sku>
      <currency>USD</currency>
      <amount>10.00</amount>
      <link />
    </account>
    <account>
      <id>261338</id>
      <firstname>Jane</firstname>
      <lastname>Doe</lastname>
      <email>[email protected]</email>
      <address1>124 Any Street</address1>
      <address2>Apt 214</address2>
      <city>Any City</city>
      <state>NY</state>
      <zip>98625</zip>
      <country>US</country>
      <sku>UVC-P-V03</sku>
      <currency>USD</currency>
      <amount>25.00</amount>
      <link />
    </account>
  </accounts>
</order>

Multiple Rewards Request JSON

{
    "order": {
        "programid": "26002",
        "clientid": "9749368",
        "fulfillment": "bulk",
        "shipping": {
            "company": "Sample Company",
            "attention": "Sample",
            "address1": "Any Address",
            "address2": "Apt 212",
            "city": "Any City",
            "state": "NY",
            "zip": "98625",
            "country": "US"
        },
        "accounts": [
            {
                "firstname": "Reward",
                "lastname": "Recipient",
                "email": "[email protected]",
                "sku": "UVC-P-V03",
                "amount": "10.00",
                "address1": "Any Address",
                "city": "Any City",
                "state": "NY",
                "zip": "98625",
                "country": "US"
            },
{
    "firstname":"Jane",
    "lastname":"Doe",
    "email":"[email protected]",
    "sku":"UVC-P-V03",
    "amount":"25.00",
              "address1": "Any Address",
                "city": "Any City",
                "state": "NY",
                "zip": "98625",
                "country": "US"
}
        ]
    }
}

Multiple Rewards Response JSON

{
"Order":{
"Programid":"26002",
"Clientid":"9749368",
"Fulfillment":"bulk",
"Shipping":{
"company":"Sample Company",
"attention":"Sample",
"address1":"Any Address",
"address2":"Apt 212",
"city":"Any City",
"state":"NY",
"Zip":"98625",
"country":"US"
},
"Number":"24693508",
"Status":"processing",
"Accounts":[
{
"Id":"261341",
"firstname":"Reward",
"lastname":"Recipient",
"email":"[email protected]",
"address1":"Any Address",
"city":"Any City",
"state":"NY",
"Zip":"98625",
"country":"US",
"sku":"UVC-P-V03",
"currency":"USD",
"Amount":"10.00",
"Link":""
},
{
"Id":"261342",
"firstname":"Jane",
"lastname":"Doe",
"email":"[email protected]",
"address1":"Any Address",
"city":"Any City",
"state":"NY",
"Zip":"98625",
"country":"US",
"sku":"UVC-P-V03",
"currency":"USD",
"Amount":"25.00",
"Link":""
}
]
}
}