How advertiser could upload segment lists with API

Modified on Tue, 6 Feb at 12:51 PM

Segment synchronization specification:

Overall synchronization contains two parts: container (segment) synchronization and device-id list synchronization

Authorization is based under passing auth key in headers (Bearer auth) which will be shared by Bidease team or could be accessed via Bidease dashboard

The prefix for API endpoint is https://ui-api.bidease.com

1. Container synchronization

Container (segment of devices) is a logical unit of data storage which has the following params:

• title (name of the container) - eg Installed but not active for 30 days

list of bundles (app ids like id1023456789 for iOS or com.android.test for Android)
is_suppression (if true, then all devices from this container will be marked as suppression and will be removed from UA targeting and could be used only for retargeting)
```
{
    "title": "String",
    "bundle_list": ["String", "String"],
    "is_suppression": "Boolean"
} 
```

1.1. create container method - POST /api/s2s/v1/segment-container/ create

Method creates new container with specified params. If container with specified title already exists, then method will return error

request:

{
        "container": {
                "title": "Installed but not active for 30 days", 
                "bundle_list": ["id1023456789", "com.android.test"], "is_suppression": false
    }
}

response:

{ "status": 0, // 0 is fine otherwise is error "status_message": "", // error message if not empty "container": {

"id": "10", // container id "title": "Installed but not active for 30 days",

"bundle_list": ["id1023456789", "com.android.test"],

"is_suppression": false

} }

1.2. update container method - POST /api/s2s/v1/segment-container/ update

Possible to update:

• title
• list of bundles

• is_suppression

request:

{
    "container": {
            "id": "10",
            "title": "Test segment 2",
            "bundle_list": ["id1023456789", "com.android.test","com.google"], 
            "is_suppression": true 
    }
}

response:

{
    "status": 0, // 0 is fine otherwise is error 
    "status_message": "", // error message if not empty 
    "container": {
            "id": "10", // container id
            "title": "Test segment 2",
            "bundle_list": ["id1023456789", "com.android.test", "com.google"], 
            "is_suppression": true
    }
}

1.3. delete container method - POST /api/s2s/v1/segment-container/ delete

Container with segment will be marked as deleted and will be removed from target devices. It is not possible to rollback this operation

request:

{
    "container": {
            "id": "10"
    }
}

response:

{
    "status": 0, // 0 is fine otherwise is error 
    "status_message": "", // error message if not empty 
    "container": {                                "id": "10", // container id
            "title": "Test segment 2",
            "bundle_list": ["id1023456789", "com.android.test", "com.google"], 
            "is_suppression": true                    
    }
}

1.4. list containers method - GET /api/s2s/v1/segment-container/list

request

{}

response

{ "status": 0, // 0 is fine otherwise is error "status_message": "", // error message if not empty "container_list": [

{ "id": "10",

"title": "Test segment 2", "bundle_list": ["id1023456789", "com.android.test","com.google"], "is_suppression": true },

{

"id": "12", "title": "Test segment 3",

"bundle_list": [],

"is_suppression": false

]

}

return all containers for specified auth (reasonable assumption that there wouldn’t be more than 1000 containers for the same auth entity therefore no pagination is needed)

2. Device-id list synchronization

2.1. create device-id list method - POST /api/s2s/v1/segment- container/sync

Only files with a list of device_id (IDFA/GAID) are supported All records (including header row in CSV) which couldn’t be parsed as UUIDv4 will be ignored This method set a task for specified container synchronization process using specified url with list of devices to sync:

• previously synced devices will be removed from container

• new devices will be added to container

request

{
        "container": {
                "id": "10", 
                "url": "https://example.com/device-id-list.csv"
        }
}

response

{ "status": 0, // 0 is fine otherwise is error "status_message": "" // error message if not empty

}

3. List of possible errors which are passed to the status field in response

• 0 - the request successfully processed
• 1 - wrong auth key or auth key is not specified
• 100 - container with specified title already exists
• 101 - container with specified id not found or deleted • 102 - wrong url format for container sync process