Matches

The Match API allows you to create, retrieve, modify, and delete segment matches.

Available since: v2.23.0

Create a segment match

includes segment match, signal match, group(aggregate) match, group(aggregate) signal match

Endpoint

POST /api/segments/match

Headers

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

Request Body

Name	Type	Required	Restrictions	Description
segmentId	string	true	N/A	Unique identifier for the segment
partnerId	integer(int32)	true	N/A	The ID of the partner
deliveryScopes	[string]	true	N/A	Delivery scope of identity
shareSegmentName	boolean	false	N/A	True if user wants to share segment name to partner, default is true
accessBgIds	boolean	false	N/A	True if user wants partner to access bgid, default value is true
returnUnmatchedBgIds	boolean	false	N/A	True if user wants to enable waterfall match
participantSegmentId	string	false	N/A	Required when segmentId missing
spi	boolean	false	N/A	Updated sensitive personal information flag
refresh	boolean	false	N/A	True if request a refresh match
groupId	integer(int64)	false	N/A	Unique identifier for the group, required for group match
aggregationId	string	false	N/A	Required for match refresh
shaveOffPercent	integer(int32)	false	N/A	Used only for modify
controlHoldoutPercent	integer(int32)	false	N/A	Used only for modify

Possible Responses

Status	Meaning	Description	Schema
200	OK	The status of the segment matching job. If the request is invalid, a "Bad Request"
(400) response is returned.	JobStatusResponse
400	Bad Request	Bad Request	Inline
500	Internal Server Error	Internal Server Error	Description of the match

Example Request

segment(signal) match:

curl -X POST http://localhost:8080/api/segments/match \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.blockgraph.v1+json' \
  -H 'Authorization: Bearer {access-token}'
  -d '{
   "segmentId":"3001-1547066",
   "partnerId":3003,
   "deliveryScopes":[
      "VOD_ACTIVE"
   ],
   "shareSegmentName":true,
   "accessBgIds":true,
   "returnUnmatchedBgIds":false
}'

group match:

curl -X POST http://localhost:8080/api/segments/match \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.blockgraph.v1+json' \
  -H 'Authorization: Bearer {access-token}'
  -d '{
   "segmentId":"3002-1049339",
   "groupId":4752,
   "deliveryScopes":
      [
         "VOD_ACTIVE"
      ]
   ,
   "shareSegmentName":true,
   "accessBgIds":true,
   "returnUnmatchedBgIds":false
}'

Response

200 Response

{
  "id": "3001-11350-079",
  "status": "PENDING"
}

400 Response

Create test & control(match modify)

Endpoint

POST /api/segments/match/test-control/{matchId}

Headers

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

Request Body

Name	Type	Required	Restrictions	Description
shaveOffPercent	integer(int32)	false	N/A	Used only for modify
controlHoldoutPercent	integer(int32)	false	N/A	Used only for modify

Possible Responses

Status	Meaning	Description	Schema
200	OK	The status of the segment match modification job. If the request is invalid or the job task
does not exist, a "Bad Request" (400) response is returned.	JobStatusResponse
400	Bad Request	If match was not found	Inline
500	Internal Server Error	Internal Server Error	Description of the match

Example Request

curl -X POST http://localhost:8080/api/segments/match/test-control/3001-11240-070 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.blockgraph.v1+json' \
  -H 'Authorization: Bearer {access-token}'
  -d '{
   "shaveOffPercent":20,
   "controlHoldoutPercent":30
}'

Response

200 Response

{
  "id": "3001-11350-079",
  "status": "PENDING"
}

400 Response

Retrieves a match result by its match ID.

Endpoint

GET /api/segments/match/{matchId}

Headers

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

Request Body

Name	In	Type	Required	Description
matchId	path	long	true	The ID of the job that created the match.

Possible Responses

Status	Meaning	Description	Schema
200	OK	The match result if found, otherwise a "Not Found" (404) response.	Match
400	Bad Request	Bad Request	Inline
500	Internal Server Error	Internal Server Error	Description of the match

Example Request

curl -X GET http://localhost:8080/api/segments/match//3001-11300-076 \
  -H 'Accept: application/vnd.blockgraph.v1+json' \
  -H 'Authorization: Bearer {access-token}'

Response

200 Response

