AT AppointmentTrader
Sign In
Online Now  

/v1/bidpool/

Private responses during collection, with a signed-in decision comparison after selection.
GET

/v1/bidpool/get_hold_access

#
Explain the acting seller's hold access for a visible, active bid. Does not reserve or mutate the bid. Returns title, message, missingHoldPermissions, permissionGroups (permissionName, label, medals with id/name/description/icon/statusURL), canFillDirectly, directFillAvailability (available, selection_pending, seller_ineligible or unavailable), note and emptyMedalsMessage. Medal lists are live permission metadata, not a guarantee that verification, fill rate, inventory or capacity checks pass. A buyer-selected Premium direct hire may be filled with complete confirmation without granting hold or response-round access.

Parameters

NameTypeRequiredDefaultDescription
bidID int Yes — Customer bid ID.
Request example (cURL) 
curl --get \
  'https://ca.appointmenttrader.com/v1/bidpool/get_hold_access' \
  --data-urlencode 'key={{API_KEY}}' \
  --data-urlencode 'bidID={{bidID}}'

Returns

JSON
See the shared response schema and synthetic example.
Response fields
FieldTypeRequiredDescription
$bidpool_get_hold_access_Response Yes
$.oneOf[0] Yes
$.oneOf[0].allOf[0]object Yes
$.oneOf[0].allOf[0].RequestUserAliasstring Yes
$.oneOf[0].allOf[0].RequestPathstring | null Yes
$.oneOf[0].allOf[0].RequestStatus = "Succeeded" Yes
$.oneOf[0].allOf[0].ResponseCodeinteger Yes
$.oneOf[0].allOf[0].ResponseMessageAPIResponseMessage Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[0]string | number | boolean | null Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[1]array Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[1][]APIResponseMessage No
$.oneOf[0].allOf[0].ResponseMessage.oneOf[2]object Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[2].*APIResponseMessage No
$.oneOf[0].allOf[0].RequestImpersonatedByUserAliasstring No
$.oneOf[0].allOf[1]object Yes
$.oneOf[0].allOf[1].Payloadobject Yes
$.oneOf[0].allOf[1].Payload.bidIDinteger Yes
$.oneOf[0].allOf[1].Payload.titlestring Yes
$.oneOf[0].allOf[1].Payload.messagestring Yes
$.oneOf[0].allOf[1].Payload.missingHoldPermissionsarray Yes
$.oneOf[0].allOf[1].Payload.missingHoldPermissions[]string No
$.oneOf[0].allOf[1].Payload.permissionGroupsarray Yes
$.oneOf[0].allOf[1].Payload.permissionGroups[]object No
$.oneOf[0].allOf[1].Payload.permissionGroups[].permissionNamestring Yes
$.oneOf[0].allOf[1].Payload.permissionGroups[].labelstring Yes
$.oneOf[0].allOf[1].Payload.permissionGroups[].medalsarray Yes
$.oneOf[0].allOf[1].Payload.permissionGroups[].medals[]object No
$.oneOf[0].allOf[1].Payload.permissionGroups[].medals[].idinteger Yes
$.oneOf[0].allOf[1].Payload.permissionGroups[].medals[].namestring Yes
$.oneOf[0].allOf[1].Payload.permissionGroups[].medals[].descriptionstring Yes
$.oneOf[0].allOf[1].Payload.permissionGroups[].medals[].iconstring Yes
$.oneOf[0].allOf[1].Payload.permissionGroups[].medals[].statusURLstring Yes
$.oneOf[0].allOf[1].Payload.canFillDirectlyboolean Yes
$.oneOf[0].allOf[1].Payload.directFillAvailabilitystring ["available","selection_pending","seller_ineligible","unavailable"] Yes
$.oneOf[0].allOf[1].Payload.notestring Yes
$.oneOf[0].allOf[1].Payload.emptyMedalsMessagestring Yes
$.oneOf[0].allOf[1].Payload.actionsarray Yes
$.oneOf[0].allOf[1].Payload.actions[]string No
$.oneOf[0].allOf[1].Payload.buyerIdentityHiddenboolean NoTrue when the authenticated viewer cannot see the buyer during the current response race.
$.oneOf[0].allOf[1].Payload.buyerIdentityHiddenUntilinteger | null NoSaved current-round ClosesAt as Unix seconds; null when identity is visible. Reveal is authoritative only on a new response.
$.oneOf[1]object Yes
$.oneOf[1].RequestUserAliasstring Yes
$.oneOf[1].RequestPathstring | null Yes
$.oneOf[1].RequestStatus = "Failed" Yes
$.oneOf[1].ResponseCodeinteger Yes
$.oneOf[1].ResponseMessageAPIResponseMessage Yes
$.oneOf[1].ResponseMessage.oneOf[0]string | number | boolean | null Yes
$.oneOf[1].ResponseMessage.oneOf[1]array Yes
$.oneOf[1].ResponseMessage.oneOf[1][]APIResponseMessage No
$.oneOf[1].ResponseMessage.oneOf[2]object Yes
$.oneOf[1].ResponseMessage.oneOf[2].*APIResponseMessage No
$.oneOf[1].RequestImpersonatedByUserAliasstring No
Response example 
{
    "RequestStatus": "Succeeded",
    "ResponseCode": 100,
    "ResponseMessage": "Synthetic success example.",
    "RequestPath": "/v1/bidpool/get_hold_access",
    "RequestUserAlias": "example-user",
    "Payload": {
        "bidID": 0,
        "title": "synthetic-example",
        "message": "synthetic-example",
        "missingHoldPermissions": [],
        "permissionGroups": [],
        "canFillDirectly": false,
        "directFillAvailability": "available",
        "note": "synthetic-example",
        "emptyMedalsMessage": "synthetic-example",
        "actions": []
    }
}
Machine-readable endpoint documentation
GET

