Get needs configuration by service

This endpoint returns the needs configuration defined for each product of the service specified in the URL.

GET /api/v1/businesses/{businessId}/services/{serviceId}/needs-config

If the data included in the URL is correct, the response will contain, for each product of the service that has a needs configuration, its seasons (seasons) and the proposals active in them.

Response example

{
    "businessId": "BUSINESSID",
    "serviceId": "0001",
    "products": [
        {
            "productId": "0001-GENERAL",
            "productName": "GENERAL",
            "seasons": [
                {
                    "id": "2026-GEN",
                    "name": "General",
                    "fromMonthDay": "01-01",
                    "toMonthDay": "12-31",
                    "addressable": true,
                    "proposals": [
                        {
                            "id": "PRT",
                            "name": "Productivity",
                            "defaultProposal": true,
                            "addressable": true,
                            "steps": [
                                {
                                    "id": "STP1",
                                    "name": "Productivity",
                                    "order": 4,
                                    "type": "PRODUCTIVITY",
                                    "addressable": true
                                }
                            ]
                        },
                        {
                            "name": "Dynamic template",
                            "defaultProposal": false,
                            "addressable": false,
                            "steps": [
                                {
                                    "name": "Dynamic template",
                                    "order": 1,
                                    "type": "DYNAMIC_TEMPLATES",
                                    "addressable": false
                                },
                                {
                                    "name": "Dynamic template 2",
                                    "order": 2,
                                    "type": "DYNAMIC_TEMPLATES",
                                    "addressable": false
                                }
                            ]
                        },
                        {
                            "name": "Hourly budget",
                            "defaultProposal": false,
                            "addressable": false,
                            "steps": [
                                {
                                    "name": "Recommendation based on hourly budget",
                                    "order": 1,
                                    "type": "BUDGET_HOUR",
                                    "addressable": false
                                }
                            ]
                        },
                        {
                            "name": "Training",
                            "defaultProposal": false,
                            "addressable": false,
                            "steps": [
                                {
                                    "name": "Training",
                                    "order": 1,
                                    "type": "PREPARATION",
                                    "addressable": false
                                },
                                {
                                    "name": "Productivity",
                                    "order": 2,
                                    "type": "PRODUCTIVITY",
                                    "addressable": false
                                },
                                {
                                    "name": "Test template",
                                    "order": 3,
                                    "type": "DYNAMIC_TEMPLATES",
                                    "addressable": false
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}
Details

  • businessId: external identifier of the business.

  • serviceId: external identifier of the service.

  • products: products of the service that have a needs configuration. Each product includes the following information:

    • productId: external identifier of the product or section.

    • productName: name of the product or section.

    • seasons: seasons configured for the product. Each season includes the following information:

      • id: external identifier of the season. Can be null, in which case the season cannot be referenced through the API.

      • name: name of the season.

      • fromMonthDay: start of the season, in MM-dd format.

      • toMonthDay: end of the season, in MM-dd format.

      • year: year the season is restricted to. Can be null if it applies to every year.

      • addressable: indicates whether this season can be referenced through the API. It is false when it has no external identifier.

      • proposals: needs generator proposals active in the season. Each proposal includes the following information:

        • id: external identifier of the proposal. Can be null if it has not been defined in the system.

        • name: name of the proposal.

        • defaultProposal: indicates whether this is the default proposal.

        • addressable: indicates whether this proposal can be referenced through the API. It is false when it has no external identifier.

        • steps: steps of the proposal, in execution order. Each step includes the following information:

          • id: external identifier of the step. Can be null, in which case the step cannot be referenced through the API.

          • name: name of the step.

          • order: position of the step within the proposal, as stored.

          • type: type of the step, which determines how it is configured. Possible values are BRMS, PRODUCTIVITY, ASSISTED_SALE, BUDGET_HOUR, PREPARATION, REST, DYNAMIC_TEMPLATES, ACCUMULATIVE, LOWEST_DEMAND, CHECKOUT_SIMULATION.

          • addressable: indicates whether this step can be modified through the API. It is false when it has no external identifier or when its type is not yet supported.

As shown in the example, the response groups the needs generator seasons and proposals configured, by product, along with the steps of each proposal. Only the PRT proposal and its STP1 step can be referenced and modified through the API.

Considerations

If the product has no active proposal associated with a season, the response will return "seasons": [].

If a proposal has no configured steps, the response will return "steps": [] for that proposal.

The addressable field will be true if the element has an external identifier and can be referenced through the API. For steps (steps), its generation type must also be supported for writing.

Error codes

This endpoint does not return any error codes of its own beyond those described in common errors.

Useful links

What are needs?

What is a needs generator?