BidSlammer Help: Api-documentation

New User Questions

API Documentation

Our API is for developers or computer-savvy customers. You can use it to create applications, or make shortcuts using your own tools and utilities, such as AppleScript.

You can use the API from any program that can fetch URLs. Manage your snipes in a custom way that you create! For questions of usage or terms for high-volume usage, please contact us.

To access the API, you will need an API key. This is located in your Preferences tab, which you can see in the top navigation bar after you log in. Please note: The API requires a Power Pack upgrade.

Here's a working URL: https://api.bidslammer.com/justTesting?key=test-api-key&arg1=Hello&arg2=World!

Note: A paid account is required to use the API.

Available Methods

Secondary Functions

archiveItem
deleteSearch
getAllBidders
getBidGroupItems
getGalleryImages
getItemImages
getUserLogEntries
importBidList
importWatchList

justTesting

justTesting is for trying out the API.

Parameter	Type	Description
`key`	string	(required) Your API key.
`arg1`	string	(required) Any value; it will be returned in the response.
`arg2`	string	(optional) Any value; it will be returned in the response.
`arg3`	string	(optional) Any value; it will be returned in the response.

Sample Call

https://api.bidslammer.com/justTesting?key={API_KEY}&arg1=Hello%2C+World

Returns:

{
    "status": "OK",
    "message": "Well, the API seems to be working.",
    "arg1": "Hello, World",
    "arg2": "",
    "arg3": "",
    "version": "1",
    "timestamp": "2020-03-01 21:41:53"
}

addBid

addBid is for adding a snipe bid.

parameter	type	description
`key`	string	(required) Your API key.
`item_no`	integer	(required) The item number.
`bid`	float(2)	(optional) The bid amount. Default is zero (0.00).
`newGroupName`	string	(optional) (text) The name of the Bid Group to add the snipe to.
`delay`	integer	(optional) (integer) The number of seconds of lead time before the snipe is placed. Values can be: Integers of value 1 through 15 only.
`enabled`	boolean	(optional) 0 or 1. Turn the snipe on or off.
`force`	boolean	(optional) 0 or 1. Whether or not to force the bid amount even if it is lower than a bid that will win. If set to 1, then the bid will always be overridden, even if that value will lose.

Note: Once a new group is created, always refer to it using its `group_id`. If you specify the same `newGroupName` again, it will use the same group, as long as you have used `addBid` on that group within the last ten (10) days. In other words, each time you call `addBid` with the same `newGroupName`, it resets the group's last-used date, so a new group with the same name but a different `group_id` is not created. This behavior exists for three reasons:

To ensure the UI drop-down only displays recently active groups.
To allow reuse of group names without confusion.
To prevent mistakenly reactivating an old group just because it shares a name.

For example, if you created a group named "Star Wars" last month, and then create another group with the same name today, the system treats them as separate—unless the original `groupName` was recently active.

Sample Call

https://api.bidslammer.com/addBid?key={API_KEY}&item_no=123456789012&bid=0.01&force=1

Returns:

{
    "bid": "0.01",
    "delay": 7,
    "group_id": 123456,
    "groupName": "Test group",
    "item_no": "153847324676",
    "status": "OK",
    "alert": "success",
    "short_message": "Bid added for 0.01.",
    "message": "You successfully added a snipe for 0.01 on eBay item #153847324676.",
    "message_color": "green",
    "new_snipe": true
}

Determining a Win: When checking snipe results, always verify that success equals 1. This is the definitive way to confirm a win. Do not rely on the highBidder field, as it may not accurately reflect the final auction outcome.

deleteBid

deleteBid will delete a snipe entirely from the system (if you own the snipe).

Parameter	Type	Description
`key`	string	(required) Your API key.
`item_no`	integer	(required) The item number.

Sample Call

https://api.bidslammer.com/deleteBid?key={API_KEY}&item_no=123456789012

addSearch

addSearch adds a search to your "Saved Searches" list.

Parameter	Type	Description
`key`	string	(required) Your API key.
`query`	string	(required) The search query to add (max 255 characters).

