📣 Guide to the Announcements API

Everee publishes announcements about changes that matter to you: API releases and deprecations, maintenance and security notices, product updates, service disruptions, bank holidays, and changes to state rules such as unemployment wage bases. The Announcements API lets you read them from code. Every announcement says who on your side should read it, whether your customers can see it as written, what to do and by when, when it applies, and which companies it concerns, in fields your code can use without parsing text.

EndpointWhat it does
List announcementsLists the announcements published for you, newest first, with filters
Get an announcementReturns one announcement with its full text

You authenticate the same way as every other endpoint. See Authentication & API tokens. Your credentials can read announcements without any extra setup. The endpoints are read-only, and they're served at /integration/v1/announcements.

Which announcements you see

Announcements are broadcasts. Everee publishes each one for an audience: partners that build Everee into their own product, or companies that use Everee directly. You never see an announcement written for the other audience, a draft, or one Everee has retracted. If Everee retracts an announcement, it disappears from the list.

What you see also depends on the credentials you call with:

  • A company's credentials see what applies to that company: announcements whose scope is ALL, and announcements scoped to states that include one of the company's states.
  • A partner API key sees every announcement for its audience, whatever its scope. To see only what applies to one of your companies, pass that company's ID in company-id. Another partner's company returns 404.

A company's states are the states in its state tax settings and its state unemployment settings, for the previous, current and next tax years.

Announcements are about changes that apply to everyone they cover, such as a state's new wage base. Events that concern only one company aren't sent as announcements.

Kinds and categories

Every announcement has a kind and a category. The kind says who on your side should read it, and the category decides the kind.

KindCategoryWhat it's aboutWritten by
INTEGRATIONAPI_RELEASEA new or changed endpoint, field, or behaviorEveree staff
INTEGRATIONDEPRECATIONSomething that is going away. details.sunsetDate says whenEveree staff
INTEGRATIONMAINTENANCEPlanned maintenance that may affect your integrationEveree staff
INTEGRATIONSECURITYA security notice that needs your attentionEveree staff
PRODUCTFEATUREA new featureEveree staff
PRODUCTDOCUMENTATIONNew or updated documentation and workflowsEveree staff
PRODUCTOFFERINGA change to Everee's products and offeringsEveree staff
OPERATIONSSERVICE_DISRUPTIONPayments, funding, or another part of Everee is delayed or unavailableEveree staff
OPERATIONSYEAR_ENDYear-end deadlines and timelines, such as the last day to approve the year's final payrollEveree staff
OPERATIONSBANK_HOLIDAYA day US banks are closed, which affects pay dates and approval deadlines. See Bank holidaysGenerated by Everee
OPERATIONSCOMPLIANCE_CHANGEA change to a law or published rate for everyone it covers. See Compliance changesGenerated by Everee

severity is INFO, IMPORTANT, or CRITICAL.

Reading an announcement

FieldMeaning
idThe announcement's ID. Use it to tell whether you've already seen one
keyA stable name for the subject, such as bank-holiday:2026-11-26 or CO-SUI-WAGE-BASE-2027. It stays the same when Everee retracts an announcement and publishes it again. Null when it has none
kind, category, severityWhat it is and how much it matters
readerPARTNER: written for you. CUSTOMER: written so you can show it to your customers as is. INTEGRATION announcements are always PARTNER
title, summaryA headline and a short description
bodyThe full text, as written. It's plain text with line breaks
scopeWhich companies it applies to. See Scope
startsAt, endsAtWhen it applies, if there are times. Either can be null
displayUntilWhen to stop showing it. Null when there is no end
actionRequiredtrue if the reader must act
actionByThe date to act by. Null when there is no date, and always null when actionRequired is false
detailsFields specific to the category. See Details by category. {} when the category has none
affectedThe endpoints, versions, or features it concerns, in the author's words
learnMoreUrlWhere the full announcement lives
publishedAtWhen Everee published it, in UTC

Timestamps are ISO 8601. actionBy is a date, such as 2027-03-01.

