{"openapi":"3.0.3","info":{"title":"UK Bereavement Notification Registry API","version":"1.0.0","description":"A REST API exposing bereavement contact information for 909 UK service providers — banks, insurers, pension schemes, utilities, government bodies, charities, and more. Built to help families and estate administrators find the right contact details quickly after a death.\n\nFollows the [UK Government Digital Service (GDS) API Technical and Data Standards](https://www.gov.uk/guidance/gds-api-technical-and-data-standards) (July 2024).","license":{"name":"Open Government Licence v3.0","url":"https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"}},"servers":[{"url":"/api","description":"API base path"}],"tags":[{"name":"health","description":"Service health and status checks"},{"name":"organisations","description":"Bereavement contact information for individual organisations"},{"name":"categories","description":"Browse the taxonomy of organisation categories and sub-categories"},{"name":"groups","description":"Corporate group membership and single-notification contacts"},{"name":"urgency","description":"Notification urgency tiers and the order in which to contact providers"}],"paths":{"/healthz":{"get":{"tags":["health"],"summary":"Health check","description":"Returns API operational status, version, and total organisation count.","responses":{"200":{"description":"API is operational","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"version":{"type":"string","example":"1.0.0"},"total_organisations":{"type":"integer","example":909}}}}}}}}},"/v1/organisations":{"get":{"tags":["organisations"],"summary":"List organisations","description":"Returns a paginated, alphabetically-sorted list of organisations with their bereavement contact details. Supports full-text search and filtering.","parameters":[{"name":"q","in":"query","description":"Full-text search across organisation name, category, sub-category, and special notes (max 200 chars)","schema":{"type":"string","maxLength":200}},{"name":"category","in":"query","description":"Filter by top-level category (case-insensitive exact match), e.g. Bank, Insurance, Pension","schema":{"type":"string"}},{"name":"sub_category","in":"query","description":"Filter by sub-category (case-insensitive exact match)","schema":{"type":"string"}},{"name":"tell_us_once","in":"query","description":"Filter by Tell Us Once coverage (e.g. Yes, No, N/A)","schema":{"type":"string"}},{"name":"parent_group","in":"query","description":"Filter by parent corporate group (case-insensitive exact match)","schema":{"type":"string"}},{"name":"urgency","in":"query","description":"Filter by notification urgency tier","schema":{"type":"string","enum":["tier_1_critical","tier_2_high","tier_3_medium","tier_4_low"]}},{"name":"page","in":"query","description":"Page number (1-based, default 1)","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","description":"Results per page (1–100, default 20)","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Paginated list of organisations","headers":{"Cache-Control":{"schema":{"type":"string"}},"X-Request-ID":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Organisation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"},"links":{"$ref":"#/components/schemas/PaginationLinks"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/v1/organisations/{slug}":{"get":{"tags":["organisations"],"summary":"Get a single organisation","description":"Returns full bereavement contact details for a single organisation identified by its URL-safe slug. Slug algorithm: lowercase → replace non-alphanumeric sequences with hyphens → strip leading/trailing hyphens.","parameters":[{"name":"slug","in":"path","required":true,"description":"URL-safe slug derived from organisation_name, e.g. barclays, hmrc, royal-london","schema":{"type":"string"}}],"responses":{"200":{"description":"Organisation detail","headers":{"Cache-Control":{"schema":{"type":"string"}},"ETag":{"schema":{"type":"string"}},"X-Request-ID":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Organisation"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/categories":{"get":{"tags":["categories"],"summary":"List all categories","description":"Returns every distinct category and sub-category combination in the registry with organisation counts. Sorted alphabetically by category then sub-category.","responses":{"200":{"description":"Category list with counts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","example":"Bank"},"sub_category":{"type":"string","example":"Current/Savings"},"count":{"type":"integer","example":19}}}},"meta":{"type":"object","properties":{"total":{"type":"integer","example":292}}}}}}}}}}},"/v1/urgency-tiers":{"get":{"tags":["urgency"],"summary":"List notification urgency tiers","description":"Returns the four notification urgency tiers with their definitions, recommended timeframes, and a live count of how many organisations sit in each tier. Every organisation is assigned a tier based on its category and sub-category, with all Tell Us Once–covered services forced to tier 1 (critical).","responses":{"200":{"description":"Urgency tier definitions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string","enum":["tier_1_critical","tier_2_high","tier_3_medium","tier_4_low"]},"label":{"type":"string","example":"Critical"},"rank":{"type":"integer","example":1},"timeframe":{"type":"string"},"short_timeframe":{"type":"string"},"why_it_matters":{"type":"string"},"organisation_count":{"type":"integer","example":75}}}},"meta":{"type":"object","properties":{"total":{"type":"integer","example":4}}}}}}}}}}},"/v1/groups":{"get":{"tags":["groups"],"summary":"List all corporate groups","description":"Returns every distinct parent group in the registry. Where group_single_notification is Yes, one notification to group_notification_contact covers all member organisations.","responses":{"200":{"description":"Corporate group list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"parent_group":{"type":"string","example":"Barclays Group"},"member_count":{"type":"integer","example":3},"group_single_notification":{"type":"string","nullable":true,"example":"Yes"},"group_notification_contact":{"type":"string","nullable":true}}}},"meta":{"type":"object","properties":{"total":{"type":"integer","example":68}}}}}}}}}}}},"components":{"schemas":{"Organisation":{"type":"object","properties":{"slug":{"type":"string","example":"barclays"},"organisation_name":{"type":"string","example":"Barclays"},"category":{"type":"string","example":"Bank"},"sub_category":{"type":"string","example":"Current/Savings"},"notification_urgency":{"type":"string","enum":["tier_1_critical","tier_2_high","tier_3_medium","tier_4_low"],"description":"Recommended urgency for notifying this provider after a death. Tier 1 (critical) = within 5 working days; tier 2 (high) = within 2 weeks; tier 3 (medium) = within 1 month; tier 4 (low) = within 3 months. All Tell Us Once–covered organisations are tier 1.","example":"tier_2_high"},"bereavement_phone":{"type":"string","nullable":true,"example":"0800 151 0023"},"bereavement_email":{"type":"string","nullable":true,"example":"bereavement@barclays.co.uk"},"bereavement_online_form":{"type":"string","nullable":true,"example":"https://www.barclays.co.uk/bereavement/"},"bereavement_postal_address":{"type":"string","nullable":true},"preferred_notification_method":{"type":"string","nullable":true,"example":"Phone or branch"},"accepts_digital_death_notification":{"type":"string","nullable":true,"example":"Yes"},"documents_required":{"type":"string","nullable":true},"what_happens_to_account":{"type":"string","nullable":true},"probate_required":{"type":"string","nullable":true,"example":"Yes - above threshold"},"probate_threshold_gbp":{"type":"string","nullable":true,"example":"50000"},"typical_processing_days":{"type":"string","nullable":true,"example":"14-28"},"early_termination_fees_waived":{"type":"string","nullable":true},"refund_of_unused_balance":{"type":"string","nullable":true},"joint_account_policy":{"type":"string","nullable":true},"survivor_pension_or_benefit":{"type":"string","nullable":true},"special_notes":{"type":"string","nullable":true},"parent_group":{"type":"string","nullable":true,"example":"Barclays Group"},"group_single_notification":{"type":"string","nullable":true,"example":"Yes"},"group_notification_contact":{"type":"string","nullable":true},"tell_us_once_covered":{"type":"string","nullable":true}}},"PaginationMeta":{"type":"object","properties":{"total":{"type":"integer","example":909},"page":{"type":"integer","example":1},"per_page":{"type":"integer","example":20},"total_pages":{"type":"integer","example":46}}},"PaginationLinks":{"type":"object","properties":{"self":{"type":"string"},"first":{"type":"string"},"last":{"type":"string"},"next":{"type":"string","nullable":true},"prev":{"type":"string","nullable":true}}},"GdsError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GdsError"}}}},"ValidationError":{"description":"Validation error — invalid query parameter value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GdsError"}}}}}}}