Sample Call

https://api.bidslammer.com/addSearch?key={API_KEY}&country_code=US&query=Beanie+Babies

fetchItem

fetchItem will fetch the latest information for an eBay item number that exists in your account. Note: This endpoint is restricted to active snipes only and cannot be used for general item lookups.

Parameter	Type	Description
`key`	string	(required) Your API key.
`item_no`	integer	(required) The item number.

Note: Sometimes an auction will turn into a Fixed Price auction. In this case, you will fetch the data for that auction, but it returns the old auction data. This is because the seller can cancel the auction and say it's out of stock. Then it is re-listed as a Fixed Price listing with 0 quantity. It is a loophole that sellers use to preserve the listing’s watch count, traffic history, and/or feedback record.

Sample Call

https://api.bidslammer.com/fetchItem?key={API_KEY}&item_no=123456789012

Returns:

{
    "status": "OK",
    "alert": "success",
    "bids": 0,
    "cost": 9.99,
    "ends": "2020-03-05 09:03:08",
    "eBayItemId": 153847324676,
    "currentPrice": 9.99,
    "currency": "USD",
    "country": "US",
    "sellerPercent": 100,
    "sellerScore": 0,
    "sellerUserId": "chinese*food*is*good",
    "shippingType": "Calculated",
    "startTime": "2020-02-27 09:03:08",
    "timeLeft": "8h 8m",
    "category": "Everything Else:Test Category For Internal Use Only Parent Level 2:General",
    "endTime": "2020-03-05 09:03:08",
    "pictureURL": "https://i.ebayimg.com/00/s/NDgwWDY0MA==/z/nicAAOSwi5xeMhKl/$_12.JPG?set_id=880000500F",
    "title": "Coconut Lime Verbena Pineapple Cilantro Two Wicked 16oz",
    "images": [
        "https://i.ebayimg.com/00/s/NDgwWDY0MA==/z/nicAAOSwi5xeMhKl/$_12.JPG?set_id=880000500F",
        "https://i.ebayimg.com/00/s/NDgwWDY0MA==/z/wq0AAOSwUMpeMhK1/$_12.JPG?set_id=880000500F",
        "https://i.ebayimg.com/00/s/NDgwWDY0MA==/z/bBQAAOSwPMpeMhK2/$_12.JPG?set_id=880000500F",
        "https://i.ebayimg.com/00/s/NDgwWDY0MA==/z/XbIAAOSwepleMhK2/$_12.JPG?set_id=880000500F",
        "https://i.ebayimg.com/00/s/NDgwWDY0MA==/z/PjYAAOSwmoheMhK3/$_12.JPG?set_id=880000500F",
        "https://i.ebayimg.com/00/s/NDgwWDY0MA==/z/EgsAAOSwW1NeMhK4/$_12.JPG?set_id=880000500F",
        "https://i.ebayimg.com/00/s/NDgwWDY0MA==/z/CLoAAOSw1T1eMhK5/$_12.JPG?set_id=880000500F"
    ],
    "message": ""
}

checkSnipeStatus

checkSnipeStatus will give win/loss status of the item. If a loss, will give the reason. If the snipe has not executed, it will return a status of "Pending."

Note: eBay sometimes requires up to 5 minutes to confirm status on a bid, so always wait at least 5 minutes after the auction closes to make this API call.

Parameter	Type	Description
`item_no`	integer	Required. The eBay item number to check.

To check for a definite win, check success == 1. This indicates the system successfully queried eBay's API and received confirmation that the auction was won.

Sample Call

https://api.bidslammer.com/fetchItem?key={API_KEY}&item_no=123456789012

Returns:

{
    "bidResult": {
        "success": -7,
        "status": "Minimum Bid Increment Not Met",
        "message": "You did not meet the minimum bid increment for this item.",
        "shorthand": "bid-incr",
        "color": "red"
    },
    "item_info": {
        [same as fetchItem call]
    }
}

getUserItems

