Bidease Segment API documentation

Modified on Fri, 6 Nov at 10:15 AM

bideaseAPI REFERENCE
Segment API
Manage segments — target lists and suppression lists — on the Bidease platform. Send MAID (IDFA/GAID) payloads, plain or SHA-256 hashed, via a hosted URL or a direct CSV upload.
⚿
One token, one advertiser
Every request carries the ApiToken header; each token is scoped to exactly one advertiser.
#
SegmentID is the handle
Create returns a SegmentID used by every later update, sync and delete call.
⚠
Suppression needs verification
Suppression lists can be synced only after your Bidease account manager verifies them.
REFERENCE
Managing Segments
1
Base URL & authentication

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

BASEhttps://ui-api.bidease.com/
HeaderValue
ApiToken<your_token> — provided by your Bidease account manager

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

ⓘ
Token lost or leaked? Contact your Bidease account manager: they will share a new token with you and disable the old one.
2
Segment containers

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:

FieldDescription
ExternalIDA string you choose, unique per advertiser. Use it as a stable handle your system can correlate with the container.
TitleA free-form name; doesn't need to be unique. Defaults to ExternalID if omitted on create.
BundleListList of app bundles (e.g. Android — com.android.test, iOS — id123456789). The iOS id prefix is normalized on the server side. Required when IsSuppression=true.
IsSegmentFlag: the container is a target list.
IsSuppressionFlag: the container is a suppression list. At least one of the two flags must be true on create.
RecordTypeFormat of every row you sync: uuidv4 (default) — plain IDFA/GAID, or sha256 — SHA-256 hashed IDFA/GAID (see MAID file format). Set on create; it can't be changed later.
ⓘ
Store the SegmentID: the SegmentID returned by Create is the integer primary key used by every subsequent update / delete / sync call. Store it next to your ExternalID.
3
Create
POST/api/s2s/v1/segment-container/create
REQUEST EXAMPLE
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
         }'
REQUEST EXAMPLE — SHA-256 HASHED CONTAINER
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-sha256",
           "Title": "Inactive 30d (hashed)",
           "BundleList": ["com.android.test", "id1023456789"],
           "IsSegment": true,
           "IsSuppression": false,
           "RecordType": "sha256"
         }'
SUCCESSFUL RESPONSE (TRUNCATED)
{
  "ResponseStatus": 0,
  "SegmentList": {
    "Data": [
      {
        "SegmentID": 1234,
        "ExternalID": "inactive-30d",
        "Comment": "Inactive 30d",
        "IsSegment": true,
        "IsSuppression": false,
        "RecordType": "uuidv4",
        "SuppressionVerificationStatus": "unverified",
        "Status": "Initial"
      }
    ],
    "PrimaryKey": "segmentID"
  }
}
CodeDescription
5Missing / invalid ApiToken, or the token is not bound to a single advertiser.
6One of the bundles is not allowed for the authenticated advertiser (the response message lists the offending ones).
10Validation failed (missing ExternalID, both flags false, suppression without bundles, etc.).
805A container with this ExternalID already exists for this advertiser.
4
Update

Looks up the container by SegmentID. Mutable fields:

POST/api/s2s/v1/segment-container/update
FieldBehavior
ExternalIDRename. Partial: empty leaves the existing value untouched.
TitleRename. Partial: empty leaves the existing value untouched.
IsSegmentAlways applied — send the desired value explicitly.
⚠️
Not changeable: BundleList, IsSuppression and RecordType cannot be changed via this endpoint. Recreate the container if you need to change any 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
         }'
CodeDescription
806No container with the specified SegmentID is owned by this advertiser.
805The new ExternalID collides with another container for this advertiser.
5
Sync via hosted URL

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

POST/api/s2s/v1/segment-container/sync-url
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"
         }'
CodeDescription
806Container not found.
807Url is missing or not a valid absolute http or https URL.
808The container is a suppression list and has not been verified yet (see Suppression verification).
6
Sync via CSV upload

