Update the list of suppliers for a survey

Description

Every survey in PureSpectrum has a list of suppliers that send sample. You may update the list of suppliers, and their goal, using this API endpoint.

This API endpoint may be used to update a survey’s supplier list by updating a supplier’s completes_required, or by grouping suppliers together.

To remove a supplier - set their completes_required to 0.

Supplier allocations may add up to more than or less than 100% of the survey’s goal.

To set flexibility among suppliers, set the completes_goal values to be in excess of the survey’s goal.

To pace the flexibility among suppliers, set the completes_goal values to be less than the survey’s goal.

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.

Grouping suppliers together

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.

When grouping suppliers together, you must provide a name for this group via group_name. 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.

A group reference id can can be set in the request group_ref. If a group ref is not passed in, we will create one for you and return in the response.

Request

Path Params

Header Params

Body Params application/json

Example

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

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Success

application/json

Body

Example

[
    {
        "group_ref": "sg4bcf88be",
        "group_name": "Supplier Group 1",
        "completes_goal": 25,
        "current_target": 50,
        "remaining": 25,
        "fielded": 0,
        "cpi": 33.42,
        "bid_cpi": null,
        "last_start_date": "",
        "last_complete_date": "",
        "intent": {
            "intent_count": null,
            "intent_not_set": [
                7,
                36
            ],
            "intent_denied": [],
            "intent_accepted": [],
            "child_intent_stats": {}
        },
        "buyer_in_progress": 0,
        "currency_symbol": "£",
        "suppliers": [
            {
                "id": 7,
                "name": "Say For Example",
                "allocation": 100
            },
            {
                "id": 36,
                "name": "PramodNagar",
                "allocation": 100
            }
        ],
        "is_pds_applied": false,
        "groupPercentage": 100,
        "quantity": 1050,
        "ps_start_count_24": 0,
        "valid_clicks": 0,
        "valid_epc": 0,
        "valid_click_percentage": 0,
        "total_epc": 0,
        "srv_start_count": 0,
        "max_cpi": 33.42,
        "conversion_rate": 33
    },
    {
        "group_ref": null,
        "group_name": null,
        "completes_goal": 0,
        "current_target": 3,
        "remaining": 0,
        "fielded": 0,
        "currency_symbol": "£",
        "cpi": 5.15,
        "bid_cpi": null,
        "buyer_in_progress": 0,
        "last_start_date": "",
        "last_complete_date": "",
        "intent": {
            "intent_count": null,
            "intent_not_set": [
                16
            ],
            "intent_denied": [],
            "intent_accepted": [],
            "child_intent_stats": {}
        },
        "suppliers": [
            {
                "id": 16,
                "name": "Innovate",
                "allocation": 100
            }
        ],
        "is_pds_applied": false,
        "fee": null,
        "ps_start_count_24": 0,
        "valid_clicks": 0,
        "valid_epc": 0,
        "valid_click_percentage": 0,
        "total_epc": 0,
        "srv_start_count": 0,
        "max_cpi": null,
        "conversion_rate": 33
    },
    {
        "group_ref": null,
        "group_name": null,
        "completes_goal": 0,
        "current_target": 3,
        "remaining": 0,
        "fielded": 0,
        "currency_symbol": "£",
        "cpi": 5.15,
        "bid_cpi": null,
        "buyer_in_progress": 0,
        "last_start_date": "",
        "last_complete_date": "",
        "intent": {
            "intent_count": null,
            "intent_not_set": [
                17
            ],
            "intent_denied": [],
            "intent_accepted": [],
            "child_intent_stats": {}
        },
        "suppliers": [
            {
                "id": 17,
                "name": "P2 Sample",
                "allocation": 100
            }
        ],
        "is_pds_applied": false,
        "fee": null,
        "ps_start_count_24": 0,
        "valid_clicks": 0,
        "valid_epc": 0,
        "valid_click_percentage": 0,
        "total_epc": 0,
        "srv_start_count": 0,
        "max_cpi": null,
        "conversion_rate": 33
    },
    {
        "group_ref": null,
        "group_name": null,
        "completes_goal": 0,
        "current_target": 3,
        "remaining": 0,
        "fielded": 0,
        "currency_symbol": "£",
        "cpi": 5.15,
        "bid_cpi": null,
        "buyer_in_progress": 0,
        "last_start_date": "",
        "last_complete_date": "",
        "intent": {
            "intent_count": null,
            "intent_not_set": [
                18
            ],
            "intent_denied": [],
            "intent_accepted": [],
            "child_intent_stats": {}
        },
        "suppliers": [
            {
                "id": 18,
                "name": "Sago",
                "allocation": 100
            }
        ],
        "is_pds_applied": false,
        "fee": null,
        "ps_start_count_24": 0,
        "valid_clicks": 0,
        "valid_epc": 0,
        "valid_click_percentage": 0,
        "total_epc": 0,
        "srv_start_count": 0,
        "max_cpi": null,
        "conversion_rate": 33
    }
]

🟠400Bad Request

🟠404Record Not Found

Update the list of suppliers for a survey

Description#

Important Considerations#

Grouping suppliers together#

Important Considerations#

Request

Request Code Samples

Responses

Description

Important Considerations

Grouping suppliers together

Important Considerations