getUserItems returns a list of user snipes with all parameters.

Parameter	Type	Description
`key`	string	(Required) Your API key.
`filter`	string	(Required) Specifies which list of items to return: • `watched` — Watch list (bid = 0) • `current` — Pending/current snipes • `completed` — Recently completed snipes • `archive` — Archived snipes (older than 60 days)
`orderby`	string	(Optional) Field to order results by. Possible values: `ends`, `bids`.
`dir`	string	(Optional) Sort direction: `ASC` or `DESC`.
`offset`	integer	(Optional) Number of records to skip in the returned list.
`limit`	integer	(Optional) Maximum number of records to return (max 20).
`show_won`	boolean	(Optional) Set to 1 to include "won" items in the results, or 0 to exclude.

Notes:
- If you specify filter=watched, only items without a bid are returned.
- If you specify filter=current, only active snipes are shown.
- limit cannot be greater than 20.

Sample Call

https://api.bidslammer.com/getUserItems?key={API_KEY}&filter=current

Returns:

A sample JSON response for getUserItems:

[
  {
    "id": 10123,
    "snipe_id": 10123,
    "user_id": 555,
    "item_no": 123456789012,
    "title": "Vintage Star Wars Figure",
    "title_abbrev": "vintage star wars figur...",
    "pictureURL": "https://i.ebayimg.com/images/g/xyz/s-l1600.jpg",
    "item_url": "https://www.ebay.com/itm/123456789012",
    "country": "US",
    "group_id": 0,
    "groupName": null,
    "bid": 49.99,
    "bids": 7,
    "cost": 42.00,
    "cost_unit": "USD",
    "shipping_cost": "5.00",
    "shipping_free": "0",
    "shipping_min": null,
    "shipping_max": null,
    "shipping_priority": null,
    "shipping_service": null,
    "shipping_type": null,
    "hasReservePrice": 0,
    "numberOfImages": 3,
    "seller_userid": "vintoys31",
    "seller_percent": 99.7,
    "seller_score": 3002,
    "success": 1,
    "won": 1,
    "mbi": 1.00,
    "min_bid_incr": 1.00,
    "tableClass": "success",
    "icon_src": "/img/legend_win_trans.png",
    "ends": "2024-07-01 10:59:31",
    "ends_pretty": "Jul 1, 2024",
    "ends_countdown": "3d 04h",
    "alertSet": 0,
    "note": "Want for collection",
    "note_text": "Want for collection",
    "note_date_pretty": "Jun 10",
    "jobs_arr": [
      {
        "fire_time": "2024-07-01 10:59:24",
        "status": "complete"
      }
    ],
    "error_txt": "",
    "error_txt_short": "",
    "fee": 0,
    "overtime": -77322
  },
    // ... more items ...
]

getUserSearches

getUserSearches returns your list of "Saved Searches."

parameter	type	description
`key`	string	(required) Your API key.
`filter`	string	(optional) Text string to limit searches to a filter that you specify.

If you set a filter in your call, only searches whose query contains the filter string will be returned.

Sample Call

https://api.bidslammer.com/getUserSearches?key={API_KEY}

Returns:

[
  {
    "id": 10123,
    "auctions_only": true,
    "cat_id": 6030,
    "enabled": true,
    "last_search": "2024-06-27 12:04:13",
    "major_cat_id": 6,
    "max_price": "75.00",
    "min_price": "10.00",
    "query": "vintage wristwatch",
    "searches": 88,
    "timestamp": "2023-12-30 09:14:10"
  },
  {
    "id": 10122,
    "auctions_only": false,
    "cat_id": 220,
    "enabled": true,
    "last_search": "2024-06-25 18:22:14",
    "major_cat_id": 2,
    "max_price": "45.00",
    "min_price": "",
    "query": "retro camera",
    "searches": 16,
    "timestamp": "2023-07-20 18:55:30"
  }
    // ... more searches
]

getBidderDataset

getBidderDataset gives you a dataset for the bidding history of an item that can be fed directly into Chart.js or QuickChart.io. A second dataset is added that is a horizontal line representing your current snipe value.

