Organisations

GET /organisation

[
  {
    "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "name": "Cabinet Office",
    "active": true,
    "count_of_live_services": 5,
    "domains": ["cabinetoffice.gov.uk"],
    "organisation_type": "central"
  },
  {
    "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
    "name": "Department for Education",
    "active": true,
    "count_of_live_services": 12,
    "domains": ["education.gov.uk"],
    "organisation_type": "central"
  }
]

GET /organisation/{organisation_id}

{
  "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "name": "Cabinet Office",
  "active": true,
  "crown": true,
  "organisation_type": "central",
  "email_branding_id": "3f5e7c9a-1b2d-4e8f-9a3c-7d6e4b2f1a8c",
  "letter_branding_id": "5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c",
  "agreement_signed": true,
  "agreement_signed_at": "2024-01-15T10:00:00.000000Z",
  "agreement_signed_by_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "agreement_signed_on_behalf_of_name": null,
  "agreement_signed_on_behalf_of_email_address": null,
  "agreement_signed_version": 2.5,
  "domains": ["cabinetoffice.gov.uk"],
  "request_to_go_live_notes": null,
  "count_of_live_services": 5,
  "notes": "Primary central government department",
  "purchase_order_number": "PO-2024-001",
  "billing_contact_names": "Jane Smith",
  "billing_contact_email_addresses": "[email protected]",
  "billing_reference": "CO-001",
  "can_approve_own_go_live_requests": true,
  "permissions": ["can_ask_to_join_service"]
}

GET /organisation/by-domain?domain={domain}

GET /organisation/by-domain?domain=education.gov.uk

{
  "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
  "name": "Department for Education",
  "active": true,
  "crown": true,
  "organisation_type": "central",
  "domains": ["education.gov.uk"],
  "count_of_live_services": 12
}

GET /organisation/search?name={search_term}

GET /organisation/search?name=Education

{
  "data": [
    {
      "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
      "name": "Department for Education",
      "active": true,
      "count_of_live_services": 12,
      "domains": ["education.gov.uk"],
      "organisation_type": "central"
    }
  ]
}

POST /organisation

{
  "name": "Ministry of Justice",
  "crown": true,
  "organisation_type": "central",
  "active": true
}

{
  "id": "4d5e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
  "name": "Ministry of Justice",
  "active": true,
  "crown": true,
  "organisation_type": "central",
  "email_branding_id": null,
  "letter_branding_id": null,
  "agreement_signed": null,
  "domains": [],
  "count_of_live_services": 0,
  "can_approve_own_go_live_requests": false,
  "permissions": []
}

{
  "result": "error",
  "message": "Organisation name already exists"
}

POST /organisation/{organisation_id}

{
  "name": "Ministry of Justice",
  "email_branding_id": "3f5e7c9a-1b2d-4e8f-9a3c-7d6e4b2f1a8c",
  "can_approve_own_go_live_requests": true
}

POST /organisation/{organisation_id}/archive

{
  "result": "error",
  "message": "Cannot archive an organisation with active services"
}

{
  "result": "error",
  "message": "Cannot archive an organisation with team members or invited team members"
}

POST /organisation/{organisation_id}/service

{
  "service_id": "8c9d0e1f-2a3b-4c5d-6e7f-8a9b0c1d2e3f"
}

GET /organisation/{organisation_id}/services

