Segmentation API - SEL

Last Updated: Dec 19, 2025

SEL Segmentation API Integration Guide

This document provides comprehensive documentation for the Segmentation API. This API is crucial for understanding and categorizing individuals or households based on their Socioeconomic Level (SEL), which typically encompasses factors like income, education, occupation, and wealth. By leveraging this API, you can retrieve and save segmentation data, facilitating detailed market research, targeted campaigns, and analytical insights.

Access Requirements: To obtain credentials for this API, please contact our Commercial Sales Team.

Workflow Overview

The integration follows a two-step process: retrieving the required schema and then submitting respondent data for calculation.

Step	Endpoint	Action	Purpose
1	`GET /segmentation-qualifications`	Retrieve Schema	Identify the necessary qualifiers for a specific SEL qualification.
2	`POST /calculate-segmentation`	Derive Answer	Submit profile data to calculate the final segmentation result.

Implementation Details

Retrieve Required Qualifiers
Suppliers must first call the GET Segmentation Qualifications endpoint. The response defines the structure and specific data points required for a given SEL qualification.

Requirement: Use the metadata provided in this response to construct the request payload for the subsequent calculation step.

Calculate Segmentation Result
Once the respondent's profile data is collected, call the POST Calculate Segmentation endpoint. This service processes the input data against the SEL logic to determine the appropriate segment.

Please note: in the GET request, answer IDs are returned as answers, whereas in the POST answer ID is returned as segment_id

API Documentation

1. API Overview

The Segmentation API allows external applications/partners to retrieve and save segmentation data for qualification processes.

Base URL: http://{{environmentURL}}/suppliers/v2
Environment URL - {{environmentURL}}
- Staging: http://staging.spectrumsurveys.com
- Production: https://api.spectrumsurveys.com
Authentication: All requests require authentication. Please include a Supplier Token in the x-access-token header for all requests.
- Example Header: x-access-token: YOUR_SUPPLIER_TOKEN_HERE
Error Handling:
- Errors are returned with appropriate HTTP status codes and a specific JSON format.
- Error responses will typically follow the format:
  { "ps_api_response_code": 9999, "ps_api_response_message": "A human-readable description of the error." }

2. GET APIs

2.1. Get Segmentation Qualifications

Retrieves a list of available segmentation qualifications and their associated answers.

Endpoint: /segmentation/qualifications
Method: GET
Description: This endpoint fetches segmentation qualifications based on locale and parent qualification IDs.
Available qualifications:

Query Parameters:

Parameter	Type	Required	Description	Example

Parameter	Type	Required	Description	Example
`locale`	`string`	Yes	Combination of language and country code.	`en_IN`
`qualIds`	`string`	Yes	The parent segmentation qualification ID(s). Multiple IDs can be sent if separated by commas.	`4209` or `4209,3910`

Example Request:

GET http://{{environmentURL}}/suppliers/v2/segmentation/qualifications?locale=en_IN&qualIds=4209,3910
x-access-token: YOUR_SUPPLIER_TOKEN_HERE

Example Response (Success - 200 OK):

[
    {
        "4209": {
            "qualification_id": 4209,
            "question_type": "singlepunch",
            "question_order_number": 2994,
            "question_description": "ISEC - Segmentation Parent Edition ",
            "answers": [
                {
                    "id": 111,
                    "text": "ISEC - 1",
                    "eng_text": "ISEC - 1"
                },
                {
                    "id": 120,
                    "text": "ISEC - 10",
                    "eng_text": "ISEC - 10"
                }
                // ... other answers
            ],
            "segmentation": {
                "parent_qualification_id": null
            },
            "question_text": "I'm looking for  %%4209%%",
            "children": [
                {
                    "qualification_id": 4253,
                    "question_type": "singlepunch",
                    "question_order_number": 3038,
                    "question_description": "ISECQ1",
                    "answers": [
                        {
                            "id": 111,
                            "text": "Labour",
                            "eng_text": "Labour"
                        }
                        // ... other answers
                    ],
                    "segmentation": {
                        "parent_qualification_id": 4209
                    },
                    "question_text": "What is the occupation of the person who contributes the most to the running of your household? (If retired or unemployed, what was their occupation before they retired/were out of work? %%4253%%"
                }
                // ... other children qualifications
            ]
        }
    }
]

