Update Organization
Updates the organization from your authenticated session.
PATCH /api/organization
Request Body
{
"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",
"contractEmail": "contracts@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)
BASE_URL="https://uptimeify.io"
TOKEN="<your-api-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/:organizationPublicIdremains supported for compatibility. -
The plural org-less alias
PATCH /api/organizationsis also supported. -
Global admins need an active organization context in the authenticated session for the org-less route.
-
contractEmail(e-mail address ornull) receives notices of changes to the terms, the DPA and the privacy policy. When it is set, only this address receives them and no admin does;nullsends them to every admin of the organization again. -
countryCodeis 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
vatIdorcountryCode(either one, in the same request or separately) resetsvatIdStatustounverified. A previousvalidverdict never survives an edit to either field, re-validate with Validate VAT ID after the change to restore reverse-charge eligibility. -
Quota changes are not symmetric. A change whose
quotaMonthlyPriceCentsis 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: by default it is scheduled for the end of the current billing period, and no credit is issued for the unused part of the higher plan (seequotaChangeEffectivebelow to apply it immediately instead). This applies from 1 January 2027; until 31 December 2026 a reduction on a monthly plan takes effect immediately with a pro-rata credit by default. 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
pendingQuotaChangeon both this endpoint and Get Organization Details; it isnullwhen 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, re-sending the current tier here counts as unchanged and will not do it. -
Per-day billing from billing month January 2027. Every calendar day in Europe/Berlin costs the monthly price of the plan in effect on that day, divided by the number of days in that month (28 to 31); a full month costs exactly the monthly price. A plan change applies from 00:00 Europe/Berlin on the day it is made, so the day of the change is billed at the new plan, and of several changes on one day the last one counts for the whole day. Consecutive days on the same plan appear as one invoice line. Billing months up to December 2026 are still prorated to the millisecond in UTC months. Charges are still collected in arrears with the next monthly invoice.
-
quotaChangeEffective(optional,"immediately"or"period_end") only applies to a reduction and is never stored."period_end"schedules the reduction as described above."immediately"applies it right away: the quota fields change now, any scheduled reduction is closed, and the rest of the month is billed at the new plan (from 1 January 2027 per day from 00:00 Europe/Berlin today, until then pro rata to the millisecond from the moment of the change). Not available for yearly billing (400 quotaChangeImmediateNotSupported). The default depends on the date. From 1 January 2027 it is"period_end"and both values can be chosen. Until 31 December 2026 (terms version 1.0) a reduction on a monthly plan takes effect immediately with a pro-rata credit: the default is"immediately", and"period_end"is rejected with400 quotaChangePeriodEndNotYetAvailable. Yearly plans keep"period_end"as the default throughout. The usage check below applies to both. -
quotaAutoUpgradeEnabled(boolean, off by default) lets the organization move up one plan tier automatically when its quota is full, instead of rejecting the next monitor; the higher tier is billed per day from the day of the upgrade. An organization admin may set it, but only from a real, logged-in user session: with an API token or agent access token the request is rejected with403 nonUserSessionForbidden, because switching it on consents to future paid upgrades. -
smsOverageSafetyCapCentsMonthly(integer cents ornullfor no cap) is the monthly limit for extra SMS. An organization admin sets it freely from0up tosmsOverageSafetyCapMaxCentsMonthly(raise and lower). While no upper bound is set, they may only lower it to a value up to the stored cap, or set one while none is stored. Values above the upper bound and removing the cap (null) are reserved for platform admins and answer403 smsCapRaiseForbiddenwith the effective upper bound indata.maxCents. -
smsOverageSafetyCapMaxCentsMonthly(integer cents ornull) is that upper bound per organization. Only platform admins may set it (403 forbiddenotherwise);nullmeans no upper bound, so the organization admin can only lower the cap. -
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,requireMfaReadonlyandrequireMfaCustomers(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 aneditor/readonlymember with no explicit customer assignments (no rows inuser_customer_access). - Customer user: an
editororreadonlymember scoped to one or more specific customers (at least one row inuser_customer_access), regardless of role.
requireMfaAdmins,requireMfaEditorsandrequireMfaReadonlycover TEAM members only, an editor or readonly member who is scoped to specific customers is not covered byrequireMfaEditors/requireMfaReadonly, even when that switch is on.requireMfaCustomerscovers every customer user instead, whatever their role. An admin is never customer-scoped (admins always have unrestricted access), sorequireMfaCustomersnever applies to one,requireMfaAdminsis 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, on by default since 4 September 2026) 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 ofrequireMfaAdmins,requireMfaEditors,requireMfaReadonlyorrequireMfaCustomersis rejected with403 nonUserSessionForbiddenwhen 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. - Team member: an
-
Changing any of the four fields, in either direction (on or off), is rejected with
400 mfaRequiredForActorunless 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 bodywhen the payload does not match the schema400 Organization ID is required in the authenticated sessionwhen no organization can be derived from the current session/token400 mfaRequiredForActorwhen settingrequireMfaAdmins,requireMfaEditors,requireMfaReadonlyorrequireMfaCustomers(any of them, eithertrueorfalse) while the caller's own account does not have two-step verification enabled400 quotaChangeImmediateNotSupportedwhenquotaChangeEffectiveis"immediately"for a reduction on an organization with yearly billing400 quotaChangePeriodEndNotYetAvailablewhenquotaChangeEffectiveis"period_end"for a reduction on a monthly plan before 1 January 2027 (until then a reduction takes effect immediately with a pro-rata credit)403 nonUserSessionForbiddenwhen the request body includesrequireMfaAdmins,requireMfaEditors,requireMfaReadonly,requireMfaCustomersorquotaAutoUpgradeEnabledand the caller is an API token or agent access token rather than a real user session403 smsCapRaiseForbiddenwhen an organization admin setssmsOverageSafetyCapCentsMonthlyabove the effective upper bound or removes it (data.maxCentsissmsOverageSafetyCapMaxCentsMonthlyif set, otherwise the stored cap)401 Unauthorizedwhen you are not logged in403 Forbiddenwhen 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:
{
"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: for a monthly cycle the 1st of the next month at 00:00 Europe/Berlin (2027-01-31T23:00:00.000Z for 1 February 2027; reductions scheduled up to December 2026 still use 00:00 UTC, e.g. 2027-01-01T00:00:00.000Z), for a yearly one the end of the paid term.
See Error Codes for error responses.
Update Billing Details
Updates billing information for the organization in your authenticated session.
Cancel Scheduled Quota Change
Cancels a quota reduction that was scheduled for the end of the current billing period, so the organization keeps its current plan. Answers cancelled:false, not 404, when nothing is scheduled.