Segment Mapping

WeGive Campaigns map to Virtuous Segments.

Record Model

WeGive record	Virtuous record	Correlation column
Campaign	`Segment`	`virtuous_id`

Push (WeGive → Virtuous)

Creating a segment

When a campaign has no virtuous_id, the integration creates a Segment. This requires default_communication_id to be configured — without it, the push fails.

POST Segment
{
  "name": <campaign.name>,
  "code": "WGC:<campaign.id>",
  "communicationId": <default_communication_id>
}

The code is prefixed WGC: so the integration can later recognize segments it created. The returned id is stored as the campaign’s virtuous_id.

Updating a segment

When a campaign already has a virtuous_id, the integration GETs the Segment and only updates it if the code still starts with WGC: (i.e. WeGive created it). Segments created directly in Virtuous are left untouched.

PUT Segment/{id}
{ "name": <campaign.name>, "code": <existing code> }

Pull (Virtuous → WeGive)

Segments are pulled via POST Segment/Query (1000 per page, filtered by the configured pull_by date) and imported as Campaigns, matched on virtuous_id.

Virtuous’s Segment/Query response can omit the segment’s campaign relationship (a known Virtuous-side gap) — when that happens, the integration resolves the campaign name through the segment’s communicationId instead, via a bulk communication-to-campaign-name map built once per sync (to stay within Virtuous’s ~2,000-calls-per-day API cap, rather than issuing one lookup per segment). If that lookup itself fails, the import falls back to whatever the original query response had rather than blocking.

For new campaigns, the name is composed from the Virtuous record as:

<campaignName> | <communicationName> | <name> | <code>

Existing campaigns keep their current WeGive name. This reflects the integration as implemented in app/Integrations/Virtuous.php.

​Segment Mapping

​Record Model

​Push (WeGive → Virtuous)

​Creating a segment

​Updating a segment

​Pull (Virtuous → WeGive)