Bring Your Own Algorithm (BYOA) API

Use the Bring Your Own Algorithm (BYOA) API, available as an endpoint on the trafficking API, to create a BYOA rule that can be assigned to a line.

The following HTTP methods can be used:

Use the GET method to read existing BYOA rules by Account ID, Name or ID.
Use theGET method to read lines associated with a BYOA rule.
Use the POST method to create a BYOA rule.
Use the PUT method to update an existing BYOA rule.
Use the DELETE method to remove an existing BYOA rule.

Resources

traffic/byoa

The byoa object contains the following fields.

Request Parameters

Parameter	Definition	Data Type	Create	Update
`Id`	The unique identifier for the BYOA rule.	`Integer`	Not Required / NA	Required
`payload`	The base64 encoded rule file.	`String`	Required	Required
`accountId`	The ID of the advertiser.	`Integer`	Required	Required
`name`	The name of the BYOA algorithm rule.	`String`	Required	Required
`inputFileUrl`	The name of the uploaded file.	`String`	Required	Required

Response Parameters

Parameter	Definition	Data Type
`assignmentStatus`	This is the status of your BYOA rule. NOT_ASSIGNED - The BYOA rule is not yet associated with any line. PENDING - The BYOA rule is in the process of being associated with one or more lines. FAILED - The attempt to associate the BYOA rule with a line has failed. SUCCESS - The BYOA rule has been successfully associated with one or more lines.	`String`
`version`	This is the version of the uploaded rule. The most recent version will have the larger version number.	`Integer`
`linesTargetingBYOA`	This is a list of lines that are using the BYOA rule. Will be a list of Line IDs	`Array`
`Id`	The unique identifier for the BYOA rule.	`Integer`
`accountId`	The ID of the advertiser.	`Integer`
`name`	The name of the BYOA algorithm rule.	`String`
`inputFileUrl`	The URL of the file used for this rule.	`String`

Read BYOA Rules by Account ID, Name or ID

Read all BYOA rules for an advertiser by Account Id with Max version

Get all BYOA rules for an advertiser by account ID. The latest version of each rule is returned.

GET traffic/byoa/account/{accountId}

Parameters

Parameters	Parameter Type	Description	Data Type	Required
`accountId`	path	The ID of the advertiser.	`integer`	Y

Sample Request

GET traffic/byoa/account/987654321

Sample Response

