Skip to main content
Reformulation alerts let you track when brands change the ingredients in their products. This matters because a sulphate-free shampoo that a user trusts may silently gain sulphates in a new batch, or a beloved leave-in may drop a key moisturising ingredient without fanfare. The Black Hair API periodically checks product ingredient lists and records every detected change as a ReformulationAlert — complete with before-and-after ingredient snapshots and a severity score.
The /v1/alerts/reformulations endpoint requires a Growth, Pro, or Enterprise plan. Requests made with a Starter API key receive a 403 Forbidden response.

​
What is a reformulation alert?

The API runs automated checks that compare a product’s current published ingredient list against the previously recorded version. When the lists differ, the system creates a ReformulationAlert record containing:
  • ingredients_before — the full ingredient list as it appeared before the change.
  • ingredients_after — the updated ingredient list as it appears now.
  • diff_summary — a plain-English description of what changed.
  • severity — a score (minor, significant, or major) that reflects the scale of the reformulation.
  • detected_at — the UTC timestamp when the change was detected.
You can poll this endpoint on a schedule and filter by severity so your integration only surfaces changes relevant to your users.

​
Fetch reformulation alerts

Send a GET request to /v1/alerts/reformulations. Without filters, the endpoint returns all recent alerts in reverse chronological order. 
curl "https://api.blackhairapi.com/v1/alerts/reformulations" \
  -H "X-API-Key: bha_your_api_key"

​
Filter by severity and date

Use the severity and since parameters together to fetch only the alerts that matter most to your use case. The example below retrieves all major reformulations detected since the start of 2024. 
curl "https://api.blackhairapi.com/v1/alerts/reformulations?severity=major&since=2024-01-01T00:00:00Z" \
  -H "X-API-Key: bha_your_api_key"

​
Query parameters

​
severity
string
Filter alerts by severity level. Accepted values: minor, significant, major. Omit this parameter to return alerts of all severity levels.
​
since
string
Return only alerts detected at or after this timestamp. Must be a valid ISO 8601 datetime string, e.g. 2024-01-01T00:00:00Z. Returns a 400 if the format is invalid.
​
page
integer
Page number for pagination. Starts at 1. Defaults to 1.
​
limit
integer
Number of alerts per page. Accepts values between 1 and 100. Defaults to 20.

​
Understanding severity levels

SeverityMeaning
minorSmall ingredient order or concentration changes — the product’s overall character is unchanged, but the formulation has been tweaked.
significantA key ingredient has been added or removed — for example, a protein source dropped or a silicone introduced. Users with sensitivities may notice a difference.
majorA core formula overhaul — multiple ingredients changed, or the fundamental product type has shifted. Previously saved user recommendations for this product should be treated as stale.

​
Alert response fields

​
id
string
The unique UUID for this reformulation alert.
​
product_id
string
The UUID of the product whose formula changed. Use this with GET /v1/products/{product_id}?include=ingredients to fetch the current product record.
​
product_name
string
The display name of the affected product.
​
severity
string
The reformulation severity: minor, significant, or major.
​
diff_summary
string
A plain-English description of what changed between the two ingredient lists, e.g. "Dimethicone removed. Glycerin concentration increased. Behentrimonium Chloride added.".
​
ingredients_before
string
The full ingredient list as it appeared before the reformulation was detected.
​
ingredients_after
string
The updated ingredient list as it appears after the reformulation.
​
detected_at
string
The ISO 8601 UTC timestamp when the change was first detected, e.g. "2024-06-14T09:32:11+00:00".
Example response 
{
  "data": [
    {
      "id": "f7a8b9c0-d1e2-3456-f789-0a1b2c3d4e5f",
      "product_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "product_name": "Honey & Shea Deep Conditioner",
      "detected_at": "2024-06-14T09:32:11+00:00",
      "severity": "major",
      "diff_summary": "Dimethicone added as the third ingredient. Shea butter moved from position 2 to position 6. Fragrance formulation changed.",
      "ingredients_before": "Water, Butyrospermum Parkii (Shea) Butter, Glycerin, Cetearyl Alcohol, Honey, Panthenol, Fragrance",
      "ingredients_after": "Water, Glycerin, Dimethicone, Cetearyl Alcohol, Butyrospermum Parkii (Shea) Butter, Panthenol, Parfum"
    }
  ]
}
A major severity alert means the product’s formula has changed substantially. If your application caches product recommendations or ingredient analysis, invalidate any cached data for the affected product_id and re-fetch the current ingredient record.
Poll this endpoint on a schedule — for example, once per day via a cron job — to keep your users informed about changes to products they rely on. Use since with the timestamp of your last successful poll to fetch only new alerts each run.