Benefits

Create a new Benefit

A POST to the benefits endpoint is used to create a new benefit to enable a benefit features for an organisation.

Each of these entries relates to a particular benefit type and relates to a particular organisation and a particular time period.

post/api/v2/partner/organisations/{organisation_id}/benefits

Request

  • Base URL: http://localhost:5100
  • URL: http://localhost:5100/api/v2/partner/organisations/{organisation_id}/benefits
  • Auth: API key in header Authorization

Path parameters

organisation_idinteger required

ID of the organisation to which we are adding a benefit

Request body

relative_url'travel_and_leisure' | 'cycle_to_work' | 'bike_shop' | 'home_and_electronics' | 'car_scheme' | 'gym_membership' | 'annual_leave_purchase' | 'family_pay' | 'family_care' | 'vivup_highfive' | 'lifestyle_savings' | 'holiday_clubs' | 'your_care_wellbeing_platform' required

The benefit type

quote_type'NHS' | 'Non NHS' | 'NET' | 'Council LGPS' | 'Teachers' Pension'

One of several valid quote types describing the type of quotes involved

start_datestring date

The start date of the benefit

end_datestring date

The end date of the benefit

first_payroll_reduction_monthstring date

Month when the user will have their salary sacrifice payroll reduction first applied

limit_valuenumber float

Integer number of pounds for the maximum value limit of user's total active orders in this benefit.

limit_percentagenumber float

Percentage amount of the user's total active order limit.

income_generation_percentageinteger

Income generation percentage for benefit-level income generation settings. Must be an integer between 1 and 5, inclusive.

sso_company_namestring

Name used for organisation when doing single sign-on. Need to contact with team when updating any new values in this field.

faq_urlstring uri

URL to the FAQ page for the benefit

terms_n_conds_urlstring uri

URL to the terms and conditions page for the benefit

monthly_termsinteger[]

Number of months over which the benefit applies. This is an array because multiple selections are allowed, e.g. [12,24]. For benefits other than Cycle to Work the available options are 12, 24, 36. For Cycle to work the available options are 12, 18.

Example request

{
  "relative_url": "home_and_electronics",
  "quote_type": "NHS",
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "first_payroll_reduction_month": "2025-01-01",
  "limit_value": 1000,
  "limit_percentage": 10,
  "income_generation_percentage": 3,
  "sso_company_name": "Acme Ltd",
  "faq_url": "https://example.com/faq",
  "terms_n_conds_url": "https://example.com/terms",
  "monthly_terms": [
    12,
    18
  ]
}

Response

Benefit created

successboolean
messagestring

Example response

{
  "success": true,
  "message": "Benefit created successfully",
  "benefit": {
    "start_date": "2025-06-01",
    "end_date": "2026-06-01",
    "relative_url": "home_and_electronics",
    "quote_type": "NHS",
    "sso_company_name": "ACME Ltd"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.