> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wegive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Segment Mapping

> How WeGive campaigns map to Virtuous segments, in both directions

# 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 `GET`s 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`.

<Note>
  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.
</Note>

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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.