Example Response (Error - 400 Bad Request: Missing Parameters):

{
    "ps_api_response_code": 9999,
    "ps_api_response_message": "Missing required parameters."
}

HTTP Status Codes:

200 OK: Request successful, segmentation qualifications returned.
400 Bad Request: Invalid or missing query parameters (locale or qualIds).
401 Unauthorized: Missing or invalid x-access-token.
500 Internal Server Error: An unexpected server error occurred.

2.2. Errors

Required parameters not provided (locale and qualIds)

Example:

https://{{environmentURL}}/suppliers/v2/segmentation/qualifications?locale=en_US

https://{{environmentURL}}/suppliers/v2/segmentation/qualifications?qualIds=3910

How to fix: provide parameters with valid values

{
    "apiStatus": "fail",
    "msg": "Missing required parameters."
}

Invalid parameters provided (locale or qualIds)

Example:

https://{{environmentURL}}/suppliers/v2/segmentation/qualifications?locale=en_USA&qualIds=3912

How to fix: provide valid parameters (“en_US“ and “3912“ instead of en_USA and 0001)

{
    "apiStatus": "Failure",
    "msg": "Not a segmentation qualification."
}

3. POST APIs

3.1. Calculate Segmentation

Calculates and processes segmentation data for a specific respondent/memberId, sending all necessary information in the request body.

Endpoint: /segmentation/calculate
Method: POST
Description: This endpoint accepts segmentation data for a given member and processes it to determine their segmentation results.

Request Body Parameters (JSON):

Parameter	Type	Required	Description	Example

Parameter	Type	Required	Description	Example
`locale`	`string`	Yes	Combination of language and country code.	`en_IN`
`member_id`	`string`	Yes	The unique ID of the member for whom segmentation is calculated.	`some_member_id_xyz`
`segmentation_answers`	`array`	Yes	An array of qualification objects containing the selected answers for each segmentation question.	See Example Request for structure

Example Request:

POST http://{{environmentURL}}/suppliers/v2/segmentation/calculate
x-access-token: YOUR_SUPPLIER_TOKEN_HERE

Example Payload:

{
    "locale": "en_US",
    "member_id": "some_member_id_xyz",
    "segmentation_answers": [
        {
            "qualification_id": 3911,
            "question_type": "singlepunch",
            "question_description": "USQ1",
            "answers": [
                {
                    "id": 111,
                    "text": "0",
                    "eng_text": "0"
                }
            ],
            "segmentation": {
                "parent_qualification_id": 3910
            }
        },
        {
            "qualification_id": 3912,
            "question_type": "singlepunch",
            "question_description": "USQ2",
            "answers": [
                {
                    "id": 111,
                    "text": "Spanish Only",
                    "eng_text": "Spanish Only"
                }
            ],
            "segmentation": {
                "parent_qualification_id": 3910
            }
        },
        {
            "qualification_id": 3913,
            "question_type": "singlepunch",
            "question_description": "USQ3",
            "answers": [
                {
                    "id": 111,
                    "text": "Much closer to Hispanic/Latino Culture",
                    "eng_text": "Much closer to Hispanic/Latino Culture"
                }
            ],
            "segmentation": {
                "parent_qualification_id": 3910
            }
        },
        {
            "qualification_id": 3914,
            "question_type": "singlepunch",
            "question_description": "USQ4",
            "answers": [
                {
                    "id": 111,
                    "text": "Spanish media only",
                    "eng_text": "Spanish media only"
                }
            ],
            "segmentation": {
                "parent_qualification_id": 3910
            }
        }
    ]
}

Example Response (Success - 200 OK) - 1st attempt/calculation:

{
    "apiStatus": "Success",
    "locale": "en_US",
    "memberId": "some_member_id_xyz",
    "segmentation": {
        "question_description": "Segmentation Parent Edition",
        "qualification_id": 3910,
        "segment_text": "Less Acculturated",
        "segment_id": 111
    }
}

HTTP Status Codes:

200 OK: Data successfully processed.
400 Bad Request: Invalid or missing request body parameters.
401 Unauthorized: Missing or invalid x-access-token.
500 Internal Server Error: An unexpected server error occurred.