/v1/bidpool/get_mine

#
The acting seller's responses on active bids, including pending responses, reopened rounds needing reconfirmation and awarded rounds they responded to. postURL links to the bid's post when available. ownSelected is true/false after selection, null while no seller has been selected. Up to 100 rounds, active collecting/immediate rounds first, then awarded rounds; each group sorts newest ownRespondedAt first (original submission Unix seconds, then round ID descending). Edits and ranking do not reorder them within a group. Reopened rounds use the latest previous participation time until reconfirmed. label uses Custom Concierge Request instead of the location name when location access is restricted. title is the same safe location/request name without the bid number; missing locations use Custom Concierge Request. requestPreview is a plain-text preview of the canonical seller-visible request or readable bid-post wording, at most 160 characters, or empty when no request text is available. postURL also powers the See post action, carrying a return destination to Bid Round Participations. participants is empty before selection; afterwards it includes sellerAlias, sellerAvatar, sellerDisplayHTML (shared profile mention), selected and withdrawn, winner first then saved comparison order. Promises and ranking audits are not included in participants. fillBidURL opens the existing seller bid dialog only for the selected seller of a current awarded round; otherwise null.

Parameters

NameTypeRequiredDefaultDescription
limit int No 100 Maximum visible entries, 1-100, default 100. Smaller limits load only that prefix's previews and participants.
Request example (cURL) 
curl --get \
  'https://ca.appointmenttrader.com/v1/bidpool/get_mine' \
  --data-urlencode 'key={{API_KEY}}' \
  --data-urlencode 'limit={{limit}}'

Returns

JSON
See the shared response schema and synthetic example.
Response fields
FieldTypeRequiredDescription
$bidpool_get_mine_Response Yes
$.oneOf[0] Yes
$.oneOf[0].allOf[0]object Yes
$.oneOf[0].allOf[0].RequestUserAliasstring Yes
$.oneOf[0].allOf[0].RequestPathstring | null Yes
$.oneOf[0].allOf[0].RequestStatus = "Succeeded" Yes
$.oneOf[0].allOf[0].ResponseCodeinteger Yes
$.oneOf[0].allOf[0].ResponseMessageAPIResponseMessage Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[0]string | number | boolean | null Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[1]array Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[1][]APIResponseMessage No
$.oneOf[0].allOf[0].ResponseMessage.oneOf[2]object Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[2].*APIResponseMessage No
$.oneOf[0].allOf[0].RequestImpersonatedByUserAliasstring No
$.oneOf[0].allOf[1]object Yes
$.oneOf[0].allOf[1].Payloadarray Yes
$.oneOf[0].allOf[1].Payload[]object No
$.oneOf[0].allOf[1].Payload[].bidIDinteger Yes
$.oneOf[0].allOf[1].Payload[].closesAtinteger Yes
$.oneOf[0].allOf[1].Payload[].statestring Yes
$.oneOf[0].allOf[1].Payload[].labelstring Yes
$.oneOf[0].allOf[1].Payload[].titlestring Yes
$.oneOf[0].allOf[1].Payload[].requestPreviewstring Yes
$.oneOf[0].allOf[1].Payload[].ownRespondedAtinteger Yes
$.oneOf[0].allOf[1].Payload[].participantsarray Yes
$.oneOf[0].allOf[1].Payload[].participants[]object No
$.oneOf[0].allOf[1].Payload[].participants[].sellerAliasstring Yes
$.oneOf[0].allOf[1].Payload[].participants[].sellerAvatarstring Yes
$.oneOf[0].allOf[1].Payload[].participants[].sellerDisplayHTMLstring Yes
$.oneOf[0].allOf[1].Payload[].participants[].selectedboolean Yes
$.oneOf[0].allOf[1].Payload[].participants[].withdrawnboolean Yes
$.oneOf[0].allOf[1].Payload[].fillBidURL Yes
$.oneOf[0].allOf[1].Payload[].fillBidURL.anyOf[0]string Yes
$.oneOf[0].allOf[1].Payload[].fillBidURL.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload[].postURL Yes
$.oneOf[0].allOf[1].Payload[].postURL.anyOf[0]string Yes
$.oneOf[0].allOf[1].Payload[].postURL.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload[].ownSelected Yes
$.oneOf[0].allOf[1].Payload[].ownSelected.anyOf[0]boolean Yes
$.oneOf[0].allOf[1].Payload[].ownSelected.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload[].ownDeadline Yes
$.oneOf[0].allOf[1].Payload[].ownDeadline.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload[].ownDeadline.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload[].needsConfirmationboolean Yes
$.oneOf[0].allOf[1].Payload[].buyerIdentityHiddenboolean NoTrue when the authenticated viewer cannot see the buyer during the current response race.
$.oneOf[0].allOf[1].Payload[].buyerIdentityHiddenUntilinteger | null NoSaved current-round ClosesAt as Unix seconds; null when identity is visible. Reveal is authoritative only on a new response.
$.oneOf[1]object Yes
$.oneOf[1].RequestUserAliasstring Yes
$.oneOf[1].RequestPathstring | null Yes
$.oneOf[1].RequestStatus = "Failed" Yes
$.oneOf[1].ResponseCodeinteger Yes
$.oneOf[1].ResponseMessageAPIResponseMessage Yes
$.oneOf[1].ResponseMessage.oneOf[0]string | number | boolean | null Yes
$.oneOf[1].ResponseMessage.oneOf[1]array Yes
$.oneOf[1].ResponseMessage.oneOf[1][]APIResponseMessage No
$.oneOf[1].ResponseMessage.oneOf[2]object Yes
$.oneOf[1].ResponseMessage.oneOf[2].*APIResponseMessage No
$.oneOf[1].RequestImpersonatedByUserAliasstring No
Response example 
{
    "RequestStatus": "Succeeded",
    "ResponseCode": 100,
    "ResponseMessage": "Synthetic success example.",
    "RequestPath": "/v1/bidpool/get_mine",
    "RequestUserAlias": "example-user",
    "Payload": []
}
Machine-readable endpoint documentation
GET