Use this method for one-time uploads when you cannot host the file. The request is multipart/form-data: the JSON payload goes in the form field value, and the CSV goes as a regular file part (the file name doesn't matter).

POST/api/s2s/v1/segment-container/sync-file
ⓘ
Body limit: 500 MB.
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"
CodeDescription
10No file part in the request.
806Container not found.
808The suppression container is not verified yet.
810The file has more than 5,000,000 rows in a sha256 container.
7
Delete

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

POST/api/s2s/v1/segment-container/delete
⚠️
Cannot be restored. The container's ExternalID becomes free again, so you can create 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
         }'
CodeDescription
806Container not found.
8
List

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

POST/api/s2s/v1/segment-container/list
ⓘ
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 '{}'
9
Suppression verification

A container created with IsSuppression=true starts with SuppressionVerificationStatus=unverified.

StatusSync (URL or CSV)
unverifiedRejected with 808 / SuppressionNotVerified.
verifiedWorks normally. Your Bidease account manager sets this status after verifying the container internally.
rejectedBlocked permanently. Contact your Bidease account manager if you need a re-review.
10
MAID file format

Each line of the CSV file, whether hosted at a URL or uploaded directly, must hold one value in the container's RecordType. One container holds one format:

RecordTypeLine format
uuidv4A UUIDv4 device identifier (IDFA / GAID).
sha25664 hex characters: lower(sha256(upper(IDFA))) on iOS, lower(sha256(lower(GAID))) on Android.
■
Rows in another format are dropped, including a CSV header and any line with a second column
■
Once processing completes, the counts of accepted and rejected rows appear in the segment's ItemsSuccess and ItemsFailed fields
EXAMPLE UUIDV4 PAYLOAD
b402cda0-c07b-4d9f-9787-ffa1aa7ee916
23C12F79-066E-446B-BCED-08EA6F3EAC43
8100ceab-2201-48b9-bbb5-e52ddca856d8
B8944321-FC2D-407D-9C77-B7203A11E857
EXAMPLE SHA256 PAYLOAD
a45778f177857de7e5950111377e9eb642df346dc164a6c5d835adc967cca17d
c5e5ff33328150bf827f4a73227a143fb10e2b5f0ed984f1e53c1d28bd0ec39b
bc8090c1ebf53ad08aa132b9914d2bd3e9e0d3da7ee67b3a9a8a85efead6a6ba
a0527e9b92a519301269fd07afd2503e2b915b61fca680fb4cd62b788fdd7dba
ⓘ
Hashed lists: each load matches sha256 rows against devices Bidease has seen in the previous 90 days. A valid hash with no match still counts towards ItemsSuccess but adds no device, so ItemsSuccess can be higher than the number of devices in the segment, and a payload with no matches still ends with Status success. A sha256 payload can hold up to 5,000,000 rows: sync-file rejects a larger one with 810, sync-url ends with Status failure and FailureReason sha256RowLimitExceeded.
11
Error codes

The integer is returned as ResponseStatus in the standard response envelope.

CodeNameDescription
0SuccessCorrect request.
5AuthErrorMissing token, multi-advertiser token, expired token, etc.
6ForbiddenA bundle in BundleList doesn't belong to this advertiser.
10ValidationErrorRequest contract violation (missing required field, both flags false, suppression without bundles, missing file in multipart sync, etc.).
805ExternalSegmentIDAlreadyExistsCreate / rename collides with an existing container's ExternalID for this advertiser.
806ExternalSegmentContainerNotFoundSegmentID doesn't resolve to a container owned by this advertiser.
807ExternalSegmentUrlInvalidsync-url received a missing, malformed or non-http(s) URL.
808SuppressionNotVerifiedSync attempted on an unverified suppression container.
810SegmentSha256RowLimitExceededsync-file received more than 5,000,000 rows for a sha256 container.
12
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 Title per container. Recommended format: appname_os_info_date (e.g. google_aos_installs_0602)
■
For suppression containers, plan one round-trip with your Bidease account manager 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: one value per line in the container's RecordType, no headers, no trailing metadata
bidease
Grow Your App with Ease
Questions? Contact your Bidease account manager
support@bidease.com

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article