[
  {
    "id": "8c9d0e1f-2a3b-4c5d-6e7f-8a9b0c1d2e3f",
    "name": "Tax Notifications",
    "active": true,
    "restricted": false,
    "message_limit": 250000,
    "organisation_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  },
  {
    "id": "9d0e1f2a-3b4c-5d6e-7f8a-9b0c1d2e3f4a",
    "name": "Staff Communications",
    "active": false,
    "restricted": true,
    "message_limit": 50,
    "organisation_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  }
]

GET /organisation/{organisation_id}/services-with-usage?year={year}

{
  "services": [
    {
      "service_id": "8c9d0e1f-2a3b-4c5d-6e7f-8a9b0c1d2e3f",
      "service_name": "Tax Notifications",
      "active": true,
      "email_totals": 125000,
      "sms_totals": 50000,
      "letter_totals": 15000,
      "sms_cost": 2500.00,
      "letter_cost": 7500.00
    }
  ],
  "updated_at": "2024-03-03T12:00:00.000000Z"
}

POST /organisation/{organisation_id}/users/{user_id}

{
  "permissions": [
    {"permission": "can_make_services_live"}
  ]
}

{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "user_id": "b2c3d4e5-f6a7-5b8c-9d0e-1f2a3b4c5d6e",
    "organisation_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "permissions": ["can_make_services_live"]
  }
}

DELETE /organisation/{organisation_id}/users/{user_id}

{
  "result": "error",
  "message": "User not found"
}

GET /organisation/{organisation_id}/users

{
  "data": [
    {
      "id": "b2c3d4e5-f6a7-5b8c-9d0e-1f2a3b4c5d6e",
      "name": "Jane Smith",
      "email_address": "[email protected]",
      "mobile_number": "+447700900000",
      "permissions": ["can_make_services_live"]
    }
  ]
}

GET /organisation/{organisation_id}/email-branding-pool

{
  "data": [
    {
      "id": "3f5e7c9a-1b2d-4e8f-9a3c-7d6e4b2f1a8c",
      "name": "Cabinet Office",
      "colour": "#005ea5",
      "logo": "cabinet-office-logo.png",
      "alt_text": "Cabinet Office",
      "brand_type": "org"
    }
  ]
}

POST /organisation/{organisation_id}/email-branding-pool

{
  "branding_ids": [
    "3f5e7c9a-1b2d-4e8f-9a3c-7d6e4b2f1a8c",
    "4a6b8c0d-2e3f-5a7b-9c1d-8e9f0a1b2c3d"
  ]
}

DELETE /organisation/{organisation_id}/email-branding-pool/{email_branding_id}

{
  "result": "error",
  "message": "Email branding {id} not in {org}'s pool"
}

GET /organisation/{organisation_id}/letter-branding-pool

{
  "data": [
    {
      "id": "5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c",
      "name": "Cabinet Office Letterhead",
      "filename": "cabinet-office-letter-template",
      "created_at": "2024-01-10T08:30:00.000000Z"
    }
  ]
}

POST /organisation/{organisation_id}/letter-branding-pool

{
  "branding_ids": [
    "5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c",
    "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d"
  ]
}

DELETE /organisation/{organisation_id}/letter-branding-pool/{letter_branding_id}

{
  "result": "error",
  "message": "Letter branding {id} not in {org}'s pool"
}

{
  "result": "error",
  "message": "You cannot remove an organisation's default letter branding"
}

POST /organisation/notify-users-of-request-to-go-live/{service_id}

POST /organisation/notify-org-member-about-next-steps-of-go-live-request/{service_id}

{
  "to": "[email protected]",
  "service_name": "Tax Notifications",
  "body": "Please review the service configuration before approval."
}

POST /organisation/notify-service-member-of-rejected-go-live-request/{service_id}

{
  "name": "John Doe",
  "service_name": "Tax Notifications",
  "organisation_name": "HM Revenue & Customs",
  "reason": "Additional security review required before go-live.",
  "organisation_team_member_name": "Jane Smith",
  "organisation_team_member_email": "[email protected]"
}

import requests

base_url = "https://api.notifications.service.gov.uk"
headers = {"Authorization": f"Bearer {api_key}"}

# Create organisation
response = requests.post(
    f"{base_url}/organisation",
    headers=headers,
    json={
        "name": "Department for Transport",
        "crown": True,
        "organisation_type": "central"
    }
)
org = response.json()
org_id = org["id"]

# Update organisation
requests.post(
    f"{base_url}/organisation/{org_id}",
    headers=headers,
    json={
        "email_branding_id": "3f5e7c9a-1b2d-4e8f-9a3c-7d6e4b2f1a8c",
        "can_approve_own_go_live_requests": True
    }
)

# Link service to organisation
requests.post(
    f"{base_url}/organisation/{org_id}/service",
    headers=headers,
    json={"service_id": "8c9d0e1f-2a3b-4c5d-6e7f-8a9b0c1d2e3f"}
)

# Add email branding to pool
requests.post(
    f"{base_url}/organisation/{org_id}/email-branding-pool",
    headers=headers,
    json={
        "branding_ids": [
            "3f5e7c9a-1b2d-4e8f-9a3c-7d6e4b2f1a8c",
            "4a6b8c0d-2e3f-5a7b-9c1d-8e9f0a1b2c3d"
        ]
    }
)

# Get organisation services with usage
response = requests.get(
    f"{base_url}/organisation/{org_id}/services-with-usage",
    headers=headers,
    params={"year": 2024}
)
usage = response.json()
print(f"Services: {len(usage['services'])}")

# Create organisation
curl -X POST "https://api.notifications.service.gov.uk/organisation" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Department for Transport",
    "crown": true,
    "organisation_type": "central"
  }'

# Search organisations
curl "https://api.notifications.service.gov.uk/organisation/search?name=Transport" \
  -H "Authorization: Bearer $API_KEY"

# Get organisation by domain
curl "https://api.notifications.service.gov.uk/organisation/by-domain?domain=dft.gov.uk" \
  -H "Authorization: Bearer $API_KEY"

# Add user to organisation
curl -X POST "https://api.notifications.service.gov.uk/organisation/{org_id}/users/{user_id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"permissions": [{"permission": "can_make_services_live"}]}'

# Update letter branding pool
curl -X POST "https://api.notifications.service.gov.uk/organisation/{org_id}/letter-branding-pool" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "branding_ids": [
      "5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c"
    ]
  }'