Overview

Some researchers may choose to group suppliers together to reduce the number of individual suppliers that must be managed together. Grouped suppliers will appear as a single supplier in the PureSpectrum Survey UI, reducing the number of suppliers to manage throughout field.

Use

To group individual suppliers together, you can use the API endpoint in Updating the list of suppliers for a Survey.

To ungroup suppliers, you can use the same API endpoint.

When grouping suppliers together, you must provide a name for this group. The supplier group is unique to the survey, and will not be accessible in different surveys.

Grouped suppliers will appear as a single supplier in the PureSpectrum UI, allowing you to manage the supplier allocation, and quotas by supplier for this group.

Any supplier in the group can fulfill up to 100% of the group’s allocation.

Important Considerations

This endpoint may only be used after a draft survey has been created
By default, all valid non-blocked suppliers in a locale are added to the survey upon creation. To update/remove suppliers, either omit their supplier ID from this endpoint, or set their “completes_required” to 0.
Suppliers can not be removed from a survey, though their allocations can be set to 0.
Suppliers that are grouped together will perceive no difference in their experience, though they will share an allocation with the other suppliers in their group.

Adding suppliers that are not valid in your account or locale will result in a failed request. The API will return an HTTP status code 400 in these cases.

“group_ref” can be set in the request. If a “group_ref” is not passed in, we will create one for you and return in the response.

Request

PUT $apihost/$basepath/surveys/:surveyId/suppliers

($apihost is the environment against which you are testing, and $basepath is the base path with the api version. All Buy API calls will require access-token parameter in the header)

Request:

PUT $apihost/$basepath/surveys/:surveyId/suppliers

[
	{
	  "cpi": 33.42,
	  "completes_goal" : 25,
	  "group_name": "Supplier Group 1",
	  "suppliers": [1, 2]
	},
	{
	  "cpi": 12,
	  "completes_goal" : 25,
	  "suppliers": [3]
	}
]

Result

Response Code

200

Response Body

[
    {
        "group_ref": 'sg1',
        "group_name": 'Supplier Group 1',
        "completes_goal": 25,
        "remaining": 100,
        "fielded": 0,
        "cpi": 33.42,
        "last_start_date": "",
        "intent": {
            "intent_value": null,
            "intent_not_set": [
                1,
                2
            ],
            "intent_denied": [],
            "intent_accepted": []
        },
        "suppliers": [
            {
                "id": 1,
                "name": "Supplier 1"
            },
            {
                "id": 2,
                "name": "Supplier 2"
            }
        ]
    },
    {
        "group_ref": null,
        "group_name": null,
        "completes_goal": 25,
        "remaining": 100,
        "fielded": 0,
        "cpi": 12,
        "last_start_date": "",
        "intent": {
            "intent_value": 0
        },
        "suppliers": [
            {
                "id": 3,
                "name": "Supplier 3"
            }
        ]
    }
]