Zappocity platform API

Every change, with who made it

• 200 Newest first.

  {
    "items": [
      {
        "action": "provision",
        "at": "2026-10-08T12:00:00Z",
        "by": "the platform API key",
        "detail": "mailocity team year for Acme, resource 4f1c2d3e-1111-4a2b-9c3d-5e6f7a8b9c0d",
        "id": 12,
        "subject": "subscription:9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
      }
    ]
  }

• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.

How invoices, estimates and credit notes look as PDF files

• 200 The settings; logo is a data: URL, or empty.

  {
    "accent": "#2563eb",
    "address": "100 Market Street\nSan Francisco, CA 94105",
    "companyName": "Zappocity Inc.",
    "creditNoteTitle": "Credit note",
    "dateFormat": "long",
    "email": "billing@zappocity.test",
    "footer": "Thank you for your business.",
    "invoiceTitle": "Invoice",
    "logo": "data:image/png;base64,iVBORw0KGgo...",
    "paper": "a4",
    "paymentTerms": "Pay by bank transfer to account 000123456 within 14 days.",
    "phone": "",
    "quoteTerms": "",
    "quoteTitle": "Estimate",
    "taxId": "US EIN 98-7654321",
    "timeZone": "UTC",
    "updatedAt": "2026-11-06T12:00:00Z",
    "updatedBy": "amy@zappocity.test",
    "website": "zappocity.test"
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.

Change how billing documents look

{
  "accent": "#0f766e",
  "companyName": "Zappocity Inc.",
  "dateFormat": "us",
  "footer": "Thank you for your business.",
  "paper": "letter"
}

• 200 The settings.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 422 A value is out of range or names something that does not exist.

A made-up document, to see how the settings look

{
  "kind": "quote",
  "settings": {
    "accent": "#0f766e",
    "quoteTitle": "Quote"
  }
}

• 200 The PDF file, shown in the browser (Content-Disposition inline, named after its number).
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 422 A value is out of range or names something that does not exist.

What happens to unpaid invoices

• 200 The settings.

  {
    "cancelDays": 60,
    "lateFeeCents": 500,
    "lateFeeDays": 10,
    "lateFeePercent": 0,
    "overdueDays": [
      1,
      3,
      7
    ],
    "reminderDays": 3,
    "suspendDays": 14,
    "updatedAt": "2026-11-05T12:00:00Z",
    "updatedBy": "amy@zappocity.test"
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.

Change what happens to unpaid invoices

{
  "lateFeeCents": 500,
  "lateFeeDays": 10,
  "suspendDays": 14
}

• 200 The settings.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 422 A value is out of range or names something that does not exist.

Bill what is due now

• 200 How many invoices were issued, and what dunning did.

  {
    "dunning": {
      "canceled": 0,
      "lateFees": 0,
      "notices": 1,
      "reminders": 2,
      "restored": 0,
      "suspended": 1
    },
    "invoices": 3
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.

Coupons, newest first

• 200 The coupons.

  {
    "items": [
      {
        "active": true,
        "amountOffCents": null,
        "boosts": {},
        "buyCount": 1,
        "code": "WELCOME20",
        "createdAt": "2026-10-09T12:00:00Z",
        "createdBy": "owner@zappocity.test",
        "description": "20% off your first three months",
        "duration": "months",
        "durationMonths": 3,
        "expiresAt": "2027-01-01T00:00:00Z",
        "firstOrder": true,
        "freeCount": 1,
        "id": "6f1c2a9e-1b0e-4f3a-9a52-2f4d1e0c7b11",
        "kind": "percent",
        "maxRedemptions": null,
        "percentOff": 20,
        "periods": [
          "month"
        ],
        "plans": [],
        "product": "mailocity",
        "redemptions": 12,
        "signedUpAfter": null,
        "signedUpBefore": null,
        "startsAt": null,
        "updatedAt": "2026-10-09T12:00:00Z"
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.

Make a coupon

• 201 The coupon.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 409 A coupon with this code already exists.
• 422 A value is out of range or names something that does not exist.

A coupon

• 200 The coupon.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Switch a coupon off or on, or change its end or cap

{
  "active": false
}

• 200 The coupon.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 A value is out of range or names something that does not exist.

Delete a coupon nobody has redeemed

• 204 Deleted.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 Someone has redeemed it; switch it off instead.

Who redeemed a coupon

• 200 The redemptions, newest first.

  {
    "items": [
      {
        "active": true,
        "by": "pat@acme.test",
        "coupon": {
          "code": "WELCOME20"
        },
        "discountCents": 200,
        "endReason": null,
        "endedAt": null,
        "endsAt": "2027-01-09T12:00:00Z",
        "id": "0b8e5f43-2d6c-4c55-8f1e-7c9a3e2d1b00",
        "invoices": 1,
        "invoicesLeft": null,
        "orgId": "3c1d9a7e-55b2-4b8e-9e1f-0a2b3c4d5e6f",
        "orgName": "Acme",
        "redeemedAt": "2026-10-09T12:00:00Z"
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Card payments disputed with the bank (chargebacks)

• 200 The disputes.

  {
    "items": [
      {
        "amountCents": 1428,
        "closedAt": null,
        "createdAt": "2026-10-20T14:00:00Z",
        "dueBy": "2026-11-03T23:59:59Z",
        "id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
        "invoiceId": "3a4b5c6d-7e8f-4a0b-9c1d-2e3f4a5b6c7d",
        "invoiceNumber": 42,
        "orgId": "0f9e8d7c-6b5a-4c3d-2e1f-0a9b8c7d6e5f",
        "orgName": "Acme",
        "paymentRef": "pi_123",
        "provider": "stripe",
        "providerId": "dp_1Abc",
        "reason": "fraudulent",
        "reinstatedCents": 0,
        "status": "needs_response",
        "ticketId": "9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b",
        "updatedAt": "2026-10-20T14:00:00Z",
        "withdrawnCents": 1428
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.

Invoices of every organization

• 200 Newest first
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.

An invoice with its lines

• 200 The invoice.

  {
    "creditCents": 2500,
    "discountCents": 0,
    "dueAt": "2026-10-15T12:00:00Z",
    "lateFeeFor": null,
    "lines": [
      {
        "amountCents": 12000,
        "description": "mailocity team, yearly",
        "kind": "charge"
      },
      {
        "amountCents": -2500,
        "description": "Account credit",
        "kind": "credit"
      }
    ],
    "number": 7,
    "orgName": "Acme",
    "overdueNotices": 0,
    "remindedAt": "2026-10-12T12:00:00Z",
    "status": "open",
    "subtotalCents": 12000,
    "totalCents": 9500
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Record a payment made outside the payment provider

• 200 The invoice
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 The invoice is not open.
• 422 A value is out of range or names something that does not exist.

An invoice as a PDF file

• 200 The PDF file, shown in the browser (Content-Disposition inline, named after its number).
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Cancel an open invoice

• 200 The invoice
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 The invoice is not open.

The loyalty and referral program's rules

• 200 The rules.

  {
    "enabled": true,
    "inviteCostPoints": 100,
    "inviteUsedPoints": 20,
    "minRedeemPoints": 500,
    "pointValue": 100,
    "pointsPerDollar": 1,
    "referralPoints": 500,
    "signupPoints": 0,
    "updatedAt": "2026-10-09T12:00:00Z",
    "welcomePoints": 200
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.

Change the rules

{
  "enabled": true,
  "inviteCostPoints": 100,
  "referralPoints": 1000
}

• 200 The rules.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 422 A value is out of range or names something that does not exist.

Pay open invoices from credit

• 200 The invoices paid.

  {
    "items": [
      {
        "creditCents": 9500,
        "number": 7,
        "paymentMethod": "credit",
        "status": "paid",
        "totalCents": 0
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 An invoice listed is not one of the organization's open invoices.

An organization's billable items

• 200 Newest first.

  {
    "items": [
      {
        "amountCents": 5000,
        "createdBy": "jane.doe@zappo.city",
        "description": "Priority support",
        "id": "0b7f2c1e-3a4d-4e5f-8a9b-1c2d3e4f5a6b",
        "invoiceAt": "2026-12-01T00:00:00Z",
        "invoiced": 1,
        "lastInvoiceId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "orgId": "9f8e7d6c-5b4a-4321-8fed-cba987654321",
        "period": "month",
        "quantity": 1,
        "remaining": null,
        "status": "active"
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Add a billable item

{
  "amountCents": 7500,
  "description": "Mailbox migration, 3 hours",
  "invoiceNow": true,
  "quantity": 3
}

• 201 The item, and the invoice when invoiceNow issued one.

  {
    "invoice": {
      "number": 1043,
      "status": "open",
      "totalCents": 22500
    },
    "item": {
      "amountCents": 7500,
      "description": "Mailbox migration, 3 hours",
      "id": "0b7f2c1e-3a4d-4e5f-8a9b-1c2d3e4f5a6b",
      "invoiced": 1,
      "period": "once",
      "quantity": 3,
      "remaining": 0,
      "status": "done"
    }
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 A value is out of range or names something that does not exist.
• 502 Added

Change or cancel an active billable item

{
  "status": "canceled"
}

• 200 The item.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 The item is done or canceled.
• 422 A value is out of range or names something that does not exist.

Delete a billable item never invoiced

• 204 Deleted.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It has been invoiced; cancel it instead.

An organization's billing and balance

• 200 The profile.

  {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Hauptstr. 1",
      "line2": "",
      "postalCode": "10115",
      "state": ""
    },
    "autoPay": true,
    "balanceCents": 2500,
    "free": true,
    "freeReason": "Launch partner",
    "freeUntil": "2027-01-01T00:00:00Z",
    "mode": "free",
    "orgId": "0f9e8d7c-6b5a-4c3d-2e1f-0a9b8c7d6e5f",
    "taxId": {
      "type": "eu_vat",
      "value": "DE123456789"
    },
    "updatedAt": "2026-10-08T12:00:00Z"
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Make an organization free, or charged again; automatic payment

{
  "freeReason": "Launch partner",
  "freeUntil": "2027-01-01",
  "mode": "free"
}

• 200 The profile.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 A value is out of range or names something that does not exist.

An organization's coupons

• 200 The redemptions.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Redeem a code for an organization

{
  "code": "WELCOME20"
}

• 201 The redemption.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such organization or code.
• 409 Refused, with the reason: switched off, not started, expired, used up, already used by the organization, first order only, not for organizations made then, or the organization has 10 coupons in force.

Remove a coupon from an organization

• 200 The ended redemption.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It has already ended.

An organization's credit notes

• 200 The credit notes.

  {
    "items": [
      {
        "amountCents": 2500,
        "createdAt": "2026-11-05T13:20:49Z",
        "id": "3a4b5c6d-7e8f-4091-a2b3-c4d5e6f70812",
        "invoiceId": "0d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6",
        "invoiceNumber": 7,
        "kind": "credit",
        "number": 12,
        "reason": "Outage on 3 November",
        "reference": "",
        "tag": "CN-12"
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

A credit note as a PDF file

• 200 The PDF file, shown in the browser (Content-Disposition inline, named after its number).
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

An organization's invoices

• 200 Newest first.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Credit or refund part of a paid invoice

{
  "amountCents": 2500,
  "kind": "credit",
  "reason": "Outage on 3 November"
}

• 201 The credit note.

  {
    "amountCents": 2500,
    "createdAt": "2026-11-05T13:20:49Z",
    "id": "3a4b5c6d-7e8f-4091-a2b3-c4d5e6f70812",
    "invoiceId": "0d1e2f3a-4b5c-4d6e-8f70-8192a3b4c5d6",
    "invoiceNumber": 7,
    "kind": "credit",
    "number": 12,
    "reason": "Outage on 3 November",
    "reference": "",
    "tag": "CN-12"
  }

• 204 The refund was recorded; the charge had been credited already.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 The invoice is not paid, a refund of one paid by card or credit, or more than is left.
• 422 A value is out of range or names something that does not exist.

An organization's balance history

• 200 The entries.

  {
    "items": [
      {
        "amountCents": 2500,
        "at": "2026-10-08T12:00:00Z",
        "balanceCents": 2500,
        "by": "owner@zappocity.test",
        "description": "Sorry for the outage",
        "id": 3,
        "invoiceId": null,
        "kind": "credit",
        "reference": "ZC-41"
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Add credit, take it away, or record a payment or refund

{
  "amountCents": 2500,
  "description": "Sorry for the outage",
  "kind": "credit",
  "reference": "ZC-41"
}

• 201 The entry.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 A value is out of range or names something that does not exist.

An organization's quotes

• 200 Newest first.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Write a draft quote

{
  "lines": [
    {
      "description": "Mailbox migration, hours",
      "quantity": 3,
      "unitCents": 7500
    },
    {
      "description": "Priority support",
      "period": "month",
      "unitCents": 5000
    }
  ],
  "subject": "Migration and priority support",
  "validUntil": "2026-12-05"
}

• 201 The draft.

  {
    "answeredAt": null,
    "answeredBy": "",
    "declineReason": "",
    "expired": false,
    "firstCents": 27500,
    "id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
    "invoiceId": null,
    "lines": [
      {
        "description": "Mailbox migration, hours",
        "period": "once",
        "quantity": 3,
        "unitCents": 7500
      },
      {
        "description": "Priority support",
        "period": "month",
        "quantity": 1,
        "unitCents": 5000
      }
    ],
    "monthlyCents": 5000,
    "notes": "",
    "number": 1001,
    "orgId": "9f8e7d6c-5b4a-4321-8fed-cba987654321",
    "orgName": "Acme Co",
    "sentAt": null,
    "status": "draft",
    "subject": "Migration and priority support",
    "tag": "ZQ-1001",
    "validUntil": "2026-12-05T23:59:59Z",
    "yearlyCents": 0
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 A value is out of range or names something that does not exist.

A quote with its lines

• 200 The quote.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Rewrite a draft quote

{
  "lines": [
    {
      "description": "Mailbox migration, hours",
      "quantity": 3,
      "unitCents": 7500
    },
    {
      "description": "Priority support",
      "period": "month",
      "unitCents": 5000
    }
  ],
  "subject": "Migration and priority support",
  "validUntil": "2026-12-05"
}

• 200 The draft.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It is no longer a draft.
• 422 A value is out of range or names something that does not exist.

Delete a draft quote

• 204 Deleted.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It has been sent; cancel it instead.

Withdraw a sent quote

• 200 The quote
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It is not a sent quote waiting for an answer.

A quote as a PDF file (an estimate)

• 200 The PDF file, shown in the browser (Content-Disposition inline, named after its number).
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Send a draft quote

• 200 The quote
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 Not a draft

The payment provider

• 200 The settings.

  {
    "fundsEnabled": true,
    "fundsMaxBalanceCents": 500000,
    "fundsMaxCents": 100000,
    "fundsMinCents": 1000,
    "hasSecretKey": true,
    "hasWebhookSecret": true,
    "provider": "stripe",
    "taxCode": "txcd_10103001",
    "taxEnabled": true,
    "updatedAt": "2026-10-08T12:00:00Z"
  }

• 401 No valid platform API key or admin panel session.

Set the payment provider and its keys

{
  "fundsEnabled": true,
  "fundsMinCents": 2000,
  "provider": "stripe",
  "secretKey": "sk_live_xxx",
  "taxEnabled": true,
  "webhookSecret": "whsec_xxx"
}

• 200 The settings.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 422 A value is out of range or names something that does not exist.

Check the key works

• 200 Whether Stripe took the key, and why not.

  {
    "error": "stripe: Invalid API Key provided (401 )",
    "ok": false
  }

• 401 No valid platform API key or admin panel session.

A person's points and their history

• 200 The balance and entries.

  {
    "items": [
      {
        "at": "2026-10-09T12:00:00Z",
        "balance": 520,
        "by": "Zappocity loyalty",
        "description": "Referral: bob@example.com became a customer",
        "id": 7,
        "kind": "referral",
        "points": 500,
        "reference": "3c1d9a7e-55b2-4b8e-9e1f-0a2b3c4d5e6f"
      }
    ],
    "points": 520
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Give or take points by hand

{
  "description": "Thanks for the bug report",
  "points": 250
}

• 201 The entry.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It would take more points than the person has.
• 422 A value is out of range or names something that does not exist.

Quotes of every organization

• 200 Newest first, at most 500. A sent quote past validUntil has expired true.

  {
    "items": [
      {
        "answeredAt": null,
        "answeredBy": "",
        "declineReason": "",
        "expired": false,
        "firstCents": 27500,
        "id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
        "invoiceId": null,
        "lines": [
          {
            "description": "Mailbox migration, hours",
            "period": "once",
            "quantity": 3,
            "unitCents": 7500
          },
          {
            "description": "Priority support",
            "period": "month",
            "quantity": 1,
            "unitCents": 5000
          }
        ],
        "monthlyCents": 5000,
        "notes": "",
        "number": 1001,
        "orgId": "9f8e7d6c-5b4a-4321-8fed-cba987654321",
        "orgName": "Acme Co",
        "sentAt": "2026-11-05T12:00:00Z",
        "status": "sent",
        "subject": "Migration and priority support",
        "tag": "ZQ-1001",
        "validUntil": "2026-12-05T23:59:59Z",
        "yearlyCents": 0
      }
    ]
  }

• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.

A DNS account's zones

• 200 The zones.

  {
    "account": {
      "id": "1a2b3c4d-5e6f-4708-9a1b-2c3d4e5f6a7b",
      "name": "Acme",
      "plan": "personal",
      "status": "active"
    },
    "items": [
      {
        "id": "2b3c4d5e-6f70-4182-93a4-b5c6d7e8f901",
        "name": "example.com",
        "records": 2,
        "serial": 2026100901,
        "status": "active"
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 404 No such DNS account

Serve a zone

• 201 The zone.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 Not allowed (staff need the tenants permission to change zones).
• 404 No such DNS account
• 409 The zone is served already, or the plan's limit is reached.
• 422 The record or zone is not valid

A zone and its records

• 200 The zone and its records.

  {
    "dnssec": {
      "algorithm": 13,
      "ds": "24680 13 2 9A1B...",
      "dsRecord": "example.com.\t3600\tIN\tDS\t24680 13 2 9A1B...",
      "keyTag": 24680,
      "ready": true
    },
    "records": [
      {
        "data": "10 mail.example.com.",
        "id": "3c4d5e6f-7081-4293-a4b5-c6d7e8f90123",
        "name": "@",
        "ttl": 3600,
        "type": "MX"
      }
    ],
    "transfers": {
      "addresses": [],
      "key": null
    },
    "zone": {
      "accountId": "1a2b3c4d-5e6f-4708-9a1b-2c3d4e5f6a7b",
      "id": "2b3c4d5e-6f70-4182-93a4-b5c6d7e8f901",
      "name": "example.com",
      "records": 2,
      "serial": 2026100901,
      "status": "active"
    }
  }

• 401 No valid platform API key or admin panel session.
• 404 No such DNS account

Stop serving a zone

• 204 Removed.
• 401 No valid platform API key or admin panel session.
• 403 Not allowed (staff need the tenants permission to change zones).
• 404 No such DNS account
• 409 The zone is served already, or the plan's limit is reached.
• 422 The record or zone is not valid

Check the zone's delegation

• 200 The parent's answer.

  {
    "delegation": {
      "checkedAt": "2026-10-09T12:00:00Z",
      "ds": "off",
      "missing": [
        "ns2.dnso.city"
      ],
      "nameServers": [
        "ns1.dnso.city",
        "ns1.oldhost.net"
      ],
      "parent": "com",
      "status": "partly"
    },
    "expected": [
      "ns1.dnso.city",
      "ns2.dnso.city"
    ],
    "zone": "example.com"
  }

• 401 No valid platform API key or admin panel session.
• 404 No such DNS account or zone here.
• 503 Delegation is not checked by this server.

Set a secondary zone's primaries

{
  "addresses": [
    "192.0.2.53"
  ],
  "key": {
    "algorithm": "hmac-sha256",
    "name": "transfer.example.org",
    "secret": "c2VjcmV0LXNlY3JldC1zZWNyZXQtc2VjcmV0LTAxMjM="
  }
}

• 200 The zone
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 Not allowed (staff need the tenants permission to change zones).
• 404 No such DNS account or zone here.
• 409 The zone is not a secondary.
• 422 An address or the key is not valid.

Add a record

{
  "data": "10 mail.example.com.",
  "name": "@",
  "ttl": 3600,
  "type": "MX"
}

• 201 The zone and its records.

  {
    "dnssec": {
      "algorithm": 13,
      "ds": "24680 13 2 9A1B...",
      "dsRecord": "example.com.\t3600\tIN\tDS\t24680 13 2 9A1B...",
      "keyTag": 24680,
      "ready": true
    },
    "records": [
      {
        "data": "10 mail.example.com.",
        "id": "3c4d5e6f-7081-4293-a4b5-c6d7e8f90123",
        "name": "@",
        "ttl": 3600,
        "type": "MX"
      }
    ],
    "zone": {
      "accountId": "1a2b3c4d-5e6f-4708-9a1b-2c3d4e5f6a7b",
      "id": "2b3c4d5e-6f70-4182-93a4-b5c6d7e8f901",
      "name": "example.com",
      "records": 2,
      "serial": 2026100901,
      "status": "active"
    }
  }

• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 Not allowed (staff need the tenants permission to change zones).
• 404 No such DNS account
• 409 The zone is served already, or the plan's limit is reached.
• 422 The record or zone is not valid

Replace a record

{
  "data": "10 mail.example.com.",
  "name": "@",
  "ttl": 3600,
  "type": "MX"
}

• 200 The zone and its records.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 Not allowed (staff need the tenants permission to change zones).
• 404 No such DNS account
• 409 The zone is served already, or the plan's limit is reached.
• 422 The record or zone is not valid

Remove a record

• 200 The zone and its records.
• 401 No valid platform API key or admin panel session.
• 403 Not allowed (staff need the tenants permission to change zones).
• 404 No such DNS account
• 409 The zone is served already, or the plan's limit is reached.
• 422 The record or zone is not valid

Check a secondary zone now

• 200 The zone, its records and its secondary state.

  {
    "dnssec": {
      "ready": false,
      "secondary": true
    },
    "records": [
      {
        "data": "192.0.2.7",
        "name": "www",
        "ttl": 300,
        "type": "A"
      }
    ],
    "secondary": {
      "expire": 1209600,
      "keyName": "transfer.example.org.",
      "lastCheck": "2026-10-09T12:00:00Z",
      "lastError": "",
      "lastOk": "2026-10-09T12:00:00Z",
      "lastTransfer": "2026-10-09T12:00:00Z",
      "nextCheck": "2026-10-09T13:00:00Z",
      "primaries": [
        "192.0.2.53"
      ],
      "primarySerial": 7,
      "records": 3,
      "refresh": 3600,
      "retry": 600
    },
    "transfers": {
      "addresses": [],
      "key": null
    },
    "zone": {
      "id": "2b3c4d5e-6f70-4182-93a4-b5c6d7e8f901",
      "kind": "secondary",
      "name": "example.org",
      "records": 3,
      "serial": 7,
      "status": "active"
    }
  }

• 401 No valid platform API key or admin panel session.
• 403 Not allowed (staff need the tenants permission to change zones).
• 404 No such DNS account or zone here.
• 409 The zone is not a secondary.

Set the addresses the zone is transferred to

{
  "addresses": [
    "192.0.2.53",
    "2001:db8::53"
  ]
}

• 200 The zone's transfers; `key.secret` only when the key was just made.

  {
    "addresses": [
      "192.0.2.53",
      "2001:db8::53"
    ],
    "key": {
      "algorithm": "hmac-sha256",
      "createdAt": "2026-10-09T12:00:00Z",
      "name": "xfr.example.com.",
      "secret": "q2Lw...base64...="
    }
  }

• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 Not allowed (staff need the tenants permission to change zones), or the plan does not include secondary DNS.
• 404 No such DNS account or zone here.
• 422 An address is not valid, not on the internet, or there are more than 10.

Replace the zone's TSIG key

• 200 The zone's transfers with the new key's secret.

  {
    "addresses": [
      "192.0.2.53"
    ],
    "key": {
      "algorithm": "hmac-sha256",
      "createdAt": "2026-10-09T12:00:00Z",
      "name": "xfr.example.com.",
      "secret": "b7Rk...base64...="
    }
  }

• 401 No valid platform API key or admin panel session.
• 403 Not allowed (staff need the tenants permission to change zones), or the plan does not include secondary DNS.
• 404 No such DNS account or zone here.

Change customers' records that name the platform's old addresses

{
  "dryRun": true,
  "moves": [
    {
      "from": "203.0.113.17",
      "to": "198.51.100.10"
    }
  ],
  "step": "add"
}

• 200 The zones changed (or that would be), each with its changes; before "" is an added record, after "" a removed one.

  {
    "dryRun": true,
    "failed": 0,
    "records": 2,
    "step": "add",
    "zones": [
      {
        "accountId": "6f1c2e8a-3b5d-4c7e-9f10-2a3b4c5d6e7f",
        "changes": [
          {
            "after": "198.51.100.10",
            "before": "",
            "name": "www",
            "type": "A"
          },
          {
            "after": "v=spf1 ip4:203.0.113.17 ip4:198.51.100.10 -all",
            "before": "v=spf1 ip4:203.0.113.17 -all",
            "name": "@",
            "type": "TXT"
          }
        ],
        "zone": "example.com",
        "zoneId": "0c6d1f7e-2a3b-4c5d-8e9f-1a2b3c4d5e6f"
      }
    ]
  }

• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 422 A value is out of range or names something that does not exist.

dnso.city's name servers

• 200 The settings.

  {
    "hostmaster": "hostmaster@dnso.city",
    "nameServers": [
      "ns1.dnso.city",
      "ns2.dnso.city"
    ],
    "updatedAt": "2026-10-09T12:00:00Z"
  }

• 401 No valid platform API key or admin panel session.

Set dnso.city's name servers

{
  "hostmaster": "hostmaster@dnso.city",
  "nameServers": [
    "ns1.dnso.city",
    "ns2.dnso.city"
  ]
}

• 200 The settings.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 422 A value is out of range or names something that does not exist.

The platform's scheduled jobs

• 200 The jobs.

  {
    "items": [
      {
        "defaultEverySeconds": 3600,
        "description": "Invoices subscriptions that are due, charges saved payment methods and sends the invoices.",
        "enabled": true,
        "everySeconds": 3600,
        "failures": 0,
        "lastDurationMs": 2012,
        "lastError": "",
        "lastFinishedAt": "2026-10-09T17:00:02Z",
        "lastOk": true,
        "lastResult": "3 invoices made",
        "lastStartedAt": "2026-10-09T17:00:00Z",
        "lastTrigger": "schedule",
        "name": "billing",
        "nextAt": "2026-10-09T18:00:00Z",
        "running": false,
        "runs": 40,
        "title": "Billing"
      }
    ]
  }

• 401 No valid platform API key or admin panel session.

Pause, resume or reschedule a platform job

{
  "enabled": false
}

• 200 The job.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 A value is out of range or names something that does not exist.

Run a platform job now

• 200 Run here (no scheduler running); its outcome.

  {
    "durationMs": 41,
    "error": "",
    "finished": true,
    "ok": true,
    "result": "0 invoices made",
    "started": true
  }

• 202 Started.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It is running now.

How Zappocity sends its own mail

• 200 The settings. internalAvailable is false when Mailocity runs as its own service (CORPSUITE_MAILOCITY_API_URL), so mode internal is refused.

  {
    "apiUrl": "https://mailo.city",
    "fromName": "Zappocity",
    "hasApiToken": true,
    "hasSmtpPassword": false,
    "internalAvailable": true,
    "mode": "jmap",
    "smtpHost": "",
    "smtpPort": 587,
    "smtpSecurity": "starttls",
    "smtpUsername": "",
    "updatedAt": "2026-10-08T12:00:00Z"
  }

• 401 No valid platform API key or admin panel session.

Change how Zappocity sends its own mail

{
  "apiToken": "cs_mt_Yk3",
  "apiUrl": "https://mailo.city",
  "mode": "jmap"
}

• 200 The settings.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 422 A value is out of range or names something that does not exist.

Send a test message the configured way

• 200 Whether it went, and the error if not.

  {
    "ok": true
  }

• 401 No valid platform API key or admin panel session.
• 422 A value is out of range or names something that does not exist.

Find organizations

• 200 By name.

  {
    "items": [
      {
        "createdAt": "2026-10-08T12:00:00Z",
        "id": "0f9e8d7c-6b5a-4c3d-2e1f-0a9b8c7d6e5f",
        "kind": "company",
        "members": 3,
        "name": "Acme",
        "status": "active",
        "updatedAt": "2026-10-08T12:00:00Z"
      }
    ]
  }

• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.

Add an organization with its owner

{
  "name": "Acme",
  "owner": "amy@example.com"
}

• 201 The organization.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 422 A value is out of range or names something that does not exist.

An organization with its members, invitations and subscriptions

• 200 The organization.

  {
    "invitations": [
      {
        "createdAt": "2026-10-18T09:00:00Z",
        "email": "sam@example.com",
        "expiresAt": "2026-11-01T09:00:00Z",
        "id": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
        "invitedBy": "Alice",
        "orgId": "0f9e8d7c-6b5a-4c3d-2e1f-0a9b8c7d6e5f",
        "orgName": "Acme",
        "role": "member"
      }
    ],
    "members": [],
    "org": {
      "id": "0f9e8d7c-6b5a-4c3d-2e1f-0a9b8c7d6e5f",
      "kind": "company",
      "members": 1,
      "name": "Acme",
      "status": "active"
    },
    "subscriptions": []
  }

• 401 No valid platform API key or admin panel session.
• 404 No such object.

Rename, or suspend and reactivate

{
  "status": "suspended"
}

• 200 The organization.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 A value is out of range or names something that does not exist.

Withdraw an invitation to join the organization

• 204 Withdrawn.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Add a member or change their role

{
  "role": "billing"
}

• 200 The members.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

Remove a member

• 204 Removed.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.

Merge an organization recorded twice into this one

{
  "from": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"
}

• 200 The organization kept, and how many of each thing moved.

  {
    "moved": {
      "invoices": 4,
      "members": 2,
      "subscriptions": 1
    },
    "org": {
      "id": "1a2b3c4d-5e6f-4708-9a1b-2c3d4e5f6a7b",
      "name": "Acme"
    }
  }

• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 One of them is merged into another organization already.
• 422 from is missing or the same organization.
• 502 Merged, but the teams could not be moved; merge again to finish.

Badges, with the icons and colours they can have

• 200 The badges.

  {
    "colors": [
      "primary",
      "success"
    ],
    "icons": [
      "star",
      "user",
      "rocket"
    ],
    "items": [
      {
        "active": true,
        "color": "primary",
        "description": "Works at Zappocity",
        "holders": 0,
        "icon": "user",
        "id": "6f1c2a9e-1b0e-4f3a-9a52-2f4d1e0c7b11",
        "joinedBefore": null,
        "key": "staff",
        "name": "Staff",
        "plan": null,
        "product": null,
        "rule": "staff",
        "sortOrder": 20
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.

Make a badge

{
  "color": "warning",
  "description": "Reported a security bug",
  "icon": "bolt",
  "key": "bug-hunter",
  "name": "Bug hunter"
}

• 201 The badge.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 409 A badge with this key exists.
• 422 A value is out of range or names something that does not exist.

Change a badge

{
  "active": true,
  "joinedBefore": "2027-06-01"
}

• 200 The badge.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 A value is out of range or names something that does not exist.

Delete a badge (and take it from everyone)

• 204 Deleted.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Find people

• 200 By email.

  {
    "items": [
      {
        "createdAt": "2026-10-08T12:00:00Z",
        "email": "amy@example.com",
        "emailVerifiedAt": "2026-10-08T12:00:00Z",
        "hasPassword": true,
        "id": "6c1f0b7e-2d4a-4b8e-9f3c-1a2b3c4d5e6f",
        "name": "Amy",
        "status": "active",
        "updatedAt": "2026-10-08T12:00:00Z"
      }
    ]
  }

• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.

Add a person

{
  "email": "amy@example.com",
  "name": "Amy",
  "verified": true
}

• 201 The person.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

A person and the organizations they belong to

• 200 The person.

  {
    "memberships": [
      {
        "createdAt": "2026-10-08T12:00:00Z",
        "email": "amy@example.com",
        "name": "Amy",
        "orgId": "0f9e8d7c-6b5a-4c3d-2e1f-0a9b8c7d6e5f",
        "orgName": "Acme",
        "personId": "6c1f0b7e-2d4a-4b8e-9f3c-1a2b3c4d5e6f",
        "role": "owner"
      }
    ],
    "person": {
      "email": "amy@example.com",
      "hasPassword": true,
      "id": "6c1f0b7e-2d4a-4b8e-9f3c-1a2b3c4d5e6f",
      "name": "Amy",
      "status": "active",
      "timeZone": "Europe/London"
    }
  }

• 401 No valid platform API key or admin panel session.
• 404 No such object.

Change a person's name, status, password, verification or time zone

{
  "status": "suspended"
}

• 200 The person.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 A value is out of range or names something that does not exist.

Delete a Zappocity account

• 202 Scheduled; the person
• 204 Erased.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 Refused, with the reason: the only owner of an organization, or a mailbox under a legal hold or its team's last owner.

Give a badge by hand

• 204 Given (or already had).
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 The badge is given by its rule

Take a badge given by hand

• 204 Taken.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Merge a person recorded twice into this one

{
  "from": "3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f607"
}

• 200 The person kept, and how many of each thing moved.

  {
    "moved": {
      "memberships": 1,
      "points": 2,
      "tickets": 3
    },
    "person": {
      "email": "amy@example.com",
      "id": "6c1f0b7e-2d4a-4b8e-9f3c-1a2b3c4d5e6f"
    }
  }

• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 One of them is merged, deleted or to be deleted; or the other is linked to a mailbox of a team this person is not on (no mailbox there, not in the team's organization): unlink it first.
• 422 from is missing or the same person.
• 502 Merged, but the mailboxes could not be moved; merge again to finish.

A person's profile and badges

• 200 The profile and the badges they have.
• 401 No valid platform API key or admin panel session.
• 404 No such object.

Correct or hide a profile

{
  "bio": "",
  "visible": false
}

• 200 The profile and badges.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 That handle is taken.
• 422 A value is out of range or names something that does not exist.

Cancel a Zappocity account's deletion

• 200 The person.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

The product catalog

• 200 The catalog.

  {
    "currency": "USD",
    "items": [
      {
        "description": "Business email on your own domains.",
        "key": "mailocity",
        "module": true,
        "name": "Mailocity",
        "plans": [
          {
            "active": true,
            "code": "team",
            "limits": {
              "aliases": 100,
              "domains": 10,
              "messageBytes": 52428800,
              "sendPerDay": 5000,
              "sendPerHour": 500,
              "storageBytes": 32212254720,
              "users": 25
            },
            "name": "Team",
            "perSeat": false,
            "prices": {
              "month": 1200,
              "year": 12000
            }
          }
        ],
        "serviceHost": "",
        "siteHost": "mailo.city",
        "sortOrder": 10,
        "status": "available",
        "updatedAt": "2026-10-08T12:00:00Z"
      }
    ]
  }

• 401 No valid platform API key or admin panel session.

Change a product's name, description, status or site

{
  "serviceHost": "tether.example:443",
  "siteHost": "tether.example"
}

• 200 The product.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 A value is out of range or names something that does not exist.

The features a product's plans can include

• 200 The features.

  {
    "items": [
      {
        "description": "Read and send mail in the browser at /mail",
        "enforced": true,
        "key": "webmail",
        "name": "Webmail"
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 404 No such object.
• 409 This product's plans are not managed here.

Make or change a plan's limits and features

• 200 The plan
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 Refused (an unknown limit or feature

Set a plan's prices

{
  "month": 1900,
  "perSeat": true,
  "year": 19000
}

• 200 The whole catalog.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 A value is out of range or names something that does not exist.

Applications that sign in through Zappocity

• 200 The clients.

  {
    "items": [
      {
        "backchannelLogoutUri": "",
        "createdAt": "2026-10-08T12:00:00Z",
        "disabled": false,
        "id": "mailocity",
        "name": "Mailocity",
        "orgsScope": false,
        "redirectUris": [
          "https://mailo.city/api/mail/sso/callback"
        ],
        "updatedAt": "2026-10-08T12:00:00Z"
      }
    ]
  }

• 401 No valid platform API key or admin panel session.

Register an application

{
  "backchannelLogoutUri": "https://tether.example/auth/backchannel-logout",
  "id": "tether",
  "name": "Tether",
  "orgsScope": true,
  "redirectUris": [
    "https://tether.example/auth/callback"
  ]
}

• 201 The client and its secret.

  {
    "client": {
      "id": "xiht",
      "name": "xi.ht"
    },
    "secret": "cs_cs_Yk3"
  }

• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

Rename, change return addresses, or disable

{
  "backchannelLogoutUri": "https://tether.example/auth/backchannel-logout"
}

• 200 The client.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 A value is out of range or names something that does not exist.

Remove an application

• 204 Removed.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Give an application a new secret

• 200 The client and its new secret.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Incidents and maintenance

• 200 The notices, each with its updates, newest first.

  {
    "items": [
      {
        "createdAt": "2026-11-05T09:05:00Z",
        "createdBy": "ops@zappocity.test",
        "endsAt": null,
        "id": "7d1e2f3a-4b5c-4d6e-8f90-a1b2c3d4e5f6",
        "kind": "incident",
        "products": [
          "mailocity"
        ],
        "resolvedAt": null,
        "severity": "major",
        "startsAt": "2026-11-05T09:00:00Z",
        "status": "identified",
        "title": "Slow mail delivery",
        "updatedAt": "2026-11-05T09:40:00Z",
        "updates": [
          {
            "body": "A full disk on one relay; mail is queued, not lost.",
            "createdAt": "2026-11-05T09:40:00Z",
            "createdBy": "ops@zappocity.test",
            "id": 2,
            "status": "identified"
          },
          {
            "body": "Mail is arriving late.",
            "createdAt": "2026-11-05T09:05:00Z",
            "createdBy": "ops@zappocity.test",
            "id": 1,
            "status": "investigating"
          }
        ]
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.

Post an incident or maintenance

{
  "body": "Webmail may be unavailable for up to ten minutes.",
  "endsAt": "2026-11-10T03:00:00Z",
  "kind": "maintenance",
  "products": [
    "mailocity"
  ],
  "startsAt": "2026-11-10T02:00:00Z",
  "title": "Database upgrade"
}

• 201 The notice.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 422 A value is out of range or names something that does not exist.

A notice with its updates

• 200 The notice.

  {
    "createdAt": "2026-11-05T09:05:00Z",
    "createdBy": "ops@zappocity.test",
    "endsAt": null,
    "id": "7d1e2f3a-4b5c-4d6e-8f90-a1b2c3d4e5f6",
    "kind": "incident",
    "products": [
      "mailocity"
    ],
    "resolvedAt": null,
    "severity": "major",
    "startsAt": "2026-11-05T09:00:00Z",
    "status": "identified",
    "title": "Slow mail delivery",
    "updatedAt": "2026-11-05T09:40:00Z",
    "updates": [
      {
        "body": "A full disk on one relay; mail is queued, not lost.",
        "createdAt": "2026-11-05T09:40:00Z",
        "createdBy": "ops@zappocity.test",
        "id": 2,
        "status": "identified"
      },
      {
        "body": "Mail is arriving late.",
        "createdAt": "2026-11-05T09:05:00Z",
        "createdBy": "ops@zappocity.test",
        "id": 1,
        "status": "investigating"
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 404 No such object.

Change a notice

{
  "products": [
    "mailocity",
    "zappocity"
  ],
  "severity": "critical"
}

• 200 The notice.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 A value is out of range or names something that does not exist.

Remove a notice

• 204 Removed.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Post an update

{
  "body": "Delivery is back to normal; queued mail has been delivered.",
  "status": "resolved"
}

• 201 The notice.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 A value is out of range or names something that does not exist.

Subscribe an organization to a product

{
  "period": "year",
  "plan": "team",
  "product": "mailocity"
}

• 201 The subscription.

  {
    "canceledAt": null,
    "createdAt": "2026-10-08T12:00:00Z",
    "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "orgId": "0f9e8d7c-6b5a-4c3d-2e1f-0a9b8c7d6e5f",
    "orgName": "Acme",
    "period": "year",
    "plan": "team",
    "product": "mailocity",
    "resourceRef": "4f1c2d3e-1111-4a2b-9c3d-5e6f7a8b9c0d",
    "seats": 1,
    "status": "active",
    "updatedAt": "2026-10-08T12:00:00Z"
  }

• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

Find subscriptions

• 200 Newest first
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.

A subscription and what the product reports on it

• 200 The subscription, and the product's summary of its resource.

  {
    "resource": {
      "limits": {
        "users": 25
      },
      "name": "Acme",
      "plan": "team",
      "ref": "4f1c2d3e-1111-4a2b-9c3d-5e6f7a8b9c0d",
      "status": "active",
      "usage": {
        "aliases": 2,
        "domains": 1,
        "storageBytes": 1048576,
        "users": 3
      }
    },
    "subscription": {
      "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "plan": "team",
      "product": "mailocity",
      "status": "active"
    }
  }

• 401 No valid platform API key or admin panel session.
• 404 No such object.

Change the plan, period or seats, suspend, resume or cancel

{
  "seats": 5
}

• 200 The subscription.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

A subscription's features

• 200 The features.

  {
    "effective": [
      "webmail",
      "smtp_submission",
      "archiving"
    ],
    "off": [
      "imap"
    ],
    "on": [
      "archiving"
    ],
    "plan": [
      "webmail",
      "imap",
      "smtp_submission"
    ]
  }

• 401 No valid platform API key or admin panel session.
• 404 No such object.
• 409 Nothing provisioned

Switch features on or off for one subscription

{
  "off": [
    "imap"
  ],
  "on": [
    "archiving"
  ]
}

• 200 The features after the change.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 Refused (an unknown feature

The escalation rules

• 200 The rules.

  {
    "items": [
      {
        "active": true,
        "afterMinutes": 60,
        "assigned": "any",
        "id": "9b2c1d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
        "name": "Urgent waiting an hour",
        "note": "",
        "notify": [
          "lead@zappocity.test"
        ],
        "priorities": [
          "urgent"
        ],
        "queues": [],
        "reply": "",
        "setAssignee": "lead@zappocity.test",
        "setPriority": null,
        "setQueue": null,
        "setStatus": null,
        "sortOrder": 0,
        "statuses": [
          "open"
        ]
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.

Add an escalation rule

{
  "afterMinutes": 60,
  "name": "Urgent waiting an hour",
  "note": "Urgent with no answer for an hour.",
  "notify": [
    "lead@zappocity.test"
  ],
  "priorities": [
    "urgent"
  ],
  "setAssignee": "lead@zappocity.test"
}

• 201 The rule.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

Replace an escalation rule

{
  "afterMinutes": 60,
  "name": "Urgent waiting an hour",
  "note": "Urgent with no answer for an hour.",
  "notify": [
    "lead@zappocity.test"
  ],
  "priorities": [
    "urgent"
  ],
  "setAssignee": "lead@zappocity.test"
}

• 200 The rule.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

Delete an escalation rule

• 204 Deleted.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Reminders that are due

• 200 Oldest first.
• 401 No valid platform API key or admin panel session.

The help center's articles

• 200 The articles.

  {
    "items": [
      {
        "category": "billing",
        "helpful": 31,
        "id": "7e8f9a0b-1c2d-4e3f-8a9b-0c1d2e3f4a5b",
        "kind": "faq",
        "notHelpful": 2,
        "slug": "refund",
        "status": "published",
        "title": "How do I get a refund?",
        "views": 120,
        "visibility": "public"
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 404 No such object.

Write an article or FAQ

{
  "body": "Open a request under **Billing** within 30 days.",
  "category": "billing",
  "kind": "faq",
  "slug": "refund",
  "status": "published",
  "title": "How do I get a refund?",
  "visibility": "public"
}

• 201 The article.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

An article, with its body rendered

• 200 The article and its HTML: { article, html }.
• 401 No valid platform API key or admin panel session.
• 404 No such object.

Change an article

{
  "slug": "refund",
  "status": "draft",
  "title": "How do I get a refund?"
}

• 200 The article.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

Delete an article

• 204 Deleted.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

The help center's categories

• 200 The categories.

  {
    "items": [
      {
        "articles": 6,
        "description": "Invoices, cards and refunds",
        "id": "2d4f6a8c-1b3e-4c5d-9e7f-0a1b2c3d4e5f",
        "name": "Billing",
        "slug": "billing",
        "sortOrder": 0
      }
    ]
  }

• 401 No valid platform API key or admin panel session.

Add a category

{
  "description": "Invoices, cards and refunds",
  "name": "Billing",
  "slug": "billing"
}

• 201 The category.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

Change a category

{
  "name": "Billing and invoices",
  "slug": "billing",
  "sortOrder": 1
}

• 200 The category.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

Delete a category

• 204 Deleted.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Read the queues' mailboxes now

• 204 Done.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.

The help desk's front page

• 200 The queues.

  {
    "items": [
      {
        "counts": {
          "normal": 3,
          "open": 3,
          "pending": 1,
          "urgent": 1
        },
        "queue": {
          "active": true,
          "id": "3f1c2d3e-1111-4a2b-9c3d-5e6f7a8b9c0d",
          "name": "Billing",
          "slug": "billing",
          "ticketPrefix": "BIL"
        },
        "tickets": [
          {
            "customerNumber": 17,
            "number": 1042,
            "priority": "urgent",
            "requesterEmail": "amy@example.com",
            "status": "open",
            "subject": "Charged twice",
            "tag": "BIL-1042"
          }
        ]
      }
    ]
  }

• 401 No valid platform API key or admin panel session.

The support queues and their settings

• 200 The queues.

  {
    "items": [
      {
        "active": true,
        "address": "abuse@zappo.city",
        "addresses": [
          "abuse@mailo.city"
        ],
        "allowContacts": true,
        "customerClose": false,
        "defaultPriority": "normal",
        "emailIntake": true,
        "hasMailbox": true,
        "id": "3f1c2d3e-1111-4a2b-9c3d-5e6f7a8b9c0d",
        "intakeFrom": "anyone",
        "name": "Abuse",
        "public": true,
        "readInEmail": true,
        "replyByEmail": true,
        "slug": "abuse",
        "ticketPrefix": "ABU",
        "webReply": true,
        "webReplyLogin": false
      }
    ]
  }

• 401 No valid platform API key or admin panel session.

Add a queue

{
  "customerClose": false,
  "emailIntake": true,
  "intakeFrom": "anyone",
  "name": "Abuse",
  "slug": "abuse"
}

• 201 The queue.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

Change a queue's settings

{
  "webReplyLogin": true
}

• 200 The queue.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 A value is out of range or names something that does not exist.

Remove a queue

• 200 Removed.

  {
    "moved": 12
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

Let a queue take mail at another address

• 200 The queue
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

Stop a queue taking mail at one of its other addresses

• 200 The queue.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

A queue's custom ticket fields

• 200 The fields.

  {
    "items": [
      {
        "active": true,
        "help": "On your invoice, such as ZI-1042.",
        "id": "5d6e7f80-91a2-4b3c-8d4e-5f6a7b8c9d0e",
        "key": "order_number",
        "kind": "text",
        "label": "Order number",
        "options": [],
        "queueId": "2f3a4b5c-6d7e-4f80-9a1b-2c3d4e5f6a7b",
        "required": true,
        "sortOrder": 0,
        "staffOnly": false
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Ask a question when tickets are opened

{
  "help": "On your invoice, such as ZI-1042.",
  "key": "order_number",
  "kind": "text",
  "label": "Order number",
  "required": true
}

• 201 The field.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 The queue has a field with this key.
• 422 A value is out of range or names something that does not exist.

Replace a field's definition

{
  "help": "On your invoice, such as ZI-1042.",
  "key": "order_number",
  "kind": "text",
  "label": "Order number",
  "required": true
}

• 200 The field.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 The queue has another field with this key.
• 422 A value is out of range or names something that does not exist.

Remove a field

• 204 Removed.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Make the queue's mailbox, or give it a new token

• 200 The queue.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.

Customers' satisfaction ratings

• 200 The ratings.

  {
    "average": 4.33,
    "count": 3,
    "days": 30,
    "queues": [
      {
        "average": 4.33,
        "byScore": [
          0,
          0,
          1,
          0,
          2
        ],
        "count": 3,
        "queue": "billing"
      }
    ],
    "recent": [
      {
        "id": "fb9705e2-4477-4710-b10a-67f3bd68f854",
        "queue": "billing",
        "ratedAt": "2026-11-05T13:20:49Z",
        "rating": 5,
        "ratingComment": "Quick, thanks!",
        "status": "resolved",
        "subject": "Refund",
        "tag": "BIL-1042"
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 422 days is not 1 to 365.

List canned replies and macros

• 200 The replies.
• 401 No valid platform API key or admin panel session.
• 404 No such object.

Save a canned reply or macro

{
  "body": "Hi {{customer.firstName|there}},\n\nThat is fixed now. Reply to {{ticket.tag}} if it comes back.\n\n{{agent.name}}",
  "name": "Fixed, closing",
  "queue": "billing",
  "setAssignee": "me",
  "setStatus": "resolved"
}

• 201 Saved.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

Change a canned reply or macro

{
  "body": "Hi {{customer.firstName|there}}, could you send us a screenshot?",
  "name": "Waiting on you",
  "setStatus": "pending"
}

• 200 Changed.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

Delete a canned reply or macro

• 204 Deleted.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

The support team that holds the queues' mailboxes

• 200 The settings.

  {
    "domain": "zappo.city",
    "jmapUrl": "https://mailo.city",
    "teamRef": "4f1c2d3e-1111-4a2b-9c3d-5e6f7a8b9c0d",
    "updatedAt": "2026-10-08T12:00:00Z"
  }

• 401 No valid platform API key or admin panel session.

Set up the support team

{
  "domain": "zappo.city"
}

• 200 The settings.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

Add a mail domain to the support team

{
  "domain": "mailo.city"
}

• 204 Added
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

The intake spam rules

• 200 The rules.

  {
    "items": [
      {
        "createdAt": "2026-11-01T10:00:00Z",
        "createdBy": "lead@zappocity.test",
        "hits": 12,
        "id": "4c1e2d3f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
        "kind": "domain",
        "lastHitAt": "2026-11-05T09:30:00Z",
        "note": "Sends offers to every queue",
        "queueIds": [],
        "queues": [],
        "value": "bulk-mailer.example"
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.

Add an intake spam rule

{
  "kind": "domain",
  "note": "Sends offers to every queue",
  "value": "bulk-mailer.example"
}

• 201 The rule.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

Replace an intake spam rule

{
  "kind": "domain",
  "note": "Sends offers to every queue",
  "value": "bulk-mailer.example"
}

• 200 The rule.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

Remove an intake spam rule

• 204 Removed.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Find tickets

• 200 Newest first.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.

Open a ticket with a customer

• 201 The ticket.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 422 A value is out of range or names something that does not exist.

A ticket with every message, note, contact and follow-up

• 200 The ticket.

  {
    "contacts": [],
    "fields": [
      {
        "fieldId": "5d6e7f80-91a2-4b3c-8d4e-5f6a7b8c9d0e",
        "key": "order_number",
        "kind": "text",
        "label": "Order number",
        "staffOnly": false,
        "updatedAt": "2026-11-05T13:20:49Z",
        "updatedBy": "amy@example.com",
        "value": "ZI-1042"
      }
    ],
    "followUps": [],
    "messages": [
      {
        "authorKind": "customer",
        "body": "...",
        "internal": false
      }
    ],
    "ticket": {
      "number": 41,
      "prefix": "ABU",
      "status": "open",
      "subject": "Spam from your IP",
      "tag": "ABU-41"
    }
  }

• 401 No valid platform API key or admin panel session.
• 404 No such object.

Change status, priority, assignee or queue

• 200 The ticket.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 A value is out of range or names something that does not exist.

Add someone to the replies

• 200 The contacts.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 It already exists, the product refused the change, the resource belongs to another subscription, or an organization would lose its last owner.
• 422 A value is out of range or names something that does not exist.

Take someone off the replies

• 204 Removed.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Schedule a follow-up

{
  "body": "Check the customer's DNS is fixed",
  "dueAt": "2026-10-15T09:00:00Z",
  "kind": "reminder"
}

• 201 The follow-up.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 422 A value is out of range or names something that does not exist.

Mark a follow-up done, or not

• 204 Changed.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Merge tickets into this one

{
  "tickets": [
    "SUP-12",
    "1043"
  ]
}

• 200 This ticket, after the merges.

  {
    "id": "fb9705e2-4477-4710-b10a-67f3bd68f854",
    "mergedInto": null,
    "status": "open",
    "subject": "Can't sign in",
    "tag": "SUP-11"
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 Another requester's ticket
• 422 No such ticket

Reply, or add an internal note

• 201 The message.
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 Someone else wrote since afterMessage (newer lists it); send again with force, or after reading it.
• 422 A value is out of range or names something that does not exist.

Say you have the ticket open; see who else has

• 200 The others on the ticket.

  {
    "items": [
      {
        "replying": true,
        "seenAt": "2026-11-05T13:21:04Z",
        "since": "2026-11-05T13:20:49Z",
        "who": "lead@zappocity.test"
      }
    ]
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Say you closed the ticket

• 204 Gone.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.

Fill in a canned reply for a ticket

• 200 The reply and its text for this ticket.

  {
    "body": "Hi Ana,\n\nThat is fixed now. Reply to ZC-1042 if it comes back.\n\nJane Doe"
  }

• 401 No valid platform API key or admin panel session.
• 404 No such object.
• 409 The reply is for another queue.

Use a canned reply or macro on a ticket

{}

• 200 The ticket as it is now, and the message sent (null when there was no body).
• 400 The body is not JSON with only the documented fields, or a query parameter is out of range.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 The reply is for another queue.
• 422 A value is out of range or names something that does not exist.

Delete a reply's secure data

• 204 Deleted.
• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 410 Already deleted.

Show a reply's secure data

• 200 The data.

  {
    "data": "c0rrect-h0rse",
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 410 Deleted (by staff

Split messages into a new ticket

{
  "messages": [
    4211,
    4215
  ],
  "subject": "Invoice address"
}

• 201 The new ticket.

  {
    "id": "0c5b6f7e-2a41-4f3c-9d8e-1b2a3c4d5e6f",
    "status": "open",
    "subject": "Invoice address",
    "tag": "SUP-1044"
  }

• 401 No valid platform API key or admin panel session.
• 403 The staff account lacks the permission, or the caller is a team.
• 404 No such object.
• 409 Every message would move
• 422 A message that is not this ticket's