3.2. Errors

Only one answer allowed

Example:

https://{{environmentURL}}/suppliers/v2/segmentation/calculate

{
    "apiStatus": "Failure",
    "msg": "Only one answer is allowed for qualification 3911."
}

Invalid payload example with multiple answers:

   "segmentation_answers": [
        {
            "qualification_id": 3911,
            "question_type": "singlepunch",
            "question_order_number": 2716,
            "question_description": "USQ1",
            "answers": [
                {
                    "id": 111,
                    "text": "0",
                    "eng_text": "0"
                },
                {
                    "id": 112,
                    "text": "1 - 5",
                    "eng_text": "1 - 5"
                }
            ],
            "segmentation": {
                "parent_qualification_id": 3910
            },
            "question_text": "Please think about the first 18 years of our life. How many of those years did you live in the U.S.?  %%3911%%"
        }
        (...)

How to fix: provide just one answer per child.

    "segmentation_answers": [
        {
            "qualification_id": 3911,
            "question_type": "singlepunch",
            "question_description": "USQ1",
            "answers": [
                {
                    "id": 111,
                    "text": "0",
                    "eng_text": "0"
                }
            ],

Invalid value for open ended answer

Example:

https://{{environmentURL}}/suppliers/v2/segmentation/calculate

{
    "apiStatus": "Failure",
    "msg": "Error on regex open ended"
}

Invalid payload example with answers not respecting value for an Open Ended.

        (...)
            "qualification_id": 4051,
            "question_type": "input",
            "question_description": "MXQ3",
            "answer_placeholder": "0-99",
            "answers": [
                {
                    "value": -1
                }
            ],
        (...)

How to fix: Provide a valid Open Ended value, as suggested on answer_placeholder (0 to 99).

        (...)
            "qualification_id": 4051,
            "question_type": "input",
            "question_description": "MXQ3",
            "answer_placeholder": "0-99",
            "answers": [
                {
                    "value": 2
                }
            ],
        (...)

4. Common Data Structures

Segmentation Qualification Object (GET Response)

Represents a segmentation qualification, with nested child qualifications and answers. The top-level response is an array of objects where the key is the qualification_id.

Field	Type	Description

Field	Type	Description
`{qualification_id}`	`object`	An object representing the qualification itself, keyed by its ID.
`qualification_id`	`integer`	Unique identifier for the qualification.
`question_type`	`string`	Type of question (e.g., `singlepunch`).
`question_order_number`	`integer`	Order number of the question.
`question_description`	`string`	A short description of the question.
`answers`	`array`	List of possible answers for this qualification.
`answers[].id`	`integer`	ID of the answer.
`answers[].text`	`string`	Text of the answer.
`answers[].eng_text`	`string`	English text of the answer.
`segmentation`	`object`	Contains segmentation-specific details.
`segmentation.parent_qualification_id`	`integer`	The ID of the parent qualification, if applicable (null for top-level).
`question_text`	`string`	The full question text.
`children`	`array`	An array of nested child qualification objects.

Segmentation Calculation Payload (POST Request Body)

Represents the data structure for the POST request to calculate segmentation. For segmentation_answers, the GET API will provide that, and respondent answer should be sent on the POST API for calculation.

Field	Type	Description

Field	Type	Description
`locale`	`string`	Combination of language and country code.
`member_id`	`string`	The unique ID of the member.
`segmentation_answers`	`array`	An array of objects, each representing a submitted qualification answer.
`segmentation_answers[].qualification_id`	`integer`	Unique identifier for the qualification being submitted.
`segmentation_answers[].question_type`	`string`	Type of question (e.g., `singlepunch`).
`segmentation_answers[].question_description`	`string`	A short description of the question.
`segmentation_answers[].answers`	`array`	List of selected answers for this qualification.
`segmentation_answers[].answers[].id`	`integer`	ID of the selected answer.
`segmentation_answers[].answers[].text`	`string`	Text of the selected answer.
`segmentation_answers[].answers[].eng_text`	`string`	English text of the selected answer.
`segmentation_answers[].segmentation`	`object`	Contains segmentation-specific details.
`segmentation_answers[].segmentation.parent_qualification_id`	`integer`	The ID of the parent qualification.