PureSpectrum
PureSpectrum websiteHelp center
PureSpectrum websiteHelp center
  1. Supplier management
  • Back to home
  • API Reference
  • Feasibility
    • Feasibility & Pricing
  • Attributes
    • Get attribute (V3)
    • Get attributes (V3)
  • Surveys
    • Create survey
    • Get similar surveys
    • Create group multi-country surveys
    • Update survey
    • Update survey
    • Update survey status
    • Update offer price
    • Update group multi-country surveys
    • Get survey information
    • Get survey status
    • Get survey performance
    • Get list of all surveys
    • Surveys health status
    • Pacing details
    • Delete survey
  • Qualifications
    • Add qualification
    • Update qualification
    • Get qualification information
    • Get all qualifications
    • Delete qualification
  • Quotas
    • Add quota
    • Update quota
    • Update quota
    • Get quota information
    • Get quota performance
    • Delete quota
  • Survey group exclusions
    • Create exclusion group
    • Update exclusion group
    • Get exclusion group information
    • Delete exclusion group
  • Respondent inclusion / exclusion
    • Add a PSIDref list to a survey
    • Update a PSIDref for survey
    • Get PSIDref list for survey
  • Supplier management
    • Create supplier blend
      POST
    • Update the list of suppliers for a survey
      PUT
    • Get list of available suppliers in a locale
      GET
    • Get list of available suppliers for a survey
      GET
    • Get list of supplier blends
      GET
  • Traffic Channels
    • Create traffic channel
    • Get a list of traffic channels
  • Transactions
    • Update status of transaction (V2)
    • Update status of transaction (V3)
    • Register transaction as complete
    • Get transaction status (V3)
    • Get transaction info (V3)
    • Get transactions info for a survey ID (V3)
  • Reconciliation
    • Survey reconciliation
    • Multi survey reconciliation
    • Get status of a reconciliation request
    • Get reconciliation status for an adjustment ID
  • PureText
    • PureText Open-ended (OE) check (V3)
  • Activity logs
    • Get activity logs
    • Get events
  • Templates
    • Get survey templates
  1. Supplier management

Update the list of suppliers for a survey

PUT
/surveys/{SURVEY_ID}/suppliers
Last modified:2025-09-16 21:03:01

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

Authorization
Add parameter in header
access-token
Example:
access-token: ********************
Path 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
Go
PHP
Python
C#
Ruby
Request Request Example
Shell
JavaScript
Java
Go
curl --location --request PUT 'https://staging.spectrumsurveys.com/buyers/v2/surveys/1234567/suppliers' \
--header 'access-token: <api-key>' \
--header 'Content-Type: application/json' \
--data '[
    {
        "cpi": 33.42,
        "completes_goal": 25,
        "group_name": "Supplier Group 1",
        "suppliers": [
            1,
            2
        ]
    },
    {
        "cpi": 12,
        "completes_goal": 25,
        "suppliers": [
            3
        ]
    }
]'

Responses

🟢200Success
application/json
Bodyapplication/json

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
Modified at 2025-09-16 21:03:01
Previous
Create supplier blend
Next
Get list of available suppliers in a locale