[
   {"id": 1,accountId:2397,name:”byaa_nyc_apr-2018”,version: 1, inputFileUrl:”http://yahooo.s3/file1.rule”},
  {"id": 2,accountId:2397,name:”byoa_nyc_mar_2018”,version: 1, inputFileUrl:”http://yahooo.s3/file2.rule”},
 {"id": 3,accountId:2397,name:”byoa_nyc_103_2018”,version: 1, inputFileUrl:”http://yahooo.s3/file3.rule”} ]

Read all BYOA rules by Name

Get a list of all BYOA rules by name for the account. In case the algorithm has been modified, all the different versions will be returned.

GET /byoa/account/{account_id}/name/{name}

Parameters

Parameters	Parameter Type	Description	Data Type	Required
`accountId`	path	The ID of the advertiser.	`integer`	Y
`name`	path	The BYOA rule name.	`string`	Y

Sample Request

GET traffic/byoa/account/987654321/name/rule-1223424

Sample Response

For a rule that only has one version:

["bYOAResponses": [
        {
            "id": 987,                                             //LONG  (byoa id of this particular upload)
            "name": "testname",  
            "inputFileUrl": "https://s.yimg.com/ar/1234567abc_v3.rule",
            "version": 1,
            "accountId": 87654,
            "assignmentStatus": "FAILED",
            "linesTargetingBYOA": [987654,876546]
        }]
]

For a rule that has multiple versions:

"bYOAResponses": [
        {
            "id": 987,                                             //LONG  (byoa id of latest upload)
            "name": "testname",  
            "inputFileUrl": "https://s.yimg.com/ar/1234567abc_v3.rule",
            "version": 2,
            "accountId": 87654,
            "assignmentStatus": "FAILED",
            "linesTargetingBYOA": [987654,876546]
        },
        {
            "id": 986,                                             //LONG  (byoa id of this previous upload)
            "name": "testname",  
            "inputFileUrl": "https://s.yimg.com/ar/1234568abc_v2.rule",
            "version": 1,
            "accountId": 87654,
            "assignmentStatus": "FAILED",
            "linesTargetingBYOA": [987654,876546]
        }]

Read BYOA rule by Id

Get a BYOA rule by ID. The latest version of the rule will be returned.

GET traffic/byoa/{byoa_id}

Parameters

Parameters	Parameter Type	Description	Data Type	Required
`byoa_id`	path	The BYOA ID.	`integer`	Y

Sample Request

GET traffic/byoa/12345966

Sample Response

{
    id           : 978937432             		// LONG  (id of this particular upload)
    name        : ‘nyc-2018’
    version	         : 3
    inputFileUrl      : 'http://yahoo.s2/file2.rule’,  	// STRING   (name of file uploaded - received from FE),
    accountId: 34567,
    assignmentStatus: NOT_ASSIGNED,    // NOT_ASSIGNED, PENDING , FAILED, SUCCESS 
    linesTargetingBYOA: [987654,876543]
}

Read Lines Associated with the BYOA Rule

Get all lines associated with a BYOA rule.

GET traffic/byoa/{byoa_id}/lines

Parameters

Parameters	Parameter Type	Description	Data Type	Required
byoa_id	path	The BYOA ID.	integer	Y

Sample Request

GET traffic/byoa/6766876/lines

Sample Response

{
"lines": [
{
"id": 675765764,
"name": "Test BYOA",
"mediaType": “DISPLAY”,  (DISPLAY, VIDEO, NATIVE, AUDIO)
"deliveryStatus": “ENDED”, (RUNNING, PAUSED, ENDED, TOTAL_BUDGET_REACHED, DAILY_BUDGET_REACHED, NOT_STARTED_YET, LIVE_SOON, NOT_ACTIVE)
"accountId": 90980978,
"advertiserName": "BYOA Test Advertiser",
"clientStatus": “PAUSE”,  (PLAY, PAUSE, STOP, STOP_TOTAL_BUDGET, STOP_DAILY_BUDGET, STOP_START_DATE, STOP_END_DATE)
"seatName": "Test Seat",
"startDate": "2024-05-29T00:00:00-07:00"
},
{
"id": 675765765,
"name": "test line Package",
"mediaType": “DISPLAY”,
"deliveryStatus": “ENDED”,
"accountId": 90980978,
"advertiserName": "BYOA Test Advertiser",
"clientStatus": “PAUSE”,
"seatName": "Test Seat",
"startDate": "2024-07-31T00:00:00-07:00"
},
{
"id": 675765766,
"name": "testees",
"mediaType": “DISPLAY”,
"deliveryStatus": “PAUSED“,
"accountId": 90980978,
"advertiserName": "BYOA Test Advertiser",
"clientStatus": “PAUSE”,
"seatName": "Test Seat",
"startDate": "2024-09-30T00:00:00-07:00"
}
]
}

Create / Import BYOA rule

Create or import a new BYOA rule.

POST traffic/byoa

Parameters

All fields are specified in the request body.

Sample Request

POST traffic/byoa

Sample Request Body

  {
    payload 	: '....',             			// STRING   (base64 encoded rule file). Encoded 
    accountId   	: 1232424,            		// INTEGER  (Current advertiser-id)
    name    	:'rule-1234', '  	// STRING   (name of the algorithm rule created)
  }

Sample Response

{
  id: 123456,
  name: “rule-1234”,
  inputFileUrl: “https://yahoo.s3/rule.txt”,
  version: 1,
  accountId: 34567,
  assignmentStatus: NOT_ASSIGNED,    
  linesTargetingBYOA: [987654,876543]
}

Update a BYOA Rule

Update an existing BYOA rule.

PUT traffic/byoa

Parameters

All fields are specified in the request body.

Sample Request URL

PUT traffic/byoa/{byoa_id}

Sample Request Body

{
    payload 	: '....',             			// STRING   (base64 encoded rule file). Encoded string?
    accountId   	: 1232424,            		// INTEGER  (Current advertiser-id)
    name    	: 'rule-1234'  	// STRING   (name of the byoa ruleuploaded)
  }

Sample Response

{
  id: 123456,
  name: “rule-1233344”,
  inputFileUrl: “https://yahoo.s3/rule.txt”,
  version: 1,
  accountId: 3456457,
  assignmentStatus: NOT_ASSIGNED,    // NOT_ASSIGNED, PENDING, FAILED, SUCCESS
  linesTargetingBYOA: [987654,876543]
}

Delete a BYOA Rule

Delete an existing BYOA rule.

If the rule is associated with a line, delete will throw an error.

DELETE traffic/byoa/{byoa_id}

Parameters

Parameters	Parameter Type	Description	Data Type	Required
byoa_id	path	The BYOA ID.	integer	Y

Sample Request URL

DELETE traffic/byoa/12325476455

Sample Response

{
id: 12325476455
}

Sample Error Response

{
"validationMessages": [
{
"message": "BYOA my-test-rule is assigned to 1 or more lines. This BYOA must be removed from lines [7657645768] before it can be deactivated.",
"key": "CUSTOM",
"objectName": "bYOA",
"id": 768765765,
"propertyName": "id"
}
]
}