Bidease Segment API documentation
Modified on Fri, 6 Nov at 10:15 AM

All Segment API endpoints are server-to-server (S2S) and live under the api/s2s/v1/segment-container/ prefix.
| Header | Value |
|---|---|
| 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.
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:
| Field | Description |
|---|---|
| ExternalID | A string you choose, unique per advertiser. Use it as a stable handle 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. Required when IsSuppression=true. |
| IsSegment | Flag: the container is a target list. |
| IsSuppression | Flag: the container is a suppression list. At least one of the two flags must be true on create. |
| RecordType | Format 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. |
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
}'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"
}'{
"ResponseStatus": 0,
"SegmentList": {
"Data": [
{
"SegmentID": 1234,
"ExternalID": "inactive-30d",
"Comment": "Inactive 30d",
"IsSegment": true,
"IsSuppression": false,
"RecordType": "uuidv4",
"SuppressionVerificationStatus": "unverified",
"Status": "Initial"
}
],
"PrimaryKey": "segmentID"
}
}| Code | Description |
|---|---|
| 5 | Missing / invalid ApiToken, or the token is not bound to a single advertiser. |
| 6 | One of the bundles is not allowed for the authenticated advertiser (the response message lists the offending ones). |
| 10 | Validation failed (missing ExternalID, both flags false, suppression without bundles, etc.). |
| 805 | A container with this ExternalID already exists for this advertiser. |
Looks up the container by SegmentID. Mutable fields:
| Field | Behavior |
|---|---|
| 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. |
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
}'| Code | Description |
|---|---|
| 806 | No container with the specified SegmentID is owned by this advertiser. |
| 805 | The new ExternalID collides with another container for this advertiser. |
Triggers an asynchronous fetch of the MAID (IDFA/GAID) CSV file from Url. Previously uploaded MAIDs are replaced.
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"
}'| Code | Description |
|---|---|
| 806 | Container not found. |
| 807 | Url is missing or not a valid absolute http or https URL. |
| 808 | The container is a suppression list and has not been verified yet (see Suppression verification). |
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).
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"| Code | Description |
|---|---|
| 10 | No file part in the request. |
| 806 | Container not found. |
| 808 | The suppression container is not verified yet. |
| 810 | The file has more than 5,000,000 rows in a sha256 container. |
Soft-removes the container; the bidder stops using it on the next state refresh.
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
}'| Code | Description |
|---|---|
| 806 | Container not found. |
Returns every container owned by the authenticated advertiser, most recently updated first.
curl -X POST "https://ui-api.bidease.com/api/s2s/v1/segment-container/list" \
-H "ApiToken: <your_token>" \
-H "Content-Type: application/json" \
-d '{}'A container created with IsSuppression=true starts with SuppressionVerificationStatus=unverified.
| Status | Sync (URL or CSV) |
|---|---|
| unverified | Rejected with 808 / SuppressionNotVerified. |
| verified | Works normally. Your Bidease account manager sets this status after verifying the container internally. |
| rejected | Blocked permanently. Contact your Bidease account manager if you need a re-review. |
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:
| RecordType | Line format |
|---|---|
| uuidv4 | A UUIDv4 device identifier (IDFA / GAID). |
| sha256 | 64 hex characters: lower(sha256(upper(IDFA))) on iOS, lower(sha256(lower(GAID))) on Android. |
b402cda0-c07b-4d9f-9787-ffa1aa7ee916 23C12F79-066E-446B-BCED-08EA6F3EAC43 8100ceab-2201-48b9-bbb5-e52ddca856d8 B8944321-FC2D-407D-9C77-B7203A11E857
a45778f177857de7e5950111377e9eb642df346dc164a6c5d835adc967cca17d c5e5ff33328150bf827f4a73227a143fb10e2b5f0ed984f1e53c1d28bd0ec39b bc8090c1ebf53ad08aa132b9914d2bd3e9e0d3da7ee67b3a9a8a85efead6a6ba a0527e9b92a519301269fd07afd2503e2b915b61fca680fb4cd62b788fdd7dba
The integer is returned as ResponseStatus in the standard response envelope.
| Code | Name | Description |
|---|---|---|
| 0 | Success | Correct request. |
| 5 | AuthError | Missing token, multi-advertiser token, expired token, etc. |
| 6 | Forbidden | A bundle in BundleList doesn't belong to this advertiser. |
| 10 | ValidationError | Request contract violation (missing required field, both flags false, suppression without bundles, missing file in multipart sync, etc.). |
| 805 | ExternalSegmentIDAlreadyExists | Create / rename collides with an existing container's ExternalID for this advertiser. |
| 806 | ExternalSegmentContainerNotFound | SegmentID doesn't resolve to a container owned by this advertiser. |
| 807 | ExternalSegmentUrlInvalid | sync-url received a missing, malformed or non-http(s) URL. |
| 808 | SuppressionNotVerified | Sync attempted on an unverified suppression container. |
| 810 | SegmentSha256RowLimitExceeded | sync-file received more than 5,000,000 rows for a sha256 container. |
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
Feedback sent
We appreciate your effort and will try to fix the article