Genesys Cloud - Developer Community!

 View Only

Sign Up

Back to discussions
Expand all | Collapse all

New shift trading unmatched search API only allows one weekDate despite array schema and 5/min rate limit

  • 1.  New shift trading unmatched search API only allows one weekDate despite array schema and 5/min rate limit

    Posted yesterday

    Hi Genesys team,

    We are migrating our WFM Buddy mobile app from the deprecated shift trade APIs to the new shift trading job APIs.

    For showing shift trade availability in the schedule, we currently need:

    POST /api/v2/workforcemanagement/businessunits/{businessUnitId}/shifttrading/unmatched/search/jobs?forceAsync=true&forceDownloadService=true

    The request body has a `weekDates` property, which is an array according to Swagger:

    {
      "managementUnitIds": ["..."],
      "weekDates": ["2026-06-22"],
      "receivingSchedule": {
        "id": "..."
      },
      "receivingShiftIds": ["..."]
    }

    However, when sending more than one weekDate, the job fails with:

    "List size of 'weekDates' cannot be greater than 1"

    So my first question is: why is `weekDates` modeled as an array if the API only accepts one item? Is this a temporary limitation, a documentation/schema issue, or intended behavior?

    This limitation creates a practical issue for us. The endpoint appears to be limited by:

    shift.trading.rate.per.user.per.minute = 5

    Because only one week can be queried per request, we can only search a maximum of 5 weeks per minute for available unmatched trades. Our mobile app can show many more future weeks in the agent schedule.

    Our use case:
    In WFM Buddy, we show an icon on empty schedule days when there are available drops or community trades the agent can accept. We did this with the old APIs as well. With the new API, `unmatched/search/jobs` seems to be the only endpoint that tells us which unmatched trades are actually available for the current receiving user, including one-sided drops and match data.

    We also tested:

    POST /api/v2/workforcemanagement/shifttrading/trades/mine/query/jobs

    This endpoint does accept multiple weekDates, but it returns the agent's related trade records. It does not appear to return the same availability/match data as `unmatched/search/jobs`, such as `receivingShiftMatches` or `preview`, and it did not return an open one-sided drop that `unmatched/search/jobs` did return.

    So it does not seem to be a replacement for discovering available trades for empty schedule days.

    Because of the one-week limit and the 5-per-minute rate limit, we now have to consider workarounds such as:
    - caching available trade data
    - only querying when the user scrolls to a specific week
    - reducing the visible trade availability indicators in the schedule
    - delaying queries to avoid blocking actual trade actions like create/match

    Could you clarify the intended usage pattern for this scenario?

    Specifically:
    1. Is `unmatched/search/jobs` expected to support multiple `weekDates` in the future?
    2. Is the one-week validation intentional despite the Swagger array schema?
    3. Is the 5-per-minute rate limit shared with create/match/update shift trading job APIs?
    4. Is there another recommended endpoint for querying available unmatched trades for the current user across multiple weeks?
    5. What is the recommended approach for mobile schedule views that need to show trade availability indicators across more than 5 weeks?

    Thanks.


    #PlatformAPI
    #PlatformSDK

    ------------------------------
    Peter Vledder
    www.wfmbuddy.com
    ------------------------------


  • 2.  RE: New shift trading unmatched search API only allows one weekDate despite array schema and 5/min rate limit

    Posted 3 hours ago

    Hi @Peter Vledder,

    Thanks for the detailed analysis - this does look like a mismatch between the API contract and actual behavior.

    The fact that weekDates is defined as an array but restricted to a single value suggests either:

    • a forward-looking schema (multi-week support not yet implemented), or
    • a documentation inconsistency

    Right now, it behaves as a single-week endpoint, so your conclusion is accurate.

    On the rate limit, your concern is valid. With 1 week per call and 5 calls/minute, the API effectively caps discovery at 5 weeks per minute per user. In practice, this limit is typically shared across shift trading job APIs, so excessive querying could indeed impact create/match operations.

    Regarding alternatives, your findings also align with expected behavior:

    • /trades/mine/query/jobs is focused on the user's trades
    • it does not expose full availability or unmatched opportunities (e.g. drops), so it's not a replacement for discovery

    Given the current design, the API seems optimized for on-demand, per-week queries, not bulk availability scanning.

    Suggested approach

    What you proposed makes sense and is likely the intended pattern:

    • lazy-load per visible week
    • cache results per week/user
    • prefetch only nearby weeks (with throttling)
    • prioritize user actions over background queries

    Questions worth clarifying with Genesys

    • Will multi-week weekDates be supported?
    • Is the array schema intentional or incorrect?
    • Is the 5/min limit shared across all job endpoints?
    • Is there a recommended way to query availability across multiple weeks?

    Your use case (showing availability indicators in a mobile schedule) is very reasonable, so it would be good to hear if there's a more efficient pattern planned.



    ------------------------------
    Cesar Padilla
    INDRA COLOMBIA
    ------------------------------



Related Content