Skip to main content

How do I send custom data to Virtuous CRM+ from a donation?

Chris Mechsner
  • Updated

Legacy 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 CRM+?

The custom data sent to Virtuous CRM+ 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 CRM+ must start with 'virtuousapi_'.  The full custom name will follow this template,
custom_virtuousapi_{name}={value}. 

"custom_" - indicates to Legacy RaiseDonors this is a custom field. 
"virtuousapi_" - indicates to Legacy RaiseDonors, this custom fields needs to be sent to Virtuous CRM+. 

 

Both "custom_" and "virtuousapi_" are removed from the name when sending to Virtuous CRM+. 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|"

Legacy RaiseDonors can now see this as a custom field that will also be sent to Virtuous CRM+ with the donation. 
"age" will be sent to Virtuous CRM+'s Transaction.CustomFields.Name field. And "21" will be sent to Virtuous CRM+'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"
}

Legacy RaiseDonors can now see this as a custom field that will also be sent to Virtuous CRM+ with the donation. 
"transactionId" will be sent to Virtuous CRM+'s Transaction.CustomField.Name field. And "123456" will be sent to Virtuous CRM+'s Transaction.CustomField.Value field. 

"age" will be sent to Virtuous CRM+'s Transaction.CustomFields.Name field. And "23" will be sent to Virtuous CRM+'s Transaction.CustomField.Value field. 


Now you know how to pass custom data from Legacy RaiseDonors into Virtuous CRM+!

 

Can custom data overwrite data sent to Virtuous CRM+?

Yes! There is one very specific case where you can update a value sent to Virtuous CRM+. The context is found in the "segment code". Recall from the mapping diagram, that the source-code in Legacy RaiseDonors maps to the segment code in Virtuous CRM+. 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 CRM+. 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 Legacy RaiseDonors this is a custom field. 
  • "virtuousapi_" - indicates to Legacy RaiseDonors, this custom fields needs to be sent to Virtuous CRM+. 
  • "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"


Legacy RaiseDonors can now see this as a custom field that will be sent to Virtuous CRM+ 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.