parameter	type	description
`key`	string	(required) Your API key.
`item_no`	integer	(required) The item number.

Sample Call

https://api.bidslammer.com/getBidHistoryDataset?key={API_KEY}

Returns:

{
    "status": "OK",
    "data": {
        "datasets": [
            {
                "label": "Bid History",
                "backgroundColor": "#0099c6",
                "borderColor": "#0099c6",
                "fill": false,
                "showLine": true,
                "pointRadius": 4,
                "pointHoverRadius": 12,
                "data": [
                    { "x": 1714944227000, "y": 25.00 },
                    { "x": 1714945227000, "y": 30.00 },
                    { "x": 1714946227000, "y": 35.00 }
                    // ... more bid data points ...
                ]
            },
            {
                "label": "Your Snipe",
                "backgroundColor": "rgba(255,0,0,0.1)",
                "borderColor": "red",
                "borderDash": [10, 5],
                "pointRadius": 0,
                "fill": false,
                "data": [
                    { "x": 1714944227000, "y": 40.00 },
                    { "x": 1714946227000, "y": 40.00 }
                ]
            }
            // ... more datasets ...
        ]
    },
    "item_no": "1234567890",
    "bid": 40.00,
    "timestamp": "2024-06-01T12:45:00Z"
}

getBidHistoryDataset

getBidderDataset gives you a dataset for the bidding history of an item that can be fed directly into Chart.js version 2 or QuickChart.io using version=2. A second dataset is added that is a horizontal line representing your current snipe value.

Parameter	Type	Description
`key`	string	Required. Your API key.
`item_no`	integer	Required. The item number.

Sample Call

https://api.bidslammer.com/getBidHistoryDataset?key=abcd&item_no=1234567890

Returns:

[
{
        "backgroundColor": "#0099c6",
        "borderColor": "#0099c6",
        "borderWidth": 0.25,
        "fill": false,
        "label": "LEGO Star Wars: Ewok Village (10236)",
        "data": [
                {
                        "x": 1714944227000,
                        "y": 600
                },
                {
                        "x": 1715048287000,
                        "y": 600
                },
                {
                        ...
                }
],
"pointRadius": 4,
"pointHoverRadius": 12,
"pointHoverBackgroundColor": "#0099c6",
"showLine": true
},
{
        "borderCapStyle": "round",
        "borderColor": "#0099c6",
        "borderDash": [
                10,
                5
        ],
        "borderWidth": 2,
        "lineTension": 5,
        "data": [
                {
                        "x": 1714653979000,
                        "y": 600
                },
                {
                        "x": 1715084265000,
                        "y": 600
                }
        ],
        "fill": false,
        "label": "Your snipe of 5.00",
        "pointRadius": 1,
        "showLine": true
}
]

getSearchResults

getSearchResults will return search results (up to 100 items) from eBay for a given query.

Parameter	Type	Description
`key`	string	(required) Your API key.
`country_code`	string	(optional) 2-letter country code. Default is `US`. Examples: US, GB, AU.
`query`	string	(required) The search query.

Sample Call

https://api.bidslammer.com/getSearchResults?key={API_KEY}&query=Beanie+Babies

getSuggestedCategories

getSuggestedCategories will return a list of suggested categories for a given search query, and whether or not each category is a leaf category. You can specify the country to get the correct set of categories, since eBay has a different category set for each country.

Parameter	Type	Description
`key`	string	(required) Your API key.
`country`	string	(optional) 2-letter country code (e.g. AU, US, DE, ES, GB, etc.) specifying which set of category numbers to use. Default: US.
`maxResults`	integer	(optional) The maximum number of category suggestions to return. Default: 10.
`query`	string	(required) The search query.

Sample Call

https://api.bidslammer.com/getSuggestedCategories?key={API_KEY}&country=US&maxResults=20&query=Beanie+Babies

Secondary Functions

These utility functions provide additional functionality for managing your account and retrieving supplementary data.