/v1/bidpool/get_selection_explanation

#
Explain the most recent response-pool selection to any signed-in user, including buyers and nonparticipants. Returns localized summary/rules and, only after selection, candidates with public sellerAlias, selected/withdrawn status, sellerDisplayHTML (the shared profile chip with avatar, badges and profile link; empty for unavailable sellers), saved rank, deadlineAt (Unix seconds), durationMinutes, assignmentCount, assignmentAmountCents (gross USD cents), scoreSeconds, promisedSeconds and fairnessSeconds. Totals cover the preceding 24 hours at ranking/immediate pickup. scoringVersion is 1 for legacy rankings, 2 for count-based repeat-customer rankings, 3 for linear dollar rankings, 4 for square-root workload with fixed repeat credit, or null for unranked responses. Version 2 adds the saved repeatCustomerRateBasisPoints (100 basis points = 1%) and repeatCustomerBonusSeconds. scoreSeconds = promisedSeconds + fairnessSeconds - repeatCustomerBonusSeconds; the promised deadline is unchanged. In versions 2 and 3 the bonus discounts time by half the existing cached repeat rate. A missing rate earns zero bonus in every version. Legacy/unranked repeat fields are null; historical decisions never use today's cached user metrics. Version 3 fairnessSeconds is saved gross USD cents * 60 / 1000, floored to whole seconds, without a cap. Version 4 fairnessSeconds = floor(60 * 12 * sqrt(saved gross USD cents / 100)); repeatCustomerBonusSeconds = floor(saved rate basis points * 10 * 60 / 100). Version 4 gives 10 minutes per percentage point (17% earns 170 minutes), independent of promised time or workload. Negative scoreSeconds are valid and sort first. Version 4 retains dollar tie-breaks and saves both coefficients with the decision; prior versions are never recalculated. New version-4 rankings measure promisedSeconds from the accepted opening-adjusted fillStartsAt, excluding the initial opening wait. Later closures do not pause elapsed time. candidates.fillStartsAt (Unix seconds) and openingWaitSeconds expose this saved baseline; both are null for historical rankings that counted from round close. Preset responses submitted before baseline capture derive their start from the saved deadline and duration; older custom responses use the shared opening-hours policy at first ranking. Version 3 counts are informational; ties use deadline, assigned dollars, then saved randomness. Versions 1 and 2 retain their count-based rules. New selection counts, amounts and audit rows include only ranked awards with at least two non-withdrawn ranked contestants. Single-contestant awards, normal/immediate pickups, direct fills and direct hires are excluded, including pickup after an exhausted ranking. Existing saved decisions retain their original inputs. Missing qualifying amounts prevent ranking until repaired. candidates.assignments lists the same saved inputs used by allocation, with bidReference/bidURL, assignedAt, amountCents and directHire. assignmentAuditStatus is saved, reconstructed (older history matching the saved count), or unavailable. historicalDirectHires flags an older decision that counted direct hires; its original score is never rewritten. Null dollar totals mean historical amounts were not saved, never zero. No random tie-break tokens are exposed. Older, direct-hire and paid-auction bids without a pool record are explicitly identified as unrecorded.

