Skip to Content
Uptimeify Docs
Organization

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/: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.

  • contractEmail (e-mail address or null) 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; null sends them to every admin of the organization again.

  • 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 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: 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 (see quotaChangeEffective below 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 pendingQuotaChange on both this endpoint and 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, 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 with 400 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 with 403 nonUserSessionForbidden, because switching it on consents to future paid upgrades.

  • smsOverageSafetyCapCentsMonthly (integer cents or null for no cap) is the monthly limit for extra SMS. An organization admin sets it freely from 0 up to smsOverageSafetyCapMaxCentsMonthly (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 answer 403 smsCapRaiseForbidden with the effective upper bound in data.maxCents.

  • smsOverageSafetyCapMaxCentsMonthly (integer cents or null) is that upper bound per organization. Only platform admins may set it (403 forbidden otherwise); null means 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, 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, 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 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
  • 400 quotaChangeImmediateNotSupported when quotaChangeEffective is "immediately" for a reduction on an organization with yearly billing
  • 400 quotaChangePeriodEndNotYetAvailable when quotaChangeEffective is "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 nonUserSessionForbidden when the request body includes requireMfaAdmins, requireMfaEditors, requireMfaReadonly, requireMfaCustomers or quotaAutoUpgradeEnabled and the caller is an API token or agent access token rather than a real user session
  • 403 smsCapRaiseForbidden when an organization admin sets smsOverageSafetyCapCentsMonthly above the effective upper bound or removes it (data.maxCents is smsOverageSafetyCapMaxCentsMonthly if set, otherwise the stored cap)
  • 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:

{
  "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.

On this page