---
title: "Bring Your Own Algorithm (BYOA) API"
slug: "bring-your-own-algorithm-byoa-api"
updated: 2026-08-03T17:47:33Z
published: 2026-08-03T17:48:18Z
canonical: "help.yahooinc.com/bring-your-own-algorithm-byoa-api"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.yahooinc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/dsp-api/docs/bring-your-own-algorithm-byoa-api#read-byoa-rules-by-account-id-name-or-id).
- Use the`GET` method to [read lines associated with a BYOA rule](/dsp-api/docs/bring-your-own-algorithm-byoa-api#read-lines-associated-with-the-byoa-rule).
- Use the `POST` method to [create a BYOA rule](/dsp-api/docs/bring-your-own-algorithm-byoa-api#create-import-byoa-rule).
- Use the `PUT` method to [update an existing BYOA rule](/dsp-api/docs/bring-your-own-algorithm-byoa-api#update-a-byoa-rule).
- Use the `DELETE` method to [remove an existing BYOA rule](/dsp-api/docs/bring-your-own-algorithm-byoa-api#delete-a-byoa-rule).
- Use the `PUT` method on the `lines` endpoint to [assign or remove a BYOA rule](/dsp-api/docs/bring-your-own-algorithm-byoa-api#byoa-lines-api) from a line.

## 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.

```plaintext
GET traffic/byoa/account/{accountId}
```

#### Parameters

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

#### Sample Request

```plaintext
GET traffic/byoa/account/987654321
```

#### Sample Response

```json
[
   {"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.

```plaintext
GET traffic/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

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

#### Sample Response

For a rule that only has one version:

```json
["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:

```json
"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.

```plaintext
GET traffic/byoa/{byoa_id}
```

#### Parameters

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

#### Sample Request

```plaintext
GET traffic/byoa/12345966
```

#### Sample Response

```json
{
    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.

```plaintext
GET traffic/byoa/{byoa_id}/lines
```

### Parameters

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

### Sample Request

```plaintext
GET traffic/byoa/6766876/lines
```

### Sample Response

```json
{
"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.

```plaintext
POST traffic/byoa
```

### Parameters

All fields are specified in the request body.

### Sample Request

```plaintext
POST traffic/byoa
```

### Sample Request Body

```json
  {
    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

```json
{
  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.

```plaintext
PUT traffic/byoa
```

### Parameters

All fields are specified in the request body.

### Sample Request URL

```plaintext
PUT traffic/byoa/{byoa_id}
```

### Sample Request Body

```json
{
    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

```json
{
  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.

```plaintext
DELETE traffic/byoa/{byoa_id}
```

### Parameters

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

### Sample Request URL

```plaintext
DELETE traffic/byoa/12325476455
```

### Sample Response

```json
{
id: 12325476455
}
```

### Sample Error Response

```json
{
"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"
}
]
}
```

## BYOA Lines API

Use the `PUT` method to assign or remove a BYOA rule on a line.

### Assign a BYOA Rule to a line

Assign an existing BYOA rule to a line.

```plaintext
PUT traffic/lines/{line_id}/byoa
```

#### Parameters

| Parameters | Parameter Type | Description | Data Type | Required |
| --- | --- | --- | --- | --- |
| `line_id` | path | The Line ID. | `integer` | Y |

#### Sample Request URL

```plaintext
PUT traffic/lines/12345/byoa
```

#### Sample Request Body

```json
{
   “byoaId” : 12,             		              // Integer (current byoa rule id)
   “byoaMultiplierCap”: 4.11                              //Double  byoa rule multiplier
}
```

#### Sample Response

```json
{
    "response": {
        "id": 693013,
        "name": "BYOA Test Line1",
        "orderId": 127495,
        "bidPrice": 4.11,
        "goalAmount": 0.0,
        "maxGoal": 0.0,
        "marginGoal": 25.0,
        "billingPrice": 5.0,
        "pacingAcceleration": 100,
        "isNativeEnabled": false,
        "channelType": "DEFAULT",
         …
        "mediaType": "DISPLAY",
        "goalModeType": "SOFT",
        "goalType": "NONE",
        "billingMethodType": "MARGIN",
        "marginType": "TOTAL_BUDGET",
        "budgetType": "CURRENCY",
    ….
    "errors": null,
    "timeStamp": "2025-10-29T09:34:39.993Z"
}
```

### Remove a BYOA Rule from a line

Remove an existing BYOA rule from a line.

```plaintext
PUT traffic/lines/{line_id}/byoa
```

#### Parameters

| Parameters | Parameter Type | Description | Data Type | Required |
| --- | --- | --- | --- | --- |
| `line_id` | path | The Line ID. | `integer` | Y |

#### Sample Request URL

```plaintext
PUT traffic/lines/3413/byoa
```

#### Sample Request Body

```json
{
   “byoaId” : null,             		              // Integer (current byoa rule id)
   “byoaMultiplierCap”: null                              //Double  byoa rule multiplier
}
```

#### Sample Response

```json
{
    "response": {
        "id": 693013,
        "name": "BYOA Test Line1",
        "orderId": 127495,
        "bidPrice": 4.11,
        "goalAmount": 0.0,
        "maxGoal": 0.0,
        "marginGoal": 25.0,
        "billingPrice": 5.0,
        "pacingAcceleration": 100,
        "isNativeEnabled": false,
        "channelType": "DEFAULT",
         …
        "mediaType": "DISPLAY",
        "goalModeType": "SOFT",
        "goalType": "NONE",
        "billingMethodType": "MARGIN",
        "marginType": "TOTAL_BUDGET",
        "budgetType": "CURRENCY",
    ….
    "errors": null,
    "timeStamp": "2025-10-29T09:34:39.993Z"
}
```