Parameters

NameTypeRequiredDefaultDescription
bidID int Yes — Customer bid ID.
Request example (cURL) 
curl --get \
  'https://ca.appointmenttrader.com/v1/bidpool/get_selection_explanation' \
  --data-urlencode 'key={{API_KEY}}' \
  --data-urlencode 'bidID={{bidID}}'

Returns

JSON
See the shared response schema and synthetic example.
Response fields
FieldTypeRequiredDescription
$bidpool_get_selection_explanation_Response Yes
$.oneOf[0] Yes
$.oneOf[0].allOf[0]object Yes
$.oneOf[0].allOf[0].RequestUserAliasstring Yes
$.oneOf[0].allOf[0].RequestPathstring | null Yes
$.oneOf[0].allOf[0].RequestStatus = "Succeeded" Yes
$.oneOf[0].allOf[0].ResponseCodeinteger Yes
$.oneOf[0].allOf[0].ResponseMessageAPIResponseMessage Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[0]string | number | boolean | null Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[1]array Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[1][]APIResponseMessage No
$.oneOf[0].allOf[0].ResponseMessage.oneOf[2]object Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[2].*APIResponseMessage No
$.oneOf[0].allOf[0].RequestImpersonatedByUserAliasstring No
$.oneOf[0].allOf[1]object Yes
$.oneOf[0].allOf[1].Payloadobject Yes
$.oneOf[0].allOf[1].Payload.titlestring Yes
$.oneOf[0].allOf[1].Payload.reasonstring ["public_change_proposal","balanced","deadline","recent","random","eligible","immediate_selected","collecting","immediate","closed","no_record"] Yes
$.oneOf[0].allOf[1].Payload.summarystring Yes
$.oneOf[0].allOf[1].Payload.contextstring Yes
$.oneOf[0].allOf[1].Payload.selectedAt Yes
$.oneOf[0].allOf[1].Payload.selectedAt.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload.selectedAt.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.candidatesarray Yes
$.oneOf[0].allOf[1].Payload.candidates[]object No
$.oneOf[0].allOf[1].Payload.candidates[].sellerAliasstring Yes
$.oneOf[0].allOf[1].Payload.candidates[].sellerDisplayHTMLstring Yes
$.oneOf[0].allOf[1].Payload.candidates[].selectedboolean Yes
$.oneOf[0].allOf[1].Payload.candidates[].withdrawnboolean Yes
$.oneOf[0].allOf[1].Payload.candidates[].rank Yes
$.oneOf[0].allOf[1].Payload.candidates[].rank.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload.candidates[].rank.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.candidates[].deadlineAtinteger Yes
$.oneOf[0].allOf[1].Payload.candidates[].durationMinutesinteger Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignmentCount Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignmentCount.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignmentCount.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignmentAmountCents Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignmentAmountCents.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignmentAmountCents.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.candidates[].scoreSeconds Yes
$.oneOf[0].allOf[1].Payload.candidates[].scoreSeconds.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload.candidates[].scoreSeconds.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.candidates[].promisedSeconds Yes
$.oneOf[0].allOf[1].Payload.candidates[].promisedSeconds.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload.candidates[].promisedSeconds.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.candidates[].fairnessSeconds Yes
$.oneOf[0].allOf[1].Payload.candidates[].fairnessSeconds.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload.candidates[].fairnessSeconds.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.candidates[].scoringVersion Yes
$.oneOf[0].allOf[1].Payload.candidates[].scoringVersion.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload.candidates[].scoringVersion.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.candidates[].repeatCustomerRateBasisPoints Yes
$.oneOf[0].allOf[1].Payload.candidates[].repeatCustomerRateBasisPoints.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload.candidates[].repeatCustomerRateBasisPoints.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.candidates[].repeatCustomerBonusSeconds Yes
$.oneOf[0].allOf[1].Payload.candidates[].repeatCustomerBonusSeconds.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload.candidates[].repeatCustomerBonusSeconds.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.candidates[].fillStartsAt Yes
$.oneOf[0].allOf[1].Payload.candidates[].fillStartsAt.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload.candidates[].fillStartsAt.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.candidates[].openingWaitSeconds Yes
$.oneOf[0].allOf[1].Payload.candidates[].openingWaitSeconds.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload.candidates[].openingWaitSeconds.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignmentsarray Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignments[]object No
$.oneOf[0].allOf[1].Payload.candidates[].assignments[].bidReference Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignments[].bidReference.anyOf[0]string Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignments[].bidReference.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignments[].bidURL Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignments[].bidURL.anyOf[0]string Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignments[].bidURL.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignments[].assignedAtinteger Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignments[].amountCents Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignments[].amountCents.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignments[].amountCents.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignments[].directHireboolean Yes
$.oneOf[0].allOf[1].Payload.candidates[].assignmentAuditStatusstring ["saved","reconstructed","unavailable"] Yes
$.oneOf[0].allOf[1].Payload.candidates[].historicalDirectHiresboolean Yes
$.oneOf[0].allOf[1].Payload.dataNotestring Yes
$.oneOf[0].allOf[1].Payload.rulesarray Yes
$.oneOf[0].allOf[1].Payload.rules[]string No
$.oneOf[0].allOf[1].Payload.privacystring Yes
$.oneOf[1]object Yes
$.oneOf[1].RequestUserAliasstring Yes
$.oneOf[1].RequestPathstring | null Yes
$.oneOf[1].RequestStatus = "Failed" Yes
$.oneOf[1].ResponseCodeinteger Yes
$.oneOf[1].ResponseMessageAPIResponseMessage Yes
$.oneOf[1].ResponseMessage.oneOf[0]string | number | boolean | null Yes
$.oneOf[1].ResponseMessage.oneOf[1]array Yes
$.oneOf[1].ResponseMessage.oneOf[1][]APIResponseMessage No
$.oneOf[1].ResponseMessage.oneOf[2]object Yes
$.oneOf[1].ResponseMessage.oneOf[2].*APIResponseMessage No
$.oneOf[1].RequestImpersonatedByUserAliasstring No
Response example 
{
    "RequestStatus": "Succeeded",
    "ResponseCode": 100,
    "ResponseMessage": "Synthetic success example.",
    "RequestPath": "/v1/bidpool/get_selection_explanation",
    "RequestUserAlias": "example-user",
    "Payload": {
        "title": "synthetic-example",
        "reason": "public_change_proposal",
        "summary": "synthetic-example",
        "context": "synthetic-example",
        "selectedAt": 0,
        "candidates": [],
        "dataNote": "synthetic-example",
        "rules": [],
        "privacy": "synthetic-example"
    }
}
Machine-readable endpoint documentation
GET

