Segments API

Integrate with our Segments API

Topsort’s Segments API allows our clients to create and manage groups of users for targeting purposes. After creating segments on our platform, they can be used as targeting in the campaign creation.

Uploading Users to a Segment

Once a segment is created, users can be uploaded to it using our APIs. Topsort support three actions:

• Add: Append new users to the existing segment, without making changes to existing ones.
• Remove: Delete specific users from the segment.
• Replace: Overwrite the entire segment with a new user list

Adding, removing, or replacing users does not update the segment right away. Allow up to 24 hours for those user changes to be reflected in the segment.

User lists must follow this specification:

• File format is .txt
• No headers
• One Opaque User ID per row, without emails or personal information.

Restricting a Segment to Specific Vendors

By default, a new segment is global: every vendor in your marketplace can select it as targeting. To limit a segment to specific vendors, manage its vendor list with your Advanced API Key:

• List vendors: GET /public/v1/segment-service/segments/{segment_id}/vendors returns the vendors assigned to the segment. An empty vendorIds list means the segment is global.
• Add vendors: PUT /public/v1/segment-service/segments/{segment_id}/vendors adds the given vendors. Vendors already assigned stay. Adding the first vendor turns a global segment into a restricted one.
• Remove vendors: DELETE /public/v1/segment-service/segments/{segment_id}/vendors removes the given vendors. Removing the last vendor makes the segment global again.

Segment and vendor IDs are your external IDs. Each request accepts up to 100 vendor IDs, and every endpoint returns the segment’s resulting vendor list:

curl -X PUT https://api.topsort.com/public/v1/segment-service/segments/{segment_id}/vendors \
  -H "Authorization: Bearer YOUR_ADVANCED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vendorIds": ["vendor-a", "vendor-b"]}'

{
  "id": "{segment_id}",
  "vendorIds": ["vendor-a", "vendor-b"]
}

To check which segments a vendor can use, call Retrieve a list of segments with the vendor_id query parameter. The response contains the global segments plus the segments assigned to that vendor.

A segment is global from the moment it is created until its first vendor is added. Add vendors right after creating a segment that should not be available to every vendor.

Use in Campaigns

Segments are used as targeting options in campaigns. The same Opaque User ID uploaded to the segments should be used on the auction request, to guarantee the auction engine can match it with the corresponding segment.