Segments

The Segments API allows you to create, retrieve, update, and delete audience segments.

Create a Segment

Creates a new segment.

Endpoint

POST /api/segments

Headers

• Content-Type: application/json
• Accept: application/vnd.blockgraph.v1+json
• Authorization: Bearer {access-token}

Request Body

Field	Type	Required	Max size limit	Description
segmentFileName	string	true	100 characters	Name of the file containing segment data
participantSegmentId	string	true	100 characters	Unique identifier for the segment
segmentName	string	true	100 Characters	Name of the segment
cpm	number	false	N/A	Cost per mille
dataOwner	string	false	200 Characters	Owner of the segment data
category	string	false	200 Characters	Category of the segment
subCategory	string	false	200 Characters	Subcategory of the segment
description	string	false	500 Characters	Description of the segment
spi	boolean	false	N/A	Whether the segment was built using sensitive personal information
uploadSignal	string	true	N/A	Type of signal used for upload
resultContent	string	true	N/A	Type of content in the result
uploadDateWithSignals	boolean	false(true)	N/A	Required when: uploadSignal=IP and resultContent=BGID False - timestamp not included in file and current date used for IP lookups True - timestamp included in file and historical date used for IP lookups
providerId	integer	true(false)	N/A	ID of the provider. Not required for BGID input signal and HASHED resultant segments
updateIdentityDatabase	boolean	false	N/A	Whether to update the identity database during segment processing. Defaults to true. Can only be set to False when uploadSignal is RECORD_ID and the segment is created against your node’s own identity. Available starting in release 2.26.0

Enumerated Values

Field	Possible Values
uploadSignal	IP, IDFA, AAID, STBID, EMAIL, ADDRESS, PARTNER_RECORD_ID, BGID, RECORD_ID, ZIPCODE
resultContent	BGID, HASHED

Example Request

curl -X POST "https://api.{participant id}.blockgraph.app/api/segments" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.blockgraph.v1+json" \
  -H "Authorization: Bearer $access_token" \
  -d '{
    "segmentFileName": "segments_file.csv",
    "participantSegmentId": "segments_file",
    "segmentName": "Test Segment",
    "cpm": 0.1,
    "uploadSignal": "RECORD_ID",
    "resultContent": "BGID",
    "providerId": {participant id}
  }'

Response

200 OK

{
  "id": "job id",
  "status": "PENDING",
  "segmentId": "segment_id"
}

Field	Description
id	ID of the job created for segment processing
status	Current status of the job
segmentId	ID of the created segment (available only when job is successfully completed)

Possible Status Values

• PENDING - waiting to start processing
• READY - ready to start processing
• RUNNING - job is running
• CANCELLED - job is cancelled
• PENDING_APPROVAL - job is pending approval from another participant
• REJECTED - job is rejected
• FAILED - job failed
• PARTIAL_SUCCESS - job failed, format validation passed
• SUCCESS - job is successfully completed

Update a Segment

Updates an existing segment by its ID.

Endpoint

PUT /api/segments/{id}

Headers

• Content-Type: application/json
• Accept: application/vnd.blockgraph.v1+json
• Authorization: Bearer {access-token}

Path Parameters

Name	Type	Required	Description
id	string	true	The ID of the segment to update

Request Body

Field	Type	Required	Description
segmentName	string	true	Updated name of the segment
cpm	number	false	Updated cost per mille
dataOwner	string	false	Updated owner of the segment data
category	string	false	Updated category of the segment
subCategory	string	false	Updated subcategory of the segment
description	string	false	Updated description of the segment
spi	boolean	false	Updated sensitive personal information flag

Example Request

curl -X PUT "https://api.{participant id}.blockgraph.app/api/segments/{id}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.blockgraph.v1+json" \
  -H "Authorization: Bearer $access_token" \
  -d '{
    "segmentName": "Updated Test Segment",
    "cpm": 0.2,
    "description": "This is an updated test segment"
  }'

Response

200 OK

Returns the updated segment object.

Retrieve a Segment

Retrieves details of a segment by its ID.

Endpoint

GET /api/segments/{id}

Headers