/v1/bidpool/get_state

#
Response window, opening-hours-adjusted fillOptions with exact deadlines, timingBaseAt, timingVersion, openingHours status/timezone, and only the acting seller's response. Times are Unix seconds. scoringVersion describes the currently built ranking policy (1 through 4) for new selections; it is not a recomputation of a saved decision. All eligible sellers share the same bid-relative window: maximumDeadline is cutoffAt, independent of their legacy maximum hold allowance. With the built dollar-workload capability, fixed choices are 1, 2, 4, 8, 12, 24, 48, 72 and 96 elapsed hours from fillStartsAt, filtered to cutoffAt. fillOptions[].deadlineAt includes any opening-time wait. customMinimumDeadline is the first whole minute strictly after the longest offered deadline, or null when custom is unavailable. Custom deadlines must be whole minutes from customMinimumDeadline through maximumDeadline. Positive durations must match an offered choice. Urgent windows retain the offered instant-fill option. Before capability activation, customMinimumDeadline is absent and the previous percentage-based choices and custom rules remain available. Existing commitments remain valid. A previous response is never automatic participation; edits and reconfirmations must obey current choices. When canRespond is false, message explains why. After closesAt, refresh this read-only state until selection finishes; an empty round becomes immediate pickup, requiring a fresh preview and confirmation. A recorded missed fill deadline prevents entering later selection windows for the same bid. Immediate pickup remains available subject to normal eligibility, including when existing entrants become ineligible at selection.

Parameters

NameTypeRequiredDefaultDescription
bidID int Yes — Customer bid ID.
Request example (cURL) 
curl --get \
  'https://ca.appointmenttrader.com/v1/bidpool/get_state' \
  --data-urlencode 'key={{API_KEY}}' \
  --data-urlencode 'bidID={{bidID}}'

Returns

