curl --request GET \
--url https://api.virtuoussoftware.com/api/Contact/{referenceSource}/{referenceId} \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.virtuoussoftware.com/api/Contact/{referenceSource}/{referenceId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.virtuoussoftware.com/api/Contact/{referenceSource}/{referenceId}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)using RestSharp;
var options = new RestClientOptions("https://api.virtuoussoftware.com/api/Contact/{referenceSource}/{referenceId}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
var response = await client.GetAsync(request);
Console.WriteLine("{0}", response.Content);
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.virtuoussoftware.com/api/Contact/{referenceSource}/{referenceId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}HttpResponse<String> response = Unirest.get("https://api.virtuoussoftware.com/api/Contact/{referenceSource}/{referenceId}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.virtuoussoftware.com/api/Contact/{referenceSource}/{referenceId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyconst url = 'https://api.virtuoussoftware.com/api/Contact/{referenceSource}/{referenceId}';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));{
"isCurrentUserFollowing": true,
"id": 100234,
"contactType": "Household",
"isPrivate": false,
"name": "Marcus Castellano",
"informalName": "Marcus & Elena Castellano",
"description": "Household led by Marcus Castellano; board member and major donor.",
"website": null,
"maritalStatus": "Married",
"anniversaryMonth": null,
"anniversaryDay": null,
"anniversaryYear": null,
"mergedIntoContactId": null,
"address": {
"id": 400123,
"label": "Home",
"address1": "219 Oak Hill Drive",
"address2": null,
"city": "Springfield",
"state": "OR",
"postal": "97478",
"country": "United States",
"isPrimary": true,
"canBePrimary": true,
"startMonth": null,
"startDay": null,
"endMonth": null,
"endDay": null
},
"giftAskAmount": "1000.00",
"giftAskType": "Capital Campaign",
"lifeToDateGiving": "42500.00",
"yearToDateGiving": "4000.00",
"lastGiftAmount": "1000.00",
"lastGiftDate": "2025-10-12T00:00:00Z",
"contactIndividuals": [
{
"id": 200234,
"contactId": 100234,
"prefix": "Mr.",
"firstName": "Marcus",
"middleName": "David",
"lastName": "Castellano",
"suffix": null,
"gender": "Male",
"isPrimary": true,
"canBePrimary": true,
"isSecondary": false,
"canBeSecondary": true,
"birthMonth": 3,
"birthDay": 18,
"birthYear": 1972,
"birthDate": "1972-03-18T00:00:00Z",
"approximateAge": 53,
"isDeceased": false,
"passion": "Youth education",
"avatarUrl": "https://api.virtuoussoftware.com/api/ContactIndividual/200234/Avatar",
"contactMethods": [
{
"id": 300101,
"type": "Home Email",
"value": "marcus.castellano@example.org",
"isOptedIn": true,
"isPrimary": true,
"canBePrimary": true
},
{
"id": 300102,
"type": "Mobile Phone",
"value": "(555) 012-3401",
"isOptedIn": true,
"isPrimary": true,
"canBePrimary": true
},
{
"id": 300103,
"type": "Home Phone",
"value": "(555) 012-3400",
"isOptedIn": true,
"isPrimary": false,
"canBePrimary": true
}
],
"createDateTimeUtc": "2018-09-15T14:22:31Z",
"modifiedDateTimeUtc": "2025-10-12T09:15:42Z",
"customFields": [
{
"name": "EngagementScore",
"value": "85",
"displayName": "Engagement Score"
},
{
"name": "CommunicationPreference",
"value": "Email",
"displayName": "Communication Preference"
}
],
"customCollections": []
},
{
"id": 200235,
"contactId": 100234,
"prefix": "Mrs.",
"firstName": "Elena",
"middleName": "Maria",
"lastName": "Castellano",
"suffix": null,
"gender": "Female",
"isPrimary": false,
"canBePrimary": true,
"isSecondary": true,
"canBeSecondary": true,
"birthMonth": 8,
"birthDay": 22,
"birthYear": 1974,
"birthDate": "1974-08-22T00:00:00Z",
"approximateAge": 51,
"isDeceased": false,
"passion": "Community health",
"avatarUrl": "https://api.virtuoussoftware.com/api/ContactIndividual/200235/Avatar",
"contactMethods": [
{
"id": 300104,
"type": "Home Email",
"value": "elena.castellano@example.org",
"isOptedIn": true,
"isPrimary": true,
"canBePrimary": true
},
{
"id": 300105,
"type": "Mobile Phone",
"value": "(555) 012-3402",
"isOptedIn": true,
"isPrimary": true,
"canBePrimary": true
}
],
"createDateTimeUtc": "2018-09-15T14:22:31Z",
"modifiedDateTimeUtc": "2025-10-12T09:15:42Z",
"customFields": [],
"customCollections": []
}
],
"contactGiftsUrl": "https://api.virtuoussoftware.com/api/Gift/ByContact/100234",
"contactPassthroughGiftsUrl": "https://api.virtuoussoftware.com/api/Gift/Passthrough/ByContact/100234",
"contactPlannedGiftsUrl": "https://api.virtuoussoftware.com/api/PlannedGift/ByContact/100234",
"contactRecurringGiftsUrl": "https://api.virtuoussoftware.com/api/RecurringGift/ByContact/100234",
"contactImportantNotesUrl": "https://api.virtuoussoftware.com/api/ContactNote/Important/ByContact/100234",
"contactNotesUrl": "https://api.virtuoussoftware.com/api/ContactNote/ByContact/100234",
"contactTagsUrl": "https://api.virtuoussoftware.com/api/ContactTag/ByContact/100234",
"contactRelationshipsUrl": "https://api.virtuoussoftware.com/api/Relationship/ByContact/100234",
"primaryAvatarUrl": "https://api.virtuoussoftware.com/api/ContactIndividual/200234/Avatar",
"contactReferences": [
{
"source": "Raise",
"id": "200234"
}
],
"originSegmentId": 2010,
"originSegment": "Spring Appeal 2025",
"createDateTimeUtc": "2018-09-15T14:22:31Z",
"createdByUser": "Data Import",
"modifiedDateTimeUtc": "2025-10-12T09:15:42Z",
"modifiedByUser": "Nightly Sync",
"tags": [
"Board Member",
"Major Donor"
],
"organizationGroups": [
"Board of Directors"
],
"customFields": [
{
"name": "EngagementScore",
"value": "85",
"displayName": "Engagement Score"
},
{
"name": "CommunicationPreference",
"value": "Email",
"displayName": "Communication Preference"
}
],
"customCollections": []
}{
"message": "Authorization has been denied for this request."
}{
"message": "You do not have permission to perform this action."
}{
"message": "Rate limit exceeded. Try again later."
}Get a Contact by Reference Source
Returns the contact carrying the given reference from an external system, for example the donor record in the platform you sync from. References are set when the contact is created or imported, or through the Create a Contact Reference endpoint.
curl --request GET \
--url https://api.virtuoussoftware.com/api/Contact/{referenceSource}/{referenceId} \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.virtuoussoftware.com/api/Contact/{referenceSource}/{referenceId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.virtuoussoftware.com/api/Contact/{referenceSource}/{referenceId}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)using RestSharp;
var options = new RestClientOptions("https://api.virtuoussoftware.com/api/Contact/{referenceSource}/{referenceId}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
var response = await client.GetAsync(request);
Console.WriteLine("{0}", response.Content);
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.virtuoussoftware.com/api/Contact/{referenceSource}/{referenceId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}HttpResponse<String> response = Unirest.get("https://api.virtuoussoftware.com/api/Contact/{referenceSource}/{referenceId}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.virtuoussoftware.com/api/Contact/{referenceSource}/{referenceId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyconst url = 'https://api.virtuoussoftware.com/api/Contact/{referenceSource}/{referenceId}';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));{
"isCurrentUserFollowing": true,
"id": 100234,
"contactType": "Household",
"isPrivate": false,
"name": "Marcus Castellano",
"informalName": "Marcus & Elena Castellano",
"description": "Household led by Marcus Castellano; board member and major donor.",
"website": null,
"maritalStatus": "Married",
"anniversaryMonth": null,
"anniversaryDay": null,
"anniversaryYear": null,
"mergedIntoContactId": null,
"address": {
"id": 400123,
"label": "Home",
"address1": "219 Oak Hill Drive",
"address2": null,
"city": "Springfield",
"state": "OR",
"postal": "97478",
"country": "United States",
"isPrimary": true,
"canBePrimary": true,
"startMonth": null,
"startDay": null,
"endMonth": null,
"endDay": null
},
"giftAskAmount": "1000.00",
"giftAskType": "Capital Campaign",
"lifeToDateGiving": "42500.00",
"yearToDateGiving": "4000.00",
"lastGiftAmount": "1000.00",
"lastGiftDate": "2025-10-12T00:00:00Z",
"contactIndividuals": [
{
"id": 200234,
"contactId": 100234,
"prefix": "Mr.",
"firstName": "Marcus",
"middleName": "David",
"lastName": "Castellano",
"suffix": null,
"gender": "Male",
"isPrimary": true,
"canBePrimary": true,
"isSecondary": false,
"canBeSecondary": true,
"birthMonth": 3,
"birthDay": 18,
"birthYear": 1972,
"birthDate": "1972-03-18T00:00:00Z",
"approximateAge": 53,
"isDeceased": false,
"passion": "Youth education",
"avatarUrl": "https://api.virtuoussoftware.com/api/ContactIndividual/200234/Avatar",
"contactMethods": [
{
"id": 300101,
"type": "Home Email",
"value": "marcus.castellano@example.org",
"isOptedIn": true,
"isPrimary": true,
"canBePrimary": true
},
{
"id": 300102,
"type": "Mobile Phone",
"value": "(555) 012-3401",
"isOptedIn": true,
"isPrimary": true,
"canBePrimary": true
},
{
"id": 300103,
"type": "Home Phone",
"value": "(555) 012-3400",
"isOptedIn": true,
"isPrimary": false,
"canBePrimary": true
}
],
"createDateTimeUtc": "2018-09-15T14:22:31Z",
"modifiedDateTimeUtc": "2025-10-12T09:15:42Z",
"customFields": [
{
"name": "EngagementScore",
"value": "85",
"displayName": "Engagement Score"
},
{
"name": "CommunicationPreference",
"value": "Email",
"displayName": "Communication Preference"
}
],
"customCollections": []
},
{
"id": 200235,
"contactId": 100234,
"prefix": "Mrs.",
"firstName": "Elena",
"middleName": "Maria",
"lastName": "Castellano",
"suffix": null,
"gender": "Female",
"isPrimary": false,
"canBePrimary": true,
"isSecondary": true,
"canBeSecondary": true,
"birthMonth": 8,
"birthDay": 22,
"birthYear": 1974,
"birthDate": "1974-08-22T00:00:00Z",
"approximateAge": 51,
"isDeceased": false,
"passion": "Community health",
"avatarUrl": "https://api.virtuoussoftware.com/api/ContactIndividual/200235/Avatar",
"contactMethods": [
{
"id": 300104,
"type": "Home Email",
"value": "elena.castellano@example.org",
"isOptedIn": true,
"isPrimary": true,
"canBePrimary": true
},
{
"id": 300105,
"type": "Mobile Phone",
"value": "(555) 012-3402",
"isOptedIn": true,
"isPrimary": true,
"canBePrimary": true
}
],
"createDateTimeUtc": "2018-09-15T14:22:31Z",
"modifiedDateTimeUtc": "2025-10-12T09:15:42Z",
"customFields": [],
"customCollections": []
}
],
"contactGiftsUrl": "https://api.virtuoussoftware.com/api/Gift/ByContact/100234",
"contactPassthroughGiftsUrl": "https://api.virtuoussoftware.com/api/Gift/Passthrough/ByContact/100234",
"contactPlannedGiftsUrl": "https://api.virtuoussoftware.com/api/PlannedGift/ByContact/100234",
"contactRecurringGiftsUrl": "https://api.virtuoussoftware.com/api/RecurringGift/ByContact/100234",
"contactImportantNotesUrl": "https://api.virtuoussoftware.com/api/ContactNote/Important/ByContact/100234",
"contactNotesUrl": "https://api.virtuoussoftware.com/api/ContactNote/ByContact/100234",
"contactTagsUrl": "https://api.virtuoussoftware.com/api/ContactTag/ByContact/100234",
"contactRelationshipsUrl": "https://api.virtuoussoftware.com/api/Relationship/ByContact/100234",
"primaryAvatarUrl": "https://api.virtuoussoftware.com/api/ContactIndividual/200234/Avatar",
"contactReferences": [
{
"source": "Raise",
"id": "200234"
}
],
"originSegmentId": 2010,
"originSegment": "Spring Appeal 2025",
"createDateTimeUtc": "2018-09-15T14:22:31Z",
"createdByUser": "Data Import",
"modifiedDateTimeUtc": "2025-10-12T09:15:42Z",
"modifiedByUser": "Nightly Sync",
"tags": [
"Board Member",
"Major Donor"
],
"organizationGroups": [
"Board of Directors"
],
"customFields": [
{
"name": "EngagementScore",
"value": "85",
"displayName": "Engagement Score"
},
{
"name": "CommunicationPreference",
"value": "Email",
"displayName": "Communication Preference"
}
],
"customCollections": []
}{
"message": "Authorization has been denied for this request."
}{
"message": "You do not have permission to perform this action."
}{
"message": "Rate limit exceeded. Try again later."
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
(Required) The reference source.
(Required) The reference identifier.
Response
OK
The unique identifier of the record in Virtuous.
The type of contact, for example Household, Organization, or Foundation.
When true, the record is only visible to users with permission to view private records.
The display name of the record.
The free-text description stored on the record.
Show child attributes
Show child attributes
The total amount the contact has given since the first gift.
The total amount the contact has given in the current year.
The amount of the most recent gift from the contact.
The date of the most recent gift from the contact.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The UTC date and time the record was created.
The name of the user who created the record.
The UTC date and time the record was last modified.
The name of the user who last modified the record.
The custom field values stored on the record.
Show child attributes
Show child attributes
The custom collection instances stored on the record.
Show child attributes
Show child attributes
Was this page helpful?