Creating your first Segment

A segment is a saved audience - a group of customers matching some criteria, or a fixed list you upload directly. A segment doesn't have to feed a campaign to earn its keep: you can explore it on its own, or compare it against your full customer base or another segment. But every campaign in Drive does target a segment, so it's the natural place to start either way.

Create an empty segment

POST /drive-api/v2/segments

{
  "name": "New manual segment",
  "description": "A new manual segment (with an empty criteria)",
  "tags": ["tag_1", "tag_2"]
}

A note on response formats. Most Drive Segments V2 endpoints - including this one - respond with a vendor content type (application/vnd.bud.drive.notification+json, .criteria+json, .visualisation+json, or .criteria-options+json) instead of plain application/json. The shape is the same JSON you'd expect, but check the Content-Type you're negotiating for rather than assuming application/json everywhere - this is easy to miss on your first integration.

A successful create returns a notification-shaped response with the new segment's ID under metadata.resource_id:

{
  "operation_id": "v2_segments_post",
  "code_id": "segment_created",
  "status": "success",
  "metadata": { "resource_id": "23303f83-a790-4ee9-95b6-d5cdeaf36fa2" }
}

Other ways to create a segment

The same endpoint also accepts a from_criteria_id (seed the segment from an existing draft criteria - see Understanding Segment Criteria) or an upload object (a fixed list of customer IDs, for when the audience comes from outside Drive entirely):

{
  "name": "Uploaded list of customers",
  "description": "List of customers from a campaign",
  "tags": ["campaign_1"],
  "upload": { "filename": "campaign_customers.csv", "customers": ["c1", "c2", "c3"] }
}

Add criteria and run it

A freshly created empty segment has no criteria yet. Build one with the criteria drafts flow in Understanding Segment Criteria, then attach it:

PUT /drive-api/v2/segments/{segment_id}/criteria/{criteria_id}

To see how many customers currently match, run the segment's criteria:

POST /drive-api/v2/segments/{segment_id}/criteria/run

{
  "operation_id": "v2_segments_criteria_run_post",
  "data": { "visualisation_type": "counter", "name": "total_customers", "value": 163 },
  "metadata": { "run_id": "48c675f4-4fc7-43f3-80fd-114ec632f4f7", "run_type": "expiring" }
}

That's a segment, ready to campaign against, explore on its own, or compare against another. Next: Understanding Segment Criteria for the full criteria model - nesting AND/OR/NOT logic and excluding other segments, beyond the single flag used here - or skip straight to Creating and Managing Campaigns if you already know who you're targeting.