JSON
See the shared response schema and synthetic example.
Response fields
FieldTypeRequiredDescription
$bidpool_get_state_Response Yes
$.oneOf[0] Yes
$.oneOf[0].allOf[0]object Yes
$.oneOf[0].allOf[0].RequestUserAliasstring Yes
$.oneOf[0].allOf[0].RequestPathstring | null Yes
$.oneOf[0].allOf[0].RequestStatus = "Succeeded" Yes
$.oneOf[0].allOf[0].ResponseCodeinteger Yes
$.oneOf[0].allOf[0].ResponseMessageAPIResponseMessage Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[0]string | number | boolean | null Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[1]array Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[1][]APIResponseMessage No
$.oneOf[0].allOf[0].ResponseMessage.oneOf[2]object Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[2].*APIResponseMessage No
$.oneOf[0].allOf[0].RequestImpersonatedByUserAliasstring No
$.oneOf[0].allOf[1]object Yes
$.oneOf[0].allOf[1].PayloadBidPoolState Yes
$.oneOf[0].allOf[1].Payload.oneOf[0]object Yes
$.oneOf[0].allOf[1].Payload.oneOf[0].managed = false Yes
$.oneOf[0].allOf[1].Payload.oneOf[0].auctionURL Yes
$.oneOf[0].allOf[1].Payload.oneOf[0].auctionURL.anyOf[0]string Yes
$.oneOf[0].allOf[1].Payload.oneOf[0].auctionURL.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.oneOf[1]object Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].managed = true Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].bidIDinteger Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].roundIDinteger Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].statestring Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].serverTimeinteger Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].closesAtinteger Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].cutoffAtinteger Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].minimumDeadline Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].minimumDeadline.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].minimumDeadline.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].maximumDeadlineinteger Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].durationsarray Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].durations[]integer No
$.oneOf[0].allOf[1].Payload.oneOf[1].scoringVersioninteger [1,2,3,4] Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].timingBaseAtinteger Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].fillStartsAt Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].fillStartsAt.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].fillStartsAt.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].timingVersionstring Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].fillOptionsarray Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].fillOptions[]object No
$.oneOf[0].allOf[1].Payload.oneOf[1].fillOptions[].kindstring ["instant","duration"] Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].fillOptions[].durationMinutesinteger Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].fillOptions[].deadlineAtinteger Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].openingHoursobject Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].openingHours.statusstring ["unavailable","open","shifted","no_window"] Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].openingHours.timezonestring Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].instantFillboolean Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].ownResponse Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].ownResponse.anyOf[0]object Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].ownResponse.anyOf[0].DurationMinutesinteger | string Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].ownResponse.anyOf[0].DeadlineAtinteger | string Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].ownResponse.anyOf[0].Statestring Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].ownResponse.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].previousResponse Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].previousResponse.anyOf[0]object Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].previousResponse.anyOf[0].durationMinutesinteger Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].previousResponse.anyOf[0].deadlineAtinteger Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].previousResponse.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].canRespondboolean Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].messagestring Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].isWinnerboolean Yes
$.oneOf[0].allOf[1].Payload.oneOf[1].customMinimumDeadline No
$.oneOf[0].allOf[1].Payload.oneOf[1].customMinimumDeadline.anyOf[0]integer No
$.oneOf[0].allOf[1].Payload.oneOf[1].customMinimumDeadline.anyOf[1]null No
$.oneOf[0].allOf[1].Payload.oneOf[1].buyerIdentityHiddenboolean NoTrue when the authenticated viewer cannot see the buyer during the current response race.
$.oneOf[0].allOf[1].Payload.oneOf[1].buyerIdentityHiddenUntilinteger | null NoSaved current-round ClosesAt as Unix seconds; null when identity is visible. Reveal is authoritative only on a new response.
$.oneOf[1]object Yes
$.oneOf[1].RequestUserAliasstring Yes
$.oneOf[1].RequestPathstring | null Yes
$.oneOf[1].RequestStatus = "Failed" Yes
$.oneOf[1].ResponseCodeinteger Yes
$.oneOf[1].ResponseMessageAPIResponseMessage Yes
$.oneOf[1].ResponseMessage.oneOf[0]string | number | boolean | null Yes
$.oneOf[1].ResponseMessage.oneOf[1]array Yes
$.oneOf[1].ResponseMessage.oneOf[1][]APIResponseMessage No
$.oneOf[1].ResponseMessage.oneOf[2]object Yes
$.oneOf[1].ResponseMessage.oneOf[2].*APIResponseMessage No
$.oneOf[1].RequestImpersonatedByUserAliasstring No
Response example 
{
    "RequestStatus": "Succeeded",
    "ResponseCode": 100,
    "ResponseMessage": "Synthetic success example.",
    "RequestPath": "/v1/bidpool/get_state",
    "RequestUserAlias": "example-user",
    "Payload": {
        "managed": false,
        "auctionURL": "synthetic-example"
    }
}
Machine-readable endpoint documentation
POST

/v1/bidpool/set_response

#
Submit or edit a private response, or immediately pick up when the pool is in immediate mode. Use the preview from get_state. Durations start at round close (or preview time for immediate pickup), shifted to the next venue opening if closed. Custom deadlines are absolute. A 409 requires a refreshed preview and explicit reconfirmation. The server saves the accepted fill start alongside the response so later opening-hours edits cannot change its scoring duration. Actual completion deadlines are unchanged. Responses and assignment use the bid cutoff, not the seller's legacy hold duration limit. Seller eligibility and simultaneous-hold capacity still apply. Buyers can cancel while an unfilled promise is more than 48 hours away. Sellers who previously missed a fill deadline for this bid cannot enter collecting rounds. This restriction lifts in immediate mode; all other pickup checks still apply and eligibility is rechecked at assignment.

