RaiseDonors has the ability to collect custom data with a donation. For example, you could include things like shirt size, sponsor ship information, call center information, etc. To learn more on how you can collect and save custom data with a donation, read this help article.
How does it work with Virtuous?
The custom data sent to Virtuous will be attached to the Transaction.CustomFields section. The name of the attribute will be the name of the custom field. And the value of the attribute is the value from the custom field.
All custom fields needing to be sent to Virtuous must start with 'virtuousapi_'. The full custom name will follow this template,
custom_virtuousapi_{name}={value}.
"custom_" - indicates to RaiseDonors this is a custom field.
"virtuousapi_" - indicates to RaiseDonors, this custom fields needs to be sent to Virtuous.
Both "custom_" and "virtuousapi_" are removed from the name when sending to Virtuous. For example, if you are passing the donors age into a custom field, your implementation will look something like this. (Note: there are two ways of passing in custom data. Either directly on the donation page or via the API. Both methods are described below).
Donation Page
Add a new key 'custom_age' to the hidden field. With a value of 21.
"custom_age=21|"
You need to adjust the name by adding "virtuousapi_". The final result would look like,
"custom_virtuousapi_age=21|"
RaiseDonors can now see this as a custom field that will also be sent to Virtuous with the donation.
"age" will be sent to Virtuous's Transaction.CustomFields.Name field. And "21" will be sent to Virtuous's Transaction.CustomFields.Value field.
API
Add a new key/value pair to the CustomDataItems section. Such as "age:21" and "transactionId:123455".
customDataItems:{
"transactionId": "123456",
"age": "23"
}
You need to adjust the name by adding "virtuousapi_". The final result would look like,
customDataItems:{
"virtuousapi_transactionId": "123456",
"virtuousapi_age": "23"
}
RaiseDonors can now see this as a custom field that will also be sent to Virtuous with the donation.
"transactionId" will be sent to Virtuous's Transaction.CustomField.Name field. And "123456" will be sent to Virtuous's Transaction.CustomField.Value field.
"age" will be sent to Virtuous's Transaction.CustomFields.Name field. And "23" will be sent to Virtuous's Transaction.CustomField.Value field.
Now you know how to pass custom data from RaiseDonors into Virtuous!
Can custom data overwrite data sent to Virtuous?
Yes! There is one very specific case where you can update a value sent to Virtuous. The context is found in the "segment code". Recall from the mapping diagram, that the source-code in RaiseDonors maps to the segment code in Virtuous. We'll use segment code and source code interchangeably below.
So if you have set a default value on the page for the source code, that is likely what will be sent to Virtuous. However you also have the option to overwrite that value using URL parameters. But what if you are wanting to ask the donor a question on the donation page - which might change the value you need to send for the segment code?
That's what we are here to solve. You can follow the same principle previously described to save custom data with the donation, but with a few subtle changes.
- "custom_" - indicates to RaiseDonors this is a custom field.
- "virtuousapi_" - indicates to RaiseDonors, this custom fields needs to be sent to Virtuous.
- "overwrite_segment" - indicates this value should overwrite any value for the segment code.
If you've asked the donor a question which needs to update the segment code from "123ABC" to "456XYZ", you'd add a new key to the hidden field. Ex:
"custom_virtuousapi_overwrite_segment=456XYZ"
RaiseDonors can now see this as a custom field that will be sent to Virtuous with the donation and will specifically update the segment code to have a value of "456XYZ" regardless of the default value configured on the page or any URL parameters.