Details by category

Categorydetails
DEPRECATIONsunsetDate (date, always present): when the old behavior stops working. endpoints (array of strings): what is going away. replacement (string): what to use instead
MAINTENANCEaffects (array of areas): the parts of Everee the maintenance affects
SERVICE_DISRUPTIONstatus: INVESTIGATING, IDENTIFIED, MONITORING, or RESOLVED. affects (array of areas)
BANK_HOLIDAYdate (date): the holiday. name (string): its name, such as Thanksgiving Day
COMPLIANCE_CHANGEchangeKey, domain, rule, state, effectiveDate, from, to. See below
Every other category{}

Areas are API, EMBEDDED_EXPERIENCES, WEBHOOKS, PAYROLL_RUNS, FUNDING, PAYOUTS, TAX_FILING, and REPORTS.

A COMPLIANCE_CHANGE has these details:

FieldMeaning
changeKeyA stable name for the change, such as CO-SUI-WAGE-BASE-2027
domainThe area of the rule: TAX, MINIMUM_WAGE, LEAVE, OVERTIME, PAY_FREQUENCY, or OTHER. Everee may add values
ruleWhat changed, such as SUI_WAGE_BASE
stateThe two-letter state code, such as CO
effectiveDateThe date the change takes effect
from, toThe old and new values, as decimal strings such as "23800.00". from is empty when there was no previous value

Scope

scope says which companies an announcement applies to.

scope.typeApplies to
ALLEvery company in the audience
STATESCompanies with one of the states in scope.states, an array of two-letter state codes such as ["CO"]. Only OPERATIONS announcements use it
{ "type": "STATES", "states": ["CO"] }

Showing announcements to your customers

Show your customers only announcements whose reader is CUSTOMER. They're written so you can show them as is. Announcements with reader PARTNER are for you and your team.

  • Pick the right companies. Show an announcement to a company only if its scope applies to that company. If you call with a partner API key, pass company-id to get only what applies to that company.
  • Stop showing it after displayUntil. Pass active=true to leave out announcements that are past it.
  • Replace, don't duplicate. When Everee retracts an announcement and publishes it again, the new one has a new id but the same key. Show only the newest announcement for each key.

Finding what's new

Results are always newest first, by publishedAt. A sort parameter is ignored. Results are paged with page and size; size defaults to 20 and is at most 100. See Pagination.

  • kind, category, and reader narrow the list to one value.
  • key returns the announcements with that key, such as bank-holiday:2026-11-26.
  • active: true leaves out announcements past their displayUntil.
  • since returns announcements published at or after a time, in ISO 8601, such as 2026-11-01T00:00:00Z. To poll, keep the publishedAt of the newest announcement you've handled, ask for since that time, and skip any id you've already handled.
  • company-id, with a partner API key, returns only what applies to that company.

How announcements reach you

Every announcement can be read with this API by the audience it's written for. Everee also sends them as webhook events and emails, depending on how you use Everee and the kind of announcement.

KindPartners that build Everee into their productCompanies that use Everee directly
INTEGRATIONWebhook, API, email to your technical contactsWebhook, API, email to your technical contacts, or to your admins if there are none
PRODUCTWebhook, API, email to your technical contactsAPI, email to your admins
OPERATIONSWebhook, APINot sent

OPERATIONS announcements currently go only to partners that build Everee into their product. The API shows every announcement published for you, so you can use it to check what you may have missed.

Bank holidays

Everee announces each US bank holiday to partners that build Everee into their product, 1 to 14 days before it: 14 days before, unless the holiday was added or moved later than that. A bank holiday announcement has:

FieldValue
category, kindBANK_HOLIDAY, OPERATIONS
severityIMPORTANT
readerCUSTOMER
scopeALL
keybank-holiday: and the date, such as bank-holiday:2026-11-26
startsAt, endsAtThe start and end of the holiday, at midnight Mountain Time
displayUntilThe end of the holiday
detailsdate and name, such as { "date": "2026-11-26", "name": "Thanksgiving Day" }