Parameters

NameTypeRequiredDefaultDescription
bidID int Yes — Customer bid ID.
roundID int Yes — Current round from /v1/bidpool/get_state. Stale rounds are rejected.
durationMinutes int Yes — Positive duration from get_state; zero selects customDeadline; -1 selects the offered instant-fill deadline.
customDeadline int No 0 Absolute Unix seconds for a custom completion time, otherwise zero. With customMinimumDeadline present, must be a whole minute in that range; null minimum disallows custom.
isWritingRequest bool No false Must be true to save a response or take an immediate hold.
timingBaseAt int No 0 Preview timingBaseAt from get_state. Immediate previews expire after five minutes.
timingVersion string No "" Preview timingVersion from get_state.
expectedDeadline int No 0 Exact fill-by timestamp displayed and confirmed by the seller.
Request example (cURL) 
curl --request POST \
  'https://ca.appointmenttrader.com/v1/bidpool/set_response' \
  --data-urlencode 'key={{API_KEY}}' \
  --data-urlencode 'bidID={{bidID}}' \
  --data-urlencode 'roundID={{roundID}}' \
  --data-urlencode 'durationMinutes={{durationMinutes}}' \
  --data-urlencode 'customDeadline={{customDeadline}}' \
  --data-urlencode 'isWritingRequest={{isWritingRequest}}' \
  --data-urlencode 'timingBaseAt={{timingBaseAt}}' \
  --data-urlencode 'timingVersion={{timingVersion}}' \
  --data-urlencode 'expectedDeadline={{expectedDeadline}}'

Returns

JSON
See the shared response schema and synthetic example.
Response fields
FieldTypeRequiredDescription
$bidpool_set_response_Response Yes
$.oneOf[0] Yes
$.oneOf[0].allOf[0]object Yes
$.oneOf[0].allOf[0].RequestUserAliasstring Yes
$.oneOf[0].allOf[0].RequestPathstring | null Yes
$.oneOf[0].allOf[0].RequestStatus = "Succeeded" Yes
$.oneOf[0].allOf[0].ResponseCodeinteger Yes
$.oneOf[0].allOf[0].ResponseMessageAPIResponseMessage Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[0]string | number | boolean | null Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[1]array Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[1][]APIResponseMessage No
$.oneOf[0].allOf[0].ResponseMessage.oneOf[2]object Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[2].*APIResponseMessage No
$.oneOf[0].allOf[0].RequestImpersonatedByUserAliasstring No
$.oneOf[0].allOf[1]object Yes
$.oneOf[0].allOf[1].Payloadobject Yes
$.oneOf[0].allOf[1].Payload.success = true Yes
$.oneOf[0].allOf[1].Payload.assignedboolean Yes
$.oneOf[0].allOf[1].Payload.stateBidPoolState Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[0]object Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[0].managed = false Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[0].auctionURL Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[0].auctionURL.anyOf[0]string Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[0].auctionURL.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1]object Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].managed = true Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].bidIDinteger Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].roundIDinteger Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].statestring Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].serverTimeinteger Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].closesAtinteger Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].cutoffAtinteger Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].minimumDeadline Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].minimumDeadline.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].minimumDeadline.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].maximumDeadlineinteger Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].durationsarray Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].durations[]integer No
$.oneOf[0].allOf[1].Payload.state.oneOf[1].scoringVersioninteger [1,2,3,4] Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].timingBaseAtinteger Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].fillStartsAt Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].fillStartsAt.anyOf[0]integer Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].fillStartsAt.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].timingVersionstring Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].fillOptionsarray Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].fillOptions[]object No
$.oneOf[0].allOf[1].Payload.state.oneOf[1].fillOptions[].kindstring ["instant","duration"] Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].fillOptions[].durationMinutesinteger Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].fillOptions[].deadlineAtinteger Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].openingHoursobject Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].openingHours.statusstring ["unavailable","open","shifted","no_window"] Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].openingHours.timezonestring Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].instantFillboolean Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].ownResponse Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].ownResponse.anyOf[0]object Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].ownResponse.anyOf[0].DurationMinutesinteger | string Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].ownResponse.anyOf[0].DeadlineAtinteger | string Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].ownResponse.anyOf[0].Statestring Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].ownResponse.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].previousResponse Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].previousResponse.anyOf[0]object Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].previousResponse.anyOf[0].durationMinutesinteger Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].previousResponse.anyOf[0].deadlineAtinteger Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].previousResponse.anyOf[1]null Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].canRespondboolean Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].messagestring Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].isWinnerboolean Yes
$.oneOf[0].allOf[1].Payload.state.oneOf[1].customMinimumDeadline No
$.oneOf[0].allOf[1].Payload.state.oneOf[1].customMinimumDeadline.anyOf[0]integer No
$.oneOf[0].allOf[1].Payload.state.oneOf[1].customMinimumDeadline.anyOf[1]null No
$.oneOf[0].allOf[1].Payload.state.oneOf[1].buyerIdentityHiddenboolean NoTrue when the authenticated viewer cannot see the buyer during the current response race.
$.oneOf[0].allOf[1].Payload.state.oneOf[1].buyerIdentityHiddenUntilinteger | null NoSaved current-round ClosesAt as Unix seconds; null when identity is visible. Reveal is authoritative only on a new response.
$.oneOf[1]object Yes
$.oneOf[1].RequestUserAliasstring Yes
$.oneOf[1].RequestPathstring | null Yes
$.oneOf[1].RequestStatus = "Failed" Yes
$.oneOf[1].ResponseCodeinteger Yes
$.oneOf[1].ResponseMessageAPIResponseMessage Yes
$.oneOf[1].ResponseMessage.oneOf[0]string | number | boolean | null Yes
$.oneOf[1].ResponseMessage.oneOf[1]array Yes
$.oneOf[1].ResponseMessage.oneOf[1][]APIResponseMessage No
$.oneOf[1].ResponseMessage.oneOf[2]object Yes
$.oneOf[1].ResponseMessage.oneOf[2].*APIResponseMessage No
$.oneOf[1].RequestImpersonatedByUserAliasstring No
Response example 
{
    "RequestStatus": "Succeeded",
    "ResponseCode": 100,
    "ResponseMessage": "Synthetic success example.",
    "RequestPath": "/v1/bidpool/set_response",
    "RequestUserAlias": "example-user",
    "Payload": {
        "success": true,
        "assigned": false,
        "state": {
            "managed": false,
            "auctionURL": "synthetic-example"
        }
    }
}
Machine-readable endpoint documentation
POST