• Accept: application/vnd.blockgraph.v1+json
• Authorization: Bearer {access-token}

Path Parameters

Name	Type	Required	Description
id	string	true	The ID of the segment to retrieve

Example Request

curl -X GET "https://api.{participant id}.blockgraph.app/api/segments/{id}" \
  -H "Accept: application/vnd.blockgraph.v1+json" \
  -H "Authorization: Bearer $access_token"

Response

200 OK

Returns the segment object if found.

List all Segments

Retrieves a list of segments based on query parameters.

Endpoint

GET /api/segments

Headers

• Accept: application/vnd.blockgraph.v1+json
• Authorization: Bearer {access-token}

Query Parameters

Name	Type	Required	Description
uploadSignal	string	false	Filter by upload signal type
resultContent	string	false	Filter by result content type
providerId	integer	false	Filter by provider ID
id	string	false	Filter by segment ID
participantSegmentId	string	false	Filter by participant segment ID
page	integer	false	Page number for pagination
pageSize	integer	false	Number of items per page

Example Request

curl -X GET "https://api.{participant id}.blockgraph.app/api/segments?uploadSignal=IP&pageSize=10" \
  -H "Accept: application/vnd.blockgraph.v1+json" \
  -H "Authorization: Bearer $access_token"

Response

200 OK

Returns a list of segment objects matching the criteria.

{
  "segments": [
    {
      "id": "segment_id_1",
      "segmentName": "Segment 1",
      ...
    },
    {
      "id": "segment_id_2",
      "segmentName": "Segment 2",
      ...
    }
  ],
  "page": 1,
  "pageSize": 10,
  "hasMore": true
}

Delete a Segment

Deletes a segment by its ID.

Endpoint

DELETE /api/segments/{id}

Headers

• Accept: /
• Authorization: Bearer {access-token}

Path Parameters

Name	Type	Required	Description
id	string	true	The ID of the segment to delete

Example Request

curl -X DELETE "https://api.{participant id}.blockgraph.app/api/segments/{id}" \
  -H "Accept: */*" \
  -H "Authorization: Bearer $access_token"

Response

200 OK

Returned when the segment is successfully deleted.

Refresh a Segment

Refreshes a segment by its ID.

Endpoint

PUT /api/segments/{id}/refresh

Headers

• Accept: application/vnd.blockgraph.v1+json
• Authorization: Bearer {access-token}

Path Parameters

Name	Type	Required	Description
id	string	true	The ID of the segment to refresh

Request Body (optional)

Field	Type	Required	Max size limit	Description
segmentFileName	string	true	100 characters	Name of the file containing segment data

Example Request 1

curl -X PUT "https://api.{participant id}.blockgraph.app/api/segments/{id}/refresh" \
  -H 'Content-Type: application/json' \
  -H "Accept: application/vnd.blockgraph.v1+json" \
  -H "Authorization: Bearer $access_token"

Example Request 2 - refresh with new segment file

curl -X PUT "https://api.{participant id}.blockgraph.app/api/segments/{id}/refresh" \
  -H 'Content-Type: application/json' \
  -H "Accept: application/vnd.blockgraph.v1+json" \
  -H "Authorization: Bearer $access_token" \
  -d '{
    "segmentFileName": "segments_file.csv"
  }'

Response

200 OK

Returns the status of the segment refresh job.

Share a Segment

Shares a segment with other participants.

Endpoint

POST /api/segments/share

Headers

• Content-Type: application/json
• Accept: application/vnd.blockgraph.v1+json
• Authorization: Bearer {access-token}

Request Body

Field	Type	Required	Description
segmentId	string	true	ID of the segment to share
partnerId	integer	true	ID of the partner to share with
shareSegmentName	boolean	false	Whether to share the segment name

Example Request

curl -X POST "https://api.{participant id}.blockgraph.app/api/segments/share" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.blockgraph.v1+json" \
  -H "Authorization: Bearer $access_token" \
  -d '{
    "segmentId": "segment_id",
    "partnerId": 1234,
    "shareSegmentName": true
  }'

Response

200 OK

Returns the status of the segment sharing job.