> For the complete documentation index, see [llms.txt](https://docs.formsort.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.formsort.com/form-behavior-settings/variant-settings/group-ranking-api.md).
# Group ranking API
In the standard use of Formsort, steps can be placed into [groups](/creating-flows/building-a-new-flow/organizing-using-groups.md) for organizational purposes; the steps will then appear in the order of their parent groups. Groups and steps can be re-arranged by dragging and dropping, but once they are published they will always be seen by the responder in the fixed order.
Using the **Group ranking API,** it's possible to re-arrange groups dynamically. This allows for you to decide on-the-fly which content to show the responder, in which order.
One example use case would be a flow with many different offers that are shown to responders. Based on information gathered within a flow, some offers might be more likely to be relevant to the responder: the group ranking API allows for showing those first, and delaying (or hiding entirely) less-relevant groups.
## Setting up dynamic group ranking
To reliably refer to groups in the dynamic ranking, we first need to define unique group IDs. To do so, set the **Group ID** with a group selected on each group that you want to reorder.
The group ranking API is configured by adding a URL to the Variant settings.
Like most URLs within Formsort, the URL can be templated with answers that are present within the flow: the URL will be fetched any time one of the inputs is changed.
### Expected response
The group ranking API expects a JSON response that is an object with string keys corresponding to the group ID, and values corresponding to their rank, which will be used to sort the groups.
* Groups with a lower rank will appear before groups with a higher rank
* Groups that are defined within the flow but that are not present in the ranking, or do not have a group ID defined will be given a ranking of 0.5.
* Groups given a ranking of -1 will be hidden in the flow
* The sort is *stable* - if a ranking contains multiple groups each with the same rank, the groups will appear in the order that they were originally defined.
* Groups that have already been completed or entered by the responder will not be re-ranked.
For example, imagine a flow with four groups: Intro, About You, About Your Pet, and "Bonus Content". Let's look at the following ranking response
```
{
"intro": 0.1,
"about-you": 0.9,
"bonus-content": -1
}
```
This would result in a flow with three groups, in this order:
1. Intro (has a low rank of 0.1)
2. About your pet (it does not appear in the ranking, so it is given the default rank of 0.5)
3. About you (has a high rank of 0.9)
The Bonus content group would not appear in the result since it was given a rank of -1.
## Notes and suggestions
Be careful about conflicting sources of truth when it comes to determining which groups are enabled. If a group is disabled according to conditions and logic defined within the flow itself, it will always be hidden, even if the group appears in the ranking response.
Don't return orderings that would violate dependencies between groups, such as a group that uses an answer collected in a previous group. Such invalid configurations may lead to problems and should be avoided.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.formsort.com/form-behavior-settings/variant-settings/group-ranking-api.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.