/v1/bidpool/set_withdraw

#
Withdraw only the acting seller's response before the round closes. Does not release a fulfillment hold.

Parameters

NameTypeRequiredDefaultDescription
bidID int Yes — Customer bid ID.
roundID int Yes — Current response round.
isWritingRequest bool No false Must be true to withdraw.
Request example (cURL) 
curl --request POST \
  'https://ca.appointmenttrader.com/v1/bidpool/set_withdraw' \
  --data-urlencode 'key={{API_KEY}}' \
  --data-urlencode 'bidID={{bidID}}' \
  --data-urlencode 'roundID={{roundID}}' \
  --data-urlencode 'isWritingRequest={{isWritingRequest}}'

Returns

JSON
See the shared response schema and synthetic example.
Response fields
FieldTypeRequiredDescription
$bidpool_set_withdraw_Response Yes
$.oneOf[0] Yes
$.oneOf[0].allOf[0]object Yes
$.oneOf[0].allOf[0].RequestUserAliasstring Yes
$.oneOf[0].allOf[0].RequestPathstring | null Yes
$.oneOf[0].allOf[0].RequestStatus = "Succeeded" Yes
$.oneOf[0].allOf[0].ResponseCodeinteger Yes
$.oneOf[0].allOf[0].ResponseMessageAPIResponseMessage Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[0]string | number | boolean | null Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[1]array Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[1][]APIResponseMessage No
$.oneOf[0].allOf[0].ResponseMessage.oneOf[2]object Yes
$.oneOf[0].allOf[0].ResponseMessage.oneOf[2].*APIResponseMessage No
$.oneOf[0].allOf[0].RequestImpersonatedByUserAliasstring No
$.oneOf[0].allOf[1]object Yes
$.oneOf[0].allOf[1].Payloadobject Yes
$.oneOf[0].allOf[1].Payload.success = true Yes
$.oneOf[1]object Yes
$.oneOf[1].RequestUserAliasstring Yes
$.oneOf[1].RequestPathstring | null Yes
$.oneOf[1].RequestStatus = "Failed" Yes
$.oneOf[1].ResponseCodeinteger Yes
$.oneOf[1].ResponseMessageAPIResponseMessage Yes
$.oneOf[1].ResponseMessage.oneOf[0]string | number | boolean | null Yes
$.oneOf[1].ResponseMessage.oneOf[1]array Yes
$.oneOf[1].ResponseMessage.oneOf[1][]APIResponseMessage No
$.oneOf[1].ResponseMessage.oneOf[2]object Yes
$.oneOf[1].ResponseMessage.oneOf[2].*APIResponseMessage No
$.oneOf[1].RequestImpersonatedByUserAliasstring No
Response example 
{
    "RequestStatus": "Succeeded",
    "ResponseCode": 100,
    "ResponseMessage": "Synthetic success example.",
    "RequestPath": "/v1/bidpool/set_withdraw",
    "RequestUserAlias": "example-user",
    "Payload": {
        "success": true
    }
}
Machine-readable endpoint documentation