Bidease Segment API documentation

Segment API

Segment API gives access to managing segments (target lists and suppression lists) on the Bidease platform. MAID (IDFA/GAID) payloads can be sent via a hosted URL or via direct CSV upload.

Base URL:

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

All Segment API endpoints are server-to-server (S2S) and live under the api/s2s/v1/segment-container/ prefix.

Authentication

Every request must include a bearer-style token in the ApiToken HTTP header. The token can be provided by your Bidease CSM.

ApiToken: <your_token>

Each token is scoped to exactly one advertiser. Requests sent with a token that is not bound to a single advertiser will be rejected with 5 / AuthError.

If a token is forgotten, leaked, or needs to be rotated, contact your Bidease CSM. They will share a new token with you and disable the old one.

Container Management

A segment container is a logical group of MAIDs (IDFA/GAID) that the Bidease bidder uses for targeting or suppression during real-time bidding. Each container has:

• ExternalID - a string you choose. Unique per advertiser. Use it as the stable handle that your system can correlate with the container.
• Title - a free-form name. Doesn't need to be unique. Defaults to ExternalID if omitted on create.
• BundleList - list of app bundles (e.g. Android - com.android.test, iOS - id123456789). The iOS id prefix is normalized on the server side. BundleList is required when IsSuppression=true.
• IsSegment / IsSuppression - flags. At least one of them must be true on create.

SegmentID returned by Create is the integer primary key used by every subsequent update / delete / sync call. Store it locally next to your ExternalID.

Create

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

curl -X POST "https://ui-api.bidease.com/api/s2s/v1/segment-container/create" \
     -H "ApiToken: <your_token>" \
     -H "Content-Type: application/json" \
     -d '{
           "ExternalID": "inactive-30d",
           "Title": "Inactive 30d",
           "BundleList": ["com.android.test", "id1023456789"],
           "IsSegment": true,
           "IsSuppression": false
         }'

Successful response (truncated):

{
  "ResponseStatus": 0,
  "SegmentList": {
    "Data": [
      {
        "SegmentID": 1234,
        "ExternalID": "inactive-30d",
        "Comment": "Inactive 30d",
        "IsSegment": true,
        "IsSuppression": false,
        "SuppressionVerificationStatus": "unverified",
        "Status": "Initial"
      }
    ],
    "PrimaryKey": "segmentID"
  }
}

Errors:

Update

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

• ExternalID - rename. Partial. Empty leaves the existing value untouched.
• Title - rename. Partial. Empty leaves the existing value untouched. 
• IsSegment - always applied. Send the desired value explicitly.

BundleList and IsSuppression cannot be changed via this endpoint. Recreate the container if you need to change either of them.

Request example:

curl -X POST "https://ui-api.bidease.com/api/s2s/v1/segment-container/update" \
     -H "ApiToken: <your_token>" \
     -H "Content-Type: application/json" \
     -d '{
           "SegmentID": 1234,
           "Title": "Inactive 30d (renamed)",
           "IsSegment": true
         }'

Errors:

Sync via hosted URL

POST /api/s2s/v1/segment-container/sync-url

Triggers an asynchronous fetch of the MAID (IDFA/GAID) CSV file from Url. Previously uploaded MAIDs are replaced.

Request example:

curl -X POST "https://ui-api.bidease.com/api/s2s/v1/segment-container/sync-url" \
     -H "ApiToken: <your_token>" \
     -H "Content-Type: application/json" \
     -d '{
           "SegmentID": 1234,
           "Url": "https://example.com/devices.csv"
         }'

Errors:

Sync via CSV upload (multipart/form-data)

POST /api/s2s/v1/segment-container/sync-file

This method should be used for one-time uploads when you cannot host the file.

Body limit is 500 MB.

JSON payload goes in the form field value, and the CSV goes as a regular file part (file name doesn't matter).

Request example:

curl -X POST "https://ui-api.bidease.com/api/s2s/v1/segment-container/sync-file" \
     -H "ApiToken: <your_token>" \
     -F 'value={"SegmentID":1234};type=application/json' \
     -F "file=@devices.csv;type=text/csv"

Errors:

Delete

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

Soft-removes the container. Bidder stops using it on the next state refresh.

The container cannot be restored, but its ExternalID becomes free again, so you can recreate a new container with the same ExternalID.

Request example:

curl -X POST "https://ui-api.bidease.com/api/s2s/v1/segment-container/delete" \
     -H "ApiToken: <your_token>" \
     -H "Content-Type: application/json" \
     -d '{
           "SegmentID": 1234
         }'

Errors:

List

POST /api/s2s/v1/segment-container/list

Returns every container owned by the authenticated advertiser. Ordered by most recently updated first.

No pagination - typical advertisers have fewer than 1,000 containers.

Request example:

curl -X POST "https://ui-api.bidease.com/api/s2s/v1/segment-container/list" \
     -H "ApiToken: <your_token>" \
     -H "Content-Type: application/json" \
     -d '{}'

Suppression Verification

A container created with IsSuppression=true starts with SuppressionVerificationStatus=unverified. Sync attempts (via URL or CSV) on an unverified suppression container are rejected with code 808 / SuppressionNotVerified.

Once your Bidease CSM verifies the container internally and changes its status to verified, sync requests will succeed normally.

Containers with a rejected status keep sync blocked permanently. Contact your Bidease CSM if you need a re-review.

MAID (IDFA/GAID) file format

Each line of the CSV file (whether hosted as a URL or uploaded directly) must be a UUIDv4.

Rows that cannot be parsed as UUIDv4 (including a CSV header) will be dropped.

The counts of accepted and rejected rows will appear in the segment's ItemsSuccess and ItemsFailed fields once processing completes.

Example payload:

b402cda0-c07b-4d9f-9787-ffa1aa7ee916
23C12F79-066E-446B-BCED-08EA6F3EAC43
8100ceab-2201-48b9-bbb5-e52ddca856d8
B8944321-FC2D-407D-9C77-B7203A11E857

Error codes summary

The integer goes on the wire as ResponseStatus in the standard envelope.

Best practices

• SegmentID returned from Create is the stable handle for every subsequent call. ExternalID is yours to rename - don't use it as a database key.
• Choose a meaningful and unique ExternalID per container (e.g. inactive-30d, vip-q2-2026).
• Choose an understandable value for Title per container. Recommended format: appname_os_info_date (e.g. google_aos_installs_0602).
• For suppression containers, plan one round-trip with your CSM after creation to flip SuppressionVerificationStatus to verified before the first sync.
• Prefer sync-url for large or recurring pushes - it leaves you in control of the CSV file and avoids tying up the request socket for the upload.
• Validate your MAID file before uploading: UUIDv4 only, no headers, no trailing metadata.