archiveItem

archiveItem moves a completed snipe to your archive. This removes it from your Completed list and places it in the Archive for long-term storage.

Parameter	Type	Description
`key`	string	(required) Your API key.
`item_id`	integer	(required) The snipe ID or item number to archive.

Sample Call

https://api.bidslammer.com/archiveItem?key={API_KEY}&item_id=123456

Returns:

{
    "status": "OK"
}

deleteSearch

deleteSearch deletes a saved search from your account.

Parameter	Type	Description
`key`	string	(required) Your API key.
`id`	integer	(required) The ID of the saved search to delete. (Use `getUserSearches` to get search IDs.)

Sample Call

https://api.bidslammer.com/deleteSearch?key={API_KEY}&id=12345

Returns:

{
    "status": "OK",
    "id": 12345
}

getAllBidders

getAllBidders retrieves the complete bid history for an eBay auction, showing all bidders and their bid amounts.

Parameter	Type	Description
`key`	string	(required) Your API key.
`item_no`	integer	(required) The eBay item number.

Sample Call

https://api.bidslammer.com/getAllBidders?key={API_KEY}&item_no=123456789012

Returns:

{
    "status": "OK",
    "bidders": [
        {
            "userID": "b***r",
            "maxBid": 52.00,
            "bidTime": "2024-07-01 10:59:28"
        },
        {
            "userID": "s***e",
            "maxBid": 45.00,
            "bidTime": "2024-06-30 14:22:15"
        }
    ]
}

getBidGroupItems

getBidGroupItems retrieves all of your Bid Groups and the snipes within each group.

Parameter	Type	Description
`key`	string	(required) Your API key.

Sample Call

https://api.bidslammer.com/getBidGroupItems?key={API_KEY}

Returns:

[
    {
        "group_id": 12345,
        "groupName": "Vintage Watches",
        "created_at": "2024-06-15 09:30:00",
        "updated_at": "2024-07-01 14:22:00",
        "wins_desired": 1,
        "wins_achieved": 0,
        "items": [
            {
                "id": 98765,
                "item_no": 123456789012,
                "title": "Vintage Omega Seamaster",
                "pictureURL": "https://i.ebayimg.com/images/g/xyz/s-l1600.jpg"
            },
            {
                "id": 98766,
                "item_no": 234567890123,
                "title": "Vintage Rolex Oyster",
                "pictureURL": "https://i.ebayimg.com/images/g/abc/s-l1600.jpg"
            }
        ]
    }
]

getGalleryImages

getGalleryImages retrieves thumbnail images from your completed snipes for display in a gallery view.

Parameter	Type	Description
`key`	string	(required) Your API key.

Sample Call

https://api.bidslammer.com/getGalleryImages?key={API_KEY}

Returns:

[
    {
        "item_no": 123456789012,
        "pictureURL": "https://i.ebayimg.com/images/g/xyz/s-l1600.jpg",
        "title": "Vintage Star Wars Figure"
    },
    {
        "item_no": 234567890123,
        "pictureURL": "https://i.ebayimg.com/images/g/abc/s-l1600.jpg",
        "title": "Antique Pocket Watch"
    }
]

getItemImages

getItemImages retrieves all image URLs for a specific eBay item.

Parameter	Type	Description
`key`	string	(required) Your API key.
`item_no`	integer	(required) The eBay item number.

Sample Call

https://api.bidslammer.com/getItemImages?key={API_KEY}&item_no=123456789012

Returns:

[
    "https://i.ebayimg.com/00/s/NDgwWDY0MA==/z/nicAAOSwi5xeMhKl/$_12.JPG",
    "https://i.ebayimg.com/00/s/NDgwWDY0MA==/z/wq0AAOSwUMpeMhK1/$_12.JPG",
    "https://i.ebayimg.com/00/s/NDgwWDY0MA==/z/bBQAAOSwPMpeMhK2/$_12.JPG"
]

getUserLogEntries

getUserLogEntries retrieves your Real Time Snipe Log entries, showing all recent actions taken on your snipes.

