Bidease Segment API documentation

Modified on Tue, 28 Oct at 9:11 AM

Overview

This API allows advertisers to create and manage device segment lists (IDFA / GAID) programmatically.

The process includes two main steps:

Managing segment containers (creating, updating, deleting, listing).
Uploading device IDs to a container via a hosted file.

All requests must be authenticated with a valid Bearer token, which can be provided by your Bidease account manager.

API Endpoint: https://ui-api.bidease.com/

1. Segment Container Management

A segment container is a logical unit that groups users based on shared characteristics (e.g., "Installed but inactive for 30 days").

Each container includes the following fields:

title — container name (string).
bundle_list — list of app identifiers (e.g., id1023456789 for iOS or com.android.test for Android).
is_suppression — boolean:
- true — the container will be used as a suppression list (excluded from targeting).
- false — the container will be used as a regular targeting list.

{
    "title": "String",
    "bundle_list": ["String", "String"],
    "is_suppression": "Boolean"
}

1.1 Create a container

Method: POST /api/s2s/v1/segment-container/create

Request body:

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

Response example:

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

Note: If a container with the same title already exists, the API will return an error.

1.2 Update a Container

Method: POST /api/s2s/v1/segment-container/update

Updatable fields: title, bundle_list, is_suppression

Request body:

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

Response example:

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

1.3 Delete a Container

Method: POST /api/s2s/v1/segment-container/delete

Warning: Once deleted, a container cannot be restored.

Request body:

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

Response example:

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

1.4 List All Containers

Method: GET /api/s2s/v1/segment-container/list

Request body:

{}

Response example:

{
  "status": 0,
  "status_message": "",
  "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
    }
  ]
}

Pagination is not required. Typically, an account has no more than ~1000 containers.

2. Device ID List Synchronization

Once a container is created, you can upload device identifiers via a hosted CSV file.

2.1 Start Device List Sync

Method: POST /api/s2s/v1/segment-container/sync

Request body:

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

Behavior:

All previously uploaded device IDs for this container will be replaced.
The new list from the provided url will be added.
Only UUID v4 format is supported. Any invalid rows (including CSV headers) will be ignored

Response example:

{
  "status": 0,
  "status_message": ""
}

3. Error Codes

0	Success
1	Invalid or missing auth key
100	Container with the specified title already exists
101	Container with the specified id not found or deleted
102	Invalid url format for synchronization process

4. Best Practices & Tips

Make sure your Bearer token is valid and has access to segment API.
Choose a clear and unique title for each container — this makes management easier.
Validate your device ID file before uploading:
- Use only UUID v4 format.
- Remove headers or metadata
Remember: deleted containers cannot be restored.
Use bundle_list to target specific apps.
If is_suppression = true, the container will be used as an exclusion list, not for targeting.