{
  "matchId": 123,
  "segmentId": "123-123",
  "segmentName": "full1-recordid",
  "participantSegmentId": null,
  "spi": false,
  "status": "FINISHED",
  "matchRequestor": 123,
  "matchApprover": 456,
  "matchSignal": "IP",
  "matchCount": 10,
  "shareBgIds": true,
  "shareSegmentName": true,
  "segmentOwner": null,
  "deliveryScope": [],
  "description": "",
  "files": [],
  "matchJobId": "30200726119188"
}

400 Response

Deletes a match record by its ID.

Endpoint

DELETE /api/segments/match/{matchId}

Headers

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

Request Body

Name	In	Type	Required	Description
matchId	path	long	true	The ID of the match record to delete.

Possible Responses

Status	Meaning	Description	Schema
200	OK	A "No Content" (204) response if successful.	None
400	Bad Request	Bad Request	Inline
500	Internal Server Error	Internal Server Error	Description of the match

Example Request

curl -X DELETE http://localhost:8080/api/segments/match/{matchId} \
  -H 'Accept: */*' \
  -H 'Authorization: Bearer {access-token}'

Response

200 Response

400 Response

List all segment matches.

Endpoint

GET /api/segments/match

Headers

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

Request Body

Name	In	Type	Required	Description
params	query	SegmentMatchQueryParameters	true	Query parameters for filtering segment matches.

Possible Responses

Status	Meaning	Description	Schema
200	OK	A response containing a list of segment matches that match the filter criteria.	SegmentMatchResponse
400	Bad Request	Bad Request	Inline
500	Internal Server Error	Internal Server Error	Description of the match

Example Request

# You can also use wget
curl -X GET http://localhost:8080/api/segments/match?limit=100 \
  -H 'Accept: application/vnd.blockgraph.v1+json' \
  -H 'Authorization: Bearer {access-token}'

Response

200 Response

{
  "matches": [
    {
      "matchId": 123,
      "segmentId": "123-123",
      "segmentName": "full1-recordid",
      "participantSegmentId": null,
      "spi": false,
      "status": "FINISHED",
      "matchRequestor": 123,
      "matchApprover": 456,
      "matchSignal": "IP",
      "matchCount": 10,
      "shareBgIds": true,
      "shareSegmentName": true,
      "segmentOwner": null,
      "deliveryScope": [
        "HIGH_SPEED_DATA",
        "CABLE"
      ],
      "description": "",
      "files": [],
      "matchJobId": "30200726119188"
    },
    {
      "matchId": 123,
      "segmentId": "123-123",
      "segmentName": "full1-recordid",
      "participantSegmentId": null,
      "spi": false,
      "status": "FINISHED",
      "matchRequestor": 123,
      "matchApprover": 456,
      "matchSignal": "IP",
      "matchCount": 10,
      "shareBgIds": true,
      "shareSegmentName": true,
      "segmentOwner": null,
      "deliveryScope": [
        "HIGH_SPEED_DATA",
        "CABLE"
      ],
      "description": "",
      "files": [],
      "matchJobId": "30200726119188"
    }
  ],
  "page": 0,
  "pageSize": 1,
  "hasMore": true
}

400 Response

SegmentMatchQueryParameters

Name	Type	Constraints	Description
requester	boolean	optional	True if need to return matches requested by me.
segmentName	string	optional	Name of the segment to filter by.
status	MatchRecordStatus	optional	Status of the match record to filter by MatchRecordStatus.
page	integer	0 ≤ value ≤ 1000	Page number for pagination.
pageSize	integer	10 ≤ value ≤ 100	Number of items per page.

MatchRecordStatus

Possible values for MatchRecordStatus:

Value	Description
FAILED	Match process failed.
DELIVERING	Currently delivering data.
WAITING	Waiting for the next step.
APPROVED	Approved by a reviewer/system.
REJECTED	Rejected after review.
WAITING_DELIVERY	Waiting to be delivered.
RUNNING	Match job is running.
MATCH_ENGINE_PROCESSING	Being processed by match engine.
SUBMITTED	Submitted for processing.
PENDING_APPROVAL	Awaiting approval.
READY_FOR_MATCH	Ready to be matched.
RECEIVED	Received by the system.
FETCHED	Fetched from source.
FINISHED	Processing is complete.
RECEIVER_RUNNING	Receiver is actively processing.
AGGREGATE_MATCH_WAITING	Waiting for aggregate matching.
CHILD_SUBMITTED	Child job submitted.
CHILD_RUNNING	Child job running.
UPDATE_SUBMITTED	Update submitted.
UPDATE_RUNNING	Update in progress.
UNKNOWN	Default/unknown status.