Parameter	Type	Description
`key`	string	(required) Your API key.
`limit`	integer	(optional) Maximum number of entries to return. Default: 100.

Sample Call

https://api.bidslammer.com/getUserLogEntries?key={API_KEY}&limit=50

Returns:

[
    {
        "timestamp": "2024-07-01 10:59:24",
        "item_no": 123456789012,
        "hostname": "snipe-server-1",
        "comment": "Snipe placed successfully at $52.00"
    },
    {
        "timestamp": "2024-07-01 10:59:20",
        "item_no": 123456789012,
        "hostname": "snipe-server-1",
        "comment": "Preparing snipe for item #123456789012"
    }
]

importBidList

importBidList imports your eBay Bid List (items you are currently bidding on) into your BidSlammer account. These items appear in your Watching tab.

Parameter	Type	Description
`key`	string	(required) Your API key.

Note: This operation may take up to a minute or more depending on the size of your bid list.

Sample Call

https://api.bidslammer.com/importBidList?key={API_KEY}

Returns:

{
    "bestOfferCount": 0,
    "biddingCount": 3,
    "totalWinningCost": "125.00",
    "wonCostUnit": "USD",
    "totalWonCost": "0.00",
    "winningCount": 1,
    "wonCount": 0,
    "wonDurationInDays": 60,
    "items": [
        {
            "item_no": 123456789012,
            "title": "Vintage Toy Car",
            "pictureURL": "https://i.ebayimg.com/images/g/xyz/s-l1600.jpg",
            "cost": "14.99",
            "cost_unit": "USD",
            "ends": "2024-07-14 23:57:00",
            "bids": 2,
            "sellerID": "vintage-seller-22"
        }
    ],
    "size": 3,
    "status": "OK",
    "errors": []
}

importWatchList

importWatchList imports your eBay Watch List into your BidSlammer account. These items appear in your Watching tab without a snipe bid set.

Parameter	Type	Description
`key`	string	(required) Your API key.

Note: This operation may take up to a minute or more depending on the size of your watch list.

Sample Call

https://api.bidslammer.com/importWatchList?key={API_KEY}

Returns:

{
    "bestOfferCount": 0,
    "biddingCount": 0,
    "totalWinningCost": "0.00",
    "wonCostUnit": "USD",
    "totalWonCost": "0.00",
    "winningCount": 0,
    "wonCount": 0,
    "wonDurationInDays": 60,
    "items": [
        {
            "item_no": 123456789012,
            "title": "Vintage Toy Car",
            "pictureURL": "https://i.ebayimg.com/images/g/xyz/s-l1600.jpg",
            "cost": "14.99",
            "cost_unit": "USD",
            "ends": "2024-07-14 23:57:00",
            "bids": 2,
            "sellerID": "vintage-seller-22"
        }
    ],
    "size": 5,
    "status": "OK",
    "errors": []
}

New User Questions

My Account

Site Operation

Bidding Analytics

Troubleshooting

Quick Links

API Documentation

Available Methods

Primary Functions

Secondary Functions

justTesting

Sample Call

Returns:

addBid

Sample Call

Returns:

deleteBid

Sample Call

addSearch

Sample Call

fetchItem

Sample Call

Returns:

checkSnipeStatus

Sample Call

Returns:

getUserItems

Sample Call

Returns:

getUserSearches

Sample Call

Returns:

getBidderDataset

Sample Call

Returns:

getBidHistoryDataset

Sample Call

Returns:

getSearchResults

Sample Call

getSuggestedCategories

Sample Call

Secondary Functions

archiveItem

Sample Call

Returns:

deleteSearch

Sample Call

Returns:

getAllBidders

Sample Call

Returns:

getBidGroupItems

Sample Call

Returns:

getGalleryImages

Sample Call

Returns:

getItemImages

Sample Call

Returns:

getUserLogEntries

Sample Call

Returns:

importBidList

Sample Call

Returns:

importWatchList

Sample Call

Returns: