--- title: "Update Organization" description: "Updates the organization from your authenticated session." --- `PATCH /api/organization` ## Request Body ```json { "name": "New Name", "companyName": "New Company Name", "street": "New Street", "postalCode": "54321", "city": "New City", "country": "US", "vatId": "US123", "countryCode": "AT", "billingEmail": "new@deinkunde.com", "requireMfaAdmins": true, "requireMfaEditors": false, "requireMfaReadonly": false, "requireMfaCustomers": false, "defaultNotificationChannels": { "email": true, "sms": false, "webhook": true, "integrations": false }, "defaultNotificationTargets": { "email": "both", // customer, organization, both "sms": "organization", "webhook": "organization", "integrations": "customer" } } ``` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PATCH "$BASE_URL/api/organization" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "name": "New Name", "billingEmail": "new@deinkunde.com" }' ``` Notes: - The organization is derived automatically from your authenticated session or API token. - The legacy route `PATCH /api/organizations/:organizationPublicId` remains supported for compatibility. - The plural org-less alias `PATCH /api/organizations` is also supported. - Global admins need an active organization context in the authenticated session for the org-less route. - `countryCode` is the organization's billing country as an ISO-3166-1 alpha-2 code (two letters, case-insensitive on input, always stored and returned uppercased). It determines VAT treatment: reverse charge under AGB § 10.2 requires this to be an EU member state other than Germany. - Writing `vatId` or `countryCode` (either one, in the same request or separately) resets `vatIdStatus` to `unverified`. A previous `valid` verdict never survives an edit to either field, re-validate with [Validate VAT ID](/api/organization/validate-vat-id) after the change to restore reverse-charge eligibility. - **Quota changes are not symmetric.** A change whose `quotaMonthlyPriceCents` is **higher** than the organization's current one takes effect immediately, and the difference is charged pro rata for the rest of the current billing period. A change whose price is **lower** does **not** take effect immediately: under AGB § 10.5 it is scheduled for the end of the current billing period, and no credit is issued for the unused part of the higher plan. Until it fires, the organization keeps its current plan and every quota field on the organization still describes that plan. Direction is decided by price alone, never by the monitor limit, so a tier that costs less for *more* monitors is still a reduction. - A scheduled reduction is returned as `pendingQuotaChange` on both this endpoint and [Get Organization Details](/api/organization/get-organization-details); it is `null` when nothing is scheduled. There is at most one scheduled change per organization: a second reduction replaces the first, and an increase supersedes it (otherwise you would be silently dropped back at the period boundary). To call one off without changing plan, use [Cancel Scheduled Quota Change](/api/organization/cancel-pending-quota-change), re-sending the current tier here counts as unchanged and will not do it. - A reduction below the organization's current monitor usage is rejected up front with `400`. The same check runs again when the change is applied: if the organization has grown past the new limit in the meantime, the reduction is abandoned rather than applied, and the organization keeps the higher plan. - `requireMfaAdmins`, `requireMfaEditors`, `requireMfaReadonly` and `requireMfaCustomers` (all boolean) independently force two-step verification for four different audiences, set any subset of the four to roll MFA out incrementally. **A user's audience is not simply their role.** Every user in the organization is either a **team member** or a **customer user**: - **Team member**: an `admin`, or an `editor`/`readonly` member with no explicit customer assignments (no rows in `user_customer_access`). - **Customer user**: an `editor` or `readonly` member scoped to one or more specific customers (at least one row in `user_customer_access`), regardless of role. `requireMfaAdmins`, `requireMfaEditors` and `requireMfaReadonly` cover TEAM members only, an editor or readonly member who is scoped to specific customers is **not** covered by `requireMfaEditors`/`requireMfaReadonly`, even when that switch is on. `requireMfaCustomers` covers every customer user instead, whatever their role. An admin is never customer-scoped (admins always have unrestricted access), so `requireMfaCustomers` never applies to one, `requireMfaAdmins` is the only switch that can ever force MFA on an admin. Platform-wide enforcement for platform admins/supporters is a separate, operator-only environment flag (`MFA_ENFORCE_PLATFORM_ADMINS`, default off) and is not affected by these fields. Any of the four can be set by an organization admin, not just a global admin, but only from a real, logged-in user session. A request whose body includes any of `requireMfaAdmins`, `requireMfaEditors`, `requireMfaReadonly` or `requireMfaCustomers` is rejected with `403 nonUserSessionForbidden` when called with an API token or agent access token, even an organization-scoped one with admin-level access, otherwise a leaked token could dismantle the organization's MFA posture on its own. - Changing **any** of the four fields, in **either direction** (on or off), is rejected with `400 mfaRequiredForActor` unless the acting admin already has two-step verification enabled on their own account. Turning one on with no factor of your own would immediately lock you out of your own organization on the next request (if the switch covers your own audience); turning one off is gated the same way so a forced-but-unenrolled admin cannot use these fields to escape their own organization's MFA requirement. ## Common errors - `400 Invalid request body` when the payload does not match the schema - `400 Organization ID is required in the authenticated session` when no organization can be derived from the current session/token - `400 mfaRequiredForActor` when setting `requireMfaAdmins`, `requireMfaEditors`, `requireMfaReadonly` or `requireMfaCustomers` (any of them, either `true` or `false`) while the caller's own account does not have two-step verification enabled - `403 nonUserSessionForbidden` when the request body includes `requireMfaAdmins`, `requireMfaEditors`, `requireMfaReadonly` or `requireMfaCustomers` and the caller is an API token or agent access token rather than a real user session - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you do not have admin access to update the organization ## Response Returns the updated organization object, plus `pendingQuotaChange` describing a reduction that was scheduled by this request: ```json { "pendingQuotaChange": { "effectiveAt": "2026-08-01T00:00:00.000Z", "quotaWebsitesLimit": 25, "quotaMonthlyPriceCents": 6900 } } ``` `pendingQuotaChange` is `null` when the request scheduled nothing, including when it applied an increase immediately. `effectiveAt` is the first instant at which the new plan applies: the next UTC month start for a monthly cycle, the end of the paid term for a yearly one. See [Error Codes](/api/error-codes-and-known-pitfalls) for error responses.