Everee writes these announcements from its bank holiday calendar. If a holiday moves or is removed, its announcement is retracted. A holiday that moves is announced again for its new date, with a new key. Bank holiday announcements aren't emailed. To list the holidays in the next 30 days at any time, along with the pay dates they affect, see List a payroll run's pay dates.

Compliance changes

A COMPLIANCE_CHANGE announcement tells you about a change to a law or published rate, for everyone it covers. It's the same for every company it applies to. details.domain says what kind of rule it is, and details.rule names it.

State unemployment taxable wage bases

Each state sets the wages, per employee per year, that employers pay state unemployment insurance (SUI) tax on. When Everee loads a state's wage base for a tax year and it differs from the year before, it announces it to partners that build Everee into their product. The announcement has:

FieldValue
severityINFO
readerCUSTOMER
scopeSTATES, with the state, such as { "type": "STATES", "states": ["CO"] }
key and details.changeKeyThe state, SUI-WAGE-BASE and the tax year, such as CO-SUI-WAGE-BASE-2027
startsAtJanuary 1 of the tax year, at midnight Mountain Time
displayUntilThe end of January of the tax year
details.domain, details.ruleTAX, SUI_WAGE_BASE
details.stateThe two-letter state code
details.effectiveDateJanuary 1 of the tax year
details.from, details.toThe year before's wage base, and the new one. from is left out when Everee has no wage base for the year before

Everee applies the new wage base to payroll itself, so there's nothing to change. If Everee corrects a wage base, it updates the announcement in place and sends announcement.updated. If a wage base is corrected back to the year before's value, the announcement is retracted.

{
  "id": 311,
  "key": "CO-SUI-WAGE-BASE-2027",
  "kind": "OPERATIONS",
  "category": "COMPLIANCE_CHANGE",
  "severity": "INFO",
  "reader": "CUSTOMER",
  "title": "Colorado's unemployment taxable wage base rises to $30,600 for 2027",
  "summary": "From January 1, 2027, employers pay Colorado unemployment tax on up to $30,600 of each employee's wages for the year, up from $27,200.",
  "body": "From January 1, 2027, employers pay Colorado unemployment tax on up to $30,600 of each employee's wages for the year, up from $27,200.\n\nEveree applies the new wage base to payroll automatically, so there's nothing to change.",
  "scope": { "type": "STATES", "states": ["CO"] },
  "startsAt": "2027-01-01T07:00:00Z",
  "displayUntil": "2027-02-01T07:00:00Z",
  "actionRequired": false,
  "details": {
    "changeKey": "CO-SUI-WAGE-BASE-2027",
    "domain": "TAX",
    "rule": "SUI_WAGE_BASE",
    "state": "CO",
    "effectiveDate": "2027-01-01",
    "from": "27200.00",
    "to": "30600.00"
  },
  "affected": "Employer unemployment tax for Colorado workers",
  "learnMoreUrl": "https://developer.everee.com/reference/announcements-api-guide#compliance-changes",
  "publishedAt": "2026-11-20T16:00:00Z"
}

The values are made up. A field without a value can be null or left out, so treat the two the same.

Webhooks

Announcements are also sent as webhook events, so you can react without polling: announcement.published, announcement.updated when one is edited, and announcement.retracted when one is withdrawn. Which kinds you receive follows How announcements reach you. Companies that use Everee directly receive them at their own webhook endpoints. Partners that build Everee into their product receive them at their partner webhook endpoints. The events carry the announcement without its body; call Get an announcement for the full text. See Announcement Events.

Staying compatible

Everee adds to announcements over time. So that your code keeps working:

  • Ignore fields you don't know, and details keys you don't know.
  • Treat a scope.type you don't know as "may apply". With a partner API key, check by listing with company-id.
  • Treat a details.domain you don't know as OTHER.

Sandbox

Sandbox credentials can read announcements too, so you can build and test your polling against the Sandbox. Everee doesn't email announcements to Sandbox instances. See Sandbox & Production.