> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpalm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook example payloads

> A complete, realistic example payload for every Palm webhook event type.

A concrete payload for every webhook event Palm delivers. Every payload shares the same envelope — `id`, `object: "event"`, `type`, `created_at`, and an event-specific `data` object. For the concepts (setup, signing, retries, idempotency), see the [Webhooks overview](/developer-guide/webhooks).

## Verification events

### user.verification.completed

*Fires when a user verification finishes.* This example is a flagged applicant (`risk.level: high`), so `risk.reasons`, mismatched `match` values, and a watchlist hit are all populated. On a clean pass, `reasons` and `matches` are empty and `match` values are all `match`.

```json wrap JSON theme={null}
{
  "id": "evt_1718296200000_f6g7h8i9j0k1",
  "object": "event",
  "type": "user.verification.completed",
  "mode": "live",
  "created_at": "2026-06-13T16:30:00Z",
  "data": {
    "object": {
      "user_id": "a1d4f9c2-8b3e-4e6a-9c1d-7f2b5a8e0c43",
      "verification_id": "c7e2b9a4-1f6d-4a3c-8e9b-2d5f0a7c4b16",
      "reference_id": "your_user_ref_5573",
      "status": "completed",
      "risk": {
        "level": "high",
        "reasons": [
          "Address mismatch detected",
          "High velocity on phone number (5 applications in 24 hours)",
          "Synthetic identity indicators detected with 72% confidence",
          "Potential PEP match on Dow Jones watchlist"
        ]
      },
      "match": {
        "first_name": "match",
        "last_name": "match",
        "middle_name": "not_checked",
        "date_of_birth": "match",
        "ssn": "partial_match",
        "email": "match",
        "phone_number": "match",
        "address_line_1": "no_match",
        "address_line_2": "not_checked",
        "city": "no_match",
        "region": "match",
        "postal_code": "no_match"
      },
      "synthetic": {
        "is_synthetic": true,
        "confidence_score": 72,
        "indicators": [
          "SSN issued after applicant date of birth",
          "Credit file recently established"
        ]
      },
      "velocity": {
        "email": 1,
        "phone": 5,
        "ssn": 2,
        "address": 3
      },
      "device": {
        "risk_score": 68,
        "is_emulator": false,
        "is_vpn": true,
        "is_proxy": false
      },
      "watchlist": {
        "status": "potential_match",
        "matches": [
          { "type": "pep", "name": "dow_jones_pep", "confidence_score": 63 }
        ]
      },
      "created_at": "2026-06-13T16:28:42Z",
      "updated_at": "2026-06-13T16:30:00Z"
    }
  }
}
```

### business.verification.completed

*Fires when a business verification finishes.* Includes the full user-verification result for each associate. This example is a critical-risk outcome: the EIN does not match IRS records, the business is no longer in good standing, and an associate failed verification.

```json wrap JSON theme={null}
{
  "id": "evt_1718296500000_a1b2c3d4e5f6",
  "object": "event",
  "type": "business.verification.completed",
  "mode": "live",
  "created_at": "2026-06-13T16:35:00Z",
  "data": {
    "object": {
      "business_id": "e4b9c1a7-3d2f-4a8e-9b6c-1f0d5a7e2c83",
      "verification_id": "f2a7d4e9-6b1c-4f3a-8d5e-9c0b3a6f1d27",
      "reference_id": "your_business_ref_3391",
      "status": "completed",
      "risk": {
        "level": "critical",
        "reasons": [
          "EIN does not match IRS records for the provided legal name",
          "Business is not in good standing: status is dissolved in the formation jurisdiction (Delaware)"
        ]
      },
      "match": {
        "legal_name": "match",
        "ein": "no_match",
        "entity_type": "match",
        "registration_jurisdiction": "match",
        "formation_jurisdiction": "match",
        "formation_date": "match",
        "address_line_1": "match",
        "address_line_2": "not_checked",
        "city": "match",
        "region": "match",
        "postal_code": "match"
      },
      "associates": [
        {
          "user_id": "b8c3e6f1-9a2d-4c7e-8b5f-3a1d6e9c0f24",
          "verification_id": "d1f4a7c2-5e8b-4a9d-9c3e-6f2b0a5d8e13",
          "reference_id": "owner_1",
          "status": "completed",
          "risk": {
            "level": "high",
            "reasons": [
              "SSN does not match the provided name",
              "Identity could not be verified against authoritative records"
            ]
          },
          "match": {
            "first_name": "match",
            "last_name": "match",
            "middle_name": "not_checked",
            "date_of_birth": "no_match",
            "ssn": "no_match",
            "email": "match",
            "phone_number": "match",
            "address_line_1": "no_match",
            "address_line_2": "not_checked",
            "city": "match",
            "region": "match",
            "postal_code": "no_match"
          },
          "watchlist": {
            "status": "potential_match",
            "matches": [
              { "type": "adverse_media", "name": "complyadvantage_media", "confidence_score": 57 }
            ]
          }
        }
      ]
    }
  }
}
```

## Monitoring events

### business.registration.updated

*Fires when Palm detects a change to a monitored business in the authoritative record.* `data.business` is a lightweight reference; `data.changes` carries one entry per field that moved. Values mirror the source record (typically uppercase).

```json wrap JSON theme={null}
{
  "id": "evt_1718447400000_h8i9j0k1l2m3",
  "object": "event",
  "type": "business.registration.updated",
  "mode": "live",
  "created_at": "2026-06-15T10:30:00Z",
  "data": {
    "business": {
      "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "palm_id": "A1B2-C3D4-E5F6",
      "legal_name": "ACME HOLDINGS LLC",
      "registration_jurisdiction_id": "US-NC"
    },
    "changes": [
      {
        "attribute": "address.principal",
        "action": "updated",
        "summary": "Principal address changed from 150 FAYETTEVILLE ST, RALEIGH, NC to 401 S TRYON ST, CHARLOTTE, NC",
        "previous_value": {
          "street_line_1": "150 FAYETTEVILLE ST",
          "street_line_2": "SUITE 1100",
          "city": "RALEIGH",
          "region": "NC",
          "postal_code": "27601",
          "country": "US"
        },
        "current_value": {
          "street_line_1": "401 S TRYON ST",
          "street_line_2": "SUITE 2200",
          "city": "CHARLOTTE",
          "region": "NC",
          "postal_code": "28202",
          "country": "US"
        }
      },
      {
        "attribute": "name.dba",
        "action": "added",
        "summary": "Assumed business name added: ACME LOGISTICS",
        "previous_value": null,
        "current_value": "ACME LOGISTICS"
      }
    ]
  }
}
```

### business.filing.due

*Fires when a compliance filing deadline is approaching.*

```json wrap JSON theme={null}
{
  "id": "evt_1740571200000_l2m3n4o5p6q7",
  "object": "event",
  "type": "business.filing.due",
  "mode": "live",
  "created_at": "2026-02-26T12:00:00Z",
  "data": {
    "object": {
      "type": {
        "id": "annual_report",
        "name": "Annual Report"
      },
      "frequency": "annual",
      "due_date": "2026-04-15"
    },
    "business": {
      "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "palm_id": "A1B2-C3D4-E5F6",
      "legal_name": "ACME HOLDINGS LLC",
      "registration_jurisdiction_id": "US-NC"
    }
  }
}
```

### business.filing.overdue

*Fires when a compliance filing deadline has passed.* Identical structure to `business.filing.due`; only the event `type` differs.

```json wrap JSON theme={null}
{
  "id": "evt_1744761600000_m3n4o5p6q7r8",
  "object": "event",
  "type": "business.filing.overdue",
  "mode": "live",
  "created_at": "2026-04-16T12:00:00Z",
  "data": {
    "object": {
      "type": {
        "id": "annual_report",
        "name": "Annual Report"
      },
      "frequency": "annual",
      "due_date": "2026-04-15"
    },
    "business": {
      "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "palm_id": "A1B2-C3D4-E5F6",
      "legal_name": "ACME HOLDINGS LLC",
      "registration_jurisdiction_id": "US-NC"
    }
  }
}
```

## Filing events

All `filing.*` events carry the same `filing` object on `data.object`. Across the lifecycle only `status` changes; `result`, `documents`, and `fee` populate on completion. Route on `data.object.type` (`formation`, `ein`). A formation bundles its obligations under `related_items` — each with its own `object`, `id`, and `status`. The registered agent is one such item and is **not** a filing: it never emits `filing.*` events, only its own `registered_agent.*` events (see below).

### filing.queued

*Fires when a filing is received and validated (preparing for submission).* `result` and `fee` are `null` and no documents exist yet.

```json wrap JSON theme={null}
{
  "id": "evt_1718269200000_a1b2c3d4e5f6",
  "object": "event",
  "type": "filing.queued",
  "mode": "live",
  "created_at": "2026-06-13T09:15:00Z",
  "data": {
    "object": {
      "id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e",
      "object": "filing",
      "type": "formation",
      "status": "queued",
      "entity_type": "llc",
      "jurisdiction": "US-NC",
      "name": "Acme Holdings LLC",
      "expedited_tier": "same_day",
      "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "result": null,
      "parent_filing_id": null,
      "related_items": [
        { "object": "filing", "id": "5a1d8f9b-2e4c-4d7a-8b3f-6c9e0a1d2b4f", "type": "ein", "status": "queued" },
        { "object": "registered_agent", "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "status": "pending" }
      ],
      "documents": [],
"fee": null,
      "status_reason": null,
      "canceled_by": null,
      "canceled_at": null,
      "cases": [],
      "metadata": {},
      "created_at": "2026-06-13T09:15:00Z",
      "updated_at": "2026-06-13T09:15:00Z"
    }
  }
}
```

### filing.ready\_to\_file

*Fires when Palm is ready to submit the filing to the authority.*

```json wrap JSON theme={null}
{
  "id": "evt_1718290800000_b2c3d4e5f6a7",
  "object": "event",
  "type": "filing.ready_to_file",
  "mode": "live",
  "created_at": "2026-06-13T15:00:00Z",
  "data": {
    "object": {
      "id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e",
      "object": "filing",
      "type": "formation",
      "status": "ready_to_file",
      "entity_type": "llc",
      "jurisdiction": "US-NC",
      "name": "Acme Holdings LLC",
      "expedited_tier": "same_day",
      "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "result": null,
      "parent_filing_id": null,
      "related_items": [
        { "object": "filing", "id": "5a1d8f9b-2e4c-4d7a-8b3f-6c9e0a1d2b4f", "type": "ein", "status": "queued" },
        { "object": "registered_agent", "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "status": "pending" }
      ],
      "documents": [],
"fee": null,
      "status_reason": null,
      "canceled_by": null,
      "canceled_at": null,
      "cases": [],
      "metadata": {},
      "created_at": "2026-06-13T09:15:00Z",
      "updated_at": "2026-06-13T15:00:00Z"
    }
  }
}
```

### filing.processing

*Fires when Palm has submitted the filing and the authority is processing it.*

```json wrap JSON theme={null}
{
  "id": "evt_1718369940000_c3d4e5f6a7b8",
  "object": "event",
  "type": "filing.processing",
  "mode": "live",
  "created_at": "2026-06-14T13:00:00Z",
  "data": {
    "object": {
      "id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e",
      "object": "filing",
      "type": "formation",
      "status": "processing",
      "entity_type": "llc",
      "jurisdiction": "US-NC",
      "name": "Acme Holdings LLC",
      "expedited_tier": "same_day",
      "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "result": null,
      "parent_filing_id": null,
      "related_items": [
        { "object": "filing", "id": "5a1d8f9b-2e4c-4d7a-8b3f-6c9e0a1d2b4f", "type": "ein", "status": "queued" },
        { "object": "registered_agent", "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "status": "pending" }
      ],
      "documents": [],
"fee": null,
      "status_reason": null,
      "canceled_by": null,
      "canceled_at": null,
      "cases": [],
      "metadata": {},
      "created_at": "2026-06-13T09:15:00Z",
      "updated_at": "2026-06-14T13:00:00Z"
    }
  }
}
```

### filing.filed

*Fires when the authority has accepted the filing; final confirmation is pending.*

```json wrap JSON theme={null}
{
  "id": "evt_1718373600000_d4e5f6a7b8c9",
  "object": "event",
  "type": "filing.filed",
  "mode": "live",
  "created_at": "2026-06-14T14:00:00Z",
  "data": {
    "object": {
      "id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e",
      "object": "filing",
      "type": "formation",
      "status": "filed",
      "entity_type": "llc",
      "jurisdiction": "US-NC",
      "name": "Acme Holdings LLC",
      "expedited_tier": "same_day",
      "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "result": null,
      "parent_filing_id": null,
      "related_items": [
        { "object": "filing", "id": "5a1d8f9b-2e4c-4d7a-8b3f-6c9e0a1d2b4f", "type": "ein", "status": "queued" },
        { "object": "registered_agent", "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "status": "pending" }
      ],
      "documents": [],
"fee": null,
      "status_reason": null,
      "canceled_by": null,
      "canceled_at": null,
      "cases": [],
      "metadata": {},
      "created_at": "2026-06-13T09:15:00Z",
      "updated_at": "2026-06-14T14:00:00Z"
    }
  }
}
```

### filing.completed (formation)

*Fires when the filing is done and the result is available.* For a formation, `result` holds the registration number and formation date, the certificate appears under `documents`, and `fee` carries the finalized breakdown (including `total`).

```json wrap JSON theme={null}
{
  "id": "evt_1718372400000_n4o5p6q7r8s9",
  "object": "event",
  "type": "filing.completed",
  "mode": "live",
  "created_at": "2026-06-14T14:30:00Z",
  "data": {
    "object": {
      "id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e",
      "object": "filing",
      "type": "formation",
      "status": "completed",
      "entity_type": "llc",
      "jurisdiction": "US-NC",
      "name": "Acme Holdings LLC",
      "expedited_tier": "same_day",
      "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "result": {
        "registration_number": "NC-12345678",
        "formation_date": "2026-06-14"
      },
      "parent_filing_id": null,
      "related_items": [
        { "object": "filing", "id": "5a1d8f9b-2e4c-4d7a-8b3f-6c9e0a1d2b4f", "type": "ein", "status": "ready_to_file" },
        { "object": "registered_agent", "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c", "status": "active" }
      ],
      "documents": [
        { "id": "3e7b1a9c-5d2f-4e8a-9b6c-1d4f7a0e3b2c", "object": "document", "type": "certificate_of_formation", "uploaded_at": "2026-06-14T14:29:51Z" }
      ],
      "fee": {
        "base": { "amount": 125, "currency": "USD" },
        "dynamic": { "amount": 100, "currency": "USD" },
        "total": { "amount": 225, "currency": "USD" },
        "items": [
          { "component_type": "base", "name": "filing", "amount": 125, "currency": "USD" },
          { "component_type": "dynamic", "name": "expedited", "amount": 100, "currency": "USD" }
        ]
      },
      "status_reason": null,
      "canceled_by": null,
      "canceled_at": null,
      "cases": [],
      "metadata": {},
      "created_at": "2026-06-13T09:15:00Z",
      "updated_at": "2026-06-14T14:30:00Z"
    }
  }
}
```

### filing.completed (EIN)

*Same `filing.completed` event for an EIN filing* — a different `type` and `result` (issued EIN and entity name), no state fee, and the bundled child of the formation above (`parent_filing_id` points back to it).

```json wrap JSON theme={null}
{
  "id": "evt_1718373300000_c4d5e6f7a8b9",
  "object": "event",
  "type": "filing.completed",
  "mode": "live",
  "created_at": "2026-06-14T15:05:00Z",
  "data": {
    "object": {
      "id": "5a1d8f9b-2e4c-4d7a-8b3f-6c9e0a1d2b4f",
      "object": "filing",
      "type": "ein",
      "status": "completed",
      "entity_type": "llc",
      "jurisdiction": null,
      "name": "Acme Holdings LLC",
      "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "result": {
        "ein_number": "12-3456789",
        "entity_name": "Acme Holdings LLC"
      },
      "parent_filing_id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e",
      "related_items": [],
      "documents": [
        { "id": "8c2d1f6b-3a9e-4d7c-b5f2-0a4e7c1d9b3f", "object": "document", "type": "ein_letter", "uploaded_at": "2026-06-14T15:04:40Z" }
      ],
      "fee": null,
      "status_reason": null,
      "canceled_by": null,
      "canceled_at": null,
      "cases": [],
      "metadata": {},
      "created_at": "2026-06-13T09:15:30Z",
      "updated_at": "2026-06-14T15:05:00Z"
    }
  }
}
```

### filing.canceled

*Fires when a filing is canceled.* `status_reason`, `canceled_by`, and `canceled_at` are populated.

```json wrap JSON theme={null}
{
  "id": "evt_1718373000000_b2c3d4e5f6a7",
  "object": "event",
  "type": "filing.canceled",
  "mode": "live",
  "created_at": "2026-06-14T14:40:00Z",
  "data": {
    "object": {
      "id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e",
      "object": "filing",
      "type": "formation",
      "status": "canceled",
      "entity_type": "llc",
      "jurisdiction": "US-NC",
      "name": "Acme Holdings LLC",
      "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "result": null,
      "fee": null,
      "status_reason": "Canceled at partner request before submission to the state.",
      "canceled_by": "partner",
      "canceled_at": "2026-06-14T14:40:00Z",
      "cases": [],
      "metadata": {},
      "created_at": "2026-06-13T09:15:00Z",
      "updated_at": "2026-06-14T14:40:00Z"
    }
  }
}
```

## Case events

All `case.*` events carry the same `case` object on `data.object`; `status`, `response`, `resolved_at`, and `resolution_reason` evolve as the case progresses.

### case.opened

*Fires when Palm opens a case and needs your response.* For `missing_information` cases, `request.fields` describes exactly what to supply.

```json wrap JSON theme={null}
{
  "id": "evt_1718373600000_c3d4e5f6a7b8",
  "object": "event",
  "type": "case.opened",
  "mode": "live",
  "created_at": "2026-06-14T14:50:00Z",
  "data": {
    "object": {
      "id": "4f8c2b1e-7d9a-4c3e-8b1f-2a6d9c0e4b7a",
      "object": "case",
      "parent_type": "filing",
      "parent_id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e",
      "kind": "missing_information",
      "status": "needs_response",
      "summary": "Additional information needed to complete your filing.",
      "details": "The state requires a physical street address for the registered agent. PO boxes are not accepted.",
      "request": {
        "fields": [
          {
            "name": "registered_agent_address",
            "type": "string",
            "description": "Physical street address for the registered agent (no PO boxes).",
            "required": true,
            "example": "150 Fayetteville St, Suite 1100, Raleigh, NC 27601"
          }
        ]
      },
      "response": null,
      "due_at": "2026-06-21T23:59:59Z",
      "opened_at": "2026-06-14T14:50:00Z",
      "resolved_at": null,
      "resolution_reason": null,
      "metadata": {},
      "created_at": "2026-06-14T14:50:00Z",
      "updated_at": "2026-06-14T14:50:00Z"
    }
  }
}
```

### case.updated

*Fires when an open case changes* — for example, your response is received and the case moves to `under_review`. `response.fields` now carries what you submitted.

```json wrap JSON theme={null}
{
  "id": "evt_1718442000000_e5f6a7b8c9d0",
  "object": "event",
  "type": "case.updated",
  "mode": "live",
  "created_at": "2026-06-15T09:00:00Z",
  "data": {
    "object": {
      "id": "4f8c2b1e-7d9a-4c3e-8b1f-2a6d9c0e4b7a",
      "object": "case",
      "parent_type": "filing",
      "parent_id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e",
      "kind": "missing_information",
      "status": "under_review",
      "summary": "Additional information needed to complete your filing.",
      "details": "The state requires a physical street address for the registered agent. PO boxes are not accepted.",
      "request": {
        "fields": [
          {
            "name": "registered_agent_address",
            "type": "string",
            "description": "Physical street address for the registered agent (no PO boxes).",
            "required": true,
            "example": "150 Fayetteville St, Suite 1100, Raleigh, NC 27601"
          }
        ]
      },
      "response": {
        "fields": {
          "registered_agent_address": "401 S Tryon St, Suite 2200, Charlotte, NC 28202"
        }
      },
      "due_at": "2026-06-21T23:59:59Z",
      "opened_at": "2026-06-14T14:50:00Z",
      "resolved_at": null,
      "resolution_reason": null,
      "metadata": {},
      "created_at": "2026-06-14T14:50:00Z",
      "updated_at": "2026-06-15T09:00:00Z"
    }
  }
}
```

### case.resolved

*Fires when the case closes* (`resolved` or `superseded`). `resolved_at` is set and `resolution_reason` is one of `response_received`, `no_response_needed`, `parent_canceled`, `parent_completed`, or `parent_failed`.

```json wrap JSON theme={null}
{
  "id": "evt_1718447400000_d5e6f7a8b9c0",
  "object": "event",
  "type": "case.resolved",
  "mode": "live",
  "created_at": "2026-06-15T11:00:00Z",
  "data": {
    "object": {
      "id": "4f8c2b1e-7d9a-4c3e-8b1f-2a6d9c0e4b7a",
      "object": "case",
      "parent_type": "filing",
      "parent_id": "7d9e4c2a-1b8f-4a3d-9c6e-5f0a1b2c3d4e",
      "kind": "missing_information",
      "status": "resolved",
      "summary": "Additional information needed to complete your filing.",
      "details": "The state requires a physical street address for the registered agent. PO boxes are not accepted.",
      "request": {
        "fields": [
          {
            "name": "registered_agent_address",
            "type": "string",
            "description": "Physical street address for the registered agent (no PO boxes).",
            "required": true,
            "example": "150 Fayetteville St, Suite 1100, Raleigh, NC 27601"
          }
        ]
      },
      "response": {
        "fields": {
          "registered_agent_address": "401 S Tryon St, Suite 2200, Charlotte, NC 28202"
        }
      },
      "due_at": "2026-06-21T23:59:59Z",
      "opened_at": "2026-06-14T14:50:00Z",
      "resolved_at": "2026-06-15T11:00:00Z",
      "resolution_reason": "response_received",
      "metadata": {},
      "created_at": "2026-06-14T14:50:00Z",
      "updated_at": "2026-06-15T11:00:00Z"
    }
  }
}
```

## Platform events

Platform events deliver the full resource object. PII stays in the vault, so payloads expose only fingerprints and non-encrypted cached vault fields.

### user.created

*Fires when a person is created through the API.*

```json wrap JSON theme={null}
{
  "id": "evt_1718290000000_d4e5f6a7b8c9",
  "object": "event",
  "type": "user.created",
  "mode": "live",
  "created_at": "2026-06-13T14:46:40Z",
  "data": {
    "object": {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "object": "user",
      "status": "active",
      "display_name": "John Doe",
      "email_fingerprint": "f7c3bc1d808e04732adf679965ccc34ca7ae3441",
      "phone_fingerprint": "a8d4bc2e919f15843be0890076ddd45db8bf4552",
      "verification": null,
      "vault": {
        "identity.first_name": "John",
        "identity.last_name": "Doe"
      },
      "metadata": {
        "external_id": "user_4821"
      },
      "created_at": "2026-06-13T14:46:40Z",
      "updated_at": "2026-06-13T14:46:40Z"
    }
  }
}
```

### user.removed

*Fires when a person is removed.* Same object as `user.created` with `status: deleted`.

```json wrap JSON theme={null}
{
  "id": "evt_1719828000000_f6a7b8c9d0e1",
  "object": "event",
  "type": "user.removed",
  "mode": "live",
  "created_at": "2026-07-01T10:00:00Z",
  "data": {
    "object": {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "object": "user",
      "status": "deleted",
      "display_name": "John Doe",
      "email_fingerprint": "f7c3bc1d808e04732adf679965ccc34ca7ae3441",
      "phone_fingerprint": "a8d4bc2e919f15843be0890076ddd45db8bf4552",
      "verification": null,
      "vault": {
        "identity.first_name": "John",
        "identity.last_name": "Doe"
      },
      "metadata": {
        "external_id": "user_4821"
      },
      "created_at": "2026-06-13T14:46:40Z",
      "updated_at": "2026-07-01T10:00:00Z"
    }
  }
}
```

### business.created

*Fires when a business is created through the API.* This is the canonical business object — the same shape returned by `GET /business/{id}`. The EIN is encrypted (surfaced only via `ein_fingerprint`); the non-encrypted fields you set are echoed under `vault` by field ID.

```json wrap JSON theme={null}
{
  "id": "evt_1718269140000_e1f2a3b4c5d6",
  "object": "event",
  "type": "business.created",
  "mode": "live",
  "created_at": "2026-06-13T09:14:00Z",
  "data": {
    "object": {
      "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "object": "business",
      "status": "active",
      "palm_id": "A1B2-C3D4-E5F6",
      "display_name": "Acme Holdings LLC",
      "ein_fingerprint": "9b1c4f7a2e8d05c3a6f9b2e4d7c1a0e3f5b8d2c6",
      "verification": null,
      "vault": {
        "business.legal_name": "Acme Holdings LLC",
        "business.dba_name": "Acme Logistics",
        "business.entity_type": "llc",
        "business.formation_date": "2020-05-15",
        "business.formation_jurisdiction": "US-DE",
        "business.registration_jurisdiction": "US-NC",
        "business.address_line_1": "401 S Tryon St",
        "business.address_line_2": "Suite 2200",
        "business.city": "Charlotte",
        "business.region": "NC",
        "business.postal_code": "28202",
        "business.country": "US",
        "business.phone_number": "+17045551234",
        "business.email": "ops@acmeholdings.com",
        "business.website": "https://acmeholdings.com",
        "business.naics_code": "541614"
      },
      "metadata": {
        "external_id": "biz_4821",
        "customer_tier": "premium",
        "account_manager": "jordan.lee"
      },
      "created_at": "2026-06-13T09:14:00Z",
      "updated_at": "2026-06-13T09:14:00Z"
    }
  }
}
```

Field notes:

* **`ein_fingerprint`** — SHA-256 fingerprint of the EIN, for duplicate detection and search without exposing the value. `business.ein` is encrypted and is not echoed in `vault`.
* **`palm_id`** — Palm's identifier for the business; `null` until the business is matched to a registry record.
* **`verification`** — `null` until the business is verified, then a summary: `{ "id": "...", "risk_level": "low", "workflow": { "name": "Business Verification", "version": 1 }, "executed_at": "..." }`. The full result arrives on `business.verification.completed`.
* **`vault`** — cached non-encrypted business fields you supplied, keyed by field ID. Valid keys: `business.legal_name`, `business.dba_name`, `business.entity_type`, `business.formation_date`, `business.formation_jurisdiction`, `business.registration_jurisdiction`, `business.address_line_1`, `business.address_line_2`, `business.city`, `business.region`, `business.postal_code`, `business.country`, `business.phone_number`, `business.email`, `business.website`, `business.naics_code`.
* **`metadata`** — up to 50 of your own key-value pairs, returned on every event for this business.

### business.removed

*Fires when a business is removed.* Same object as `business.created` with `status: deleted`.

```json wrap JSON theme={null}
{
  "id": "evt_1719828000000_a7b8c9d0e1f2",
  "object": "event",
  "type": "business.removed",
  "mode": "live",
  "created_at": "2026-07-01T10:00:00Z",
  "data": {
    "object": {
      "id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "object": "business",
      "status": "deleted",
      "palm_id": "A1B2-C3D4-E5F6",
      "display_name": "Acme Holdings LLC",
      "ein_fingerprint": "9b1c4f7a2e8d05c3a6f9b2e4d7c1a0e3f5b8d2c6",
      "verification": null,
      "vault": {
        "business.legal_name": "Acme Holdings LLC",
        "business.entity_type": "llc",
        "business.region": "NC"
      },
      "metadata": {
        "external_id": "biz_4821"
      },
      "created_at": "2026-06-13T09:14:00Z",
      "updated_at": "2026-07-01T10:00:00Z"
    }
  }
}
```

## Document events

### document.created (filing artifact)

*Fires when Palm attaches a document on its own initiative.* Route on `data.object.type`. Here, the certificate produced by a completed formation.

```json wrap JSON theme={null}
{
  "id": "evt_1718372460000_f6a7b8c9d0e1",
  "object": "event",
  "type": "document.created",
  "mode": "live",
  "created_at": "2026-06-14T14:30:51Z",
  "data": {
    "object": {
      "id": "3e7b1a9c-5d2f-4e8a-9b6c-1d4f7a0e3b2c",
      "object": "document",
      "type": "certificate_of_formation",
      "filename": "certificate_of_formation.pdf",
      "file_size": 184320,
      "content_type": "application/pdf",
      "status": "verified",
      "upload_date": "2026-06-14T14:30:51Z",
      "verification_details": null,
      "metadata": {
        "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c"
      },
      "created_at": "2026-06-14T14:30:51Z",
      "updated_at": "2026-06-14T14:30:51Z"
    }
  }
}
```

### document.created (forwarded mail)

*The same event for forwarded registered-agent mail* — `type` is `mail` (or `notice`) instead of a filing artifact.

```json wrap JSON theme={null}
{
  "id": "evt_1723723200000_b8c9d0e1f2a3",
  "object": "event",
  "type": "document.created",
  "mode": "live",
  "created_at": "2026-08-15T12:00:00Z",
  "data": {
    "object": {
      "id": "2b7f9d1c-4e6a-4b8d-9f3c-5a0e2d7c1b48",
      "object": "document",
      "type": "mail",
      "filename": "nc_sos_notice_2026-08-15.pdf",
      "file_size": 98304,
      "content_type": "application/pdf",
      "status": "verified",
      "upload_date": "2026-08-15T12:00:00Z",
      "verification_details": null,
      "metadata": {
        "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c"
      },
      "created_at": "2026-08-15T12:00:00Z",
      "updated_at": "2026-08-15T12:00:00Z"
    }
  }
}
```

## Registered agent events

Registered agent (RA) is a **standalone resource**, not a filing — it never emits `filing.*` events. On a formation it appears in `related_items` as a `registered_agent` item (status `pending` until it goes `active`), and it has its own resource at `GET /v1/business/:business_id/registered-agent`. Every lifecycle transition delivers the RA snapshot on `data.object`:

* **`status`** — `pending`, `active`, `termination_requested`, `terminated`, or `failed`.
* **`provider`** — `palm` while Palm is the agent (`active` / `termination_requested`), `external` after a change-away or termination.
* **`rejection_reason`** — present only on the failure events (`failed`, `change_failed`, `termination_failed`).

RA payloads do not carry the agent's `name` or `address`; the concrete provider Palm uses is server-side and never exposed.

### registered\_agent.activated

*Fires when Palm becomes the registered agent* — formation provisioning completing, or a change into Palm. `status` is `active`, `provider` is `palm`.

```json wrap JSON theme={null}
{
  "id": "evt_1718372700000_a7b8c9d0e1f2",
  "object": "event",
  "type": "registered_agent.activated",
  "mode": "live",
  "created_at": "2026-06-14T14:35:00Z",
  "data": {
    "object": {
      "object": "registered_agent",
      "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "provider": "palm",
      "status": "active",
      "jurisdiction": "NC",
      "started_at": "2026-06-14T14:35:00Z",
      "ended_at": null
    }
  }
}
```

### registered\_agent.failed

*Fires when RA provisioning (or a required state submission) fails* on the assignment path — there was no prior RA to fall back to. `status` is `failed` and `rejection_reason` explains the blocker.

```json wrap JSON theme={null}
{
  "id": "evt_1718373900000_b1c2d3e4f5a6",
  "object": "event",
  "type": "registered_agent.failed",
  "mode": "live",
  "created_at": "2026-06-14T15:15:00Z",
  "data": {
    "object": {
      "object": "registered_agent",
      "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "provider": "palm",
      "status": "failed",
      "jurisdiction": "NC",
      "started_at": null,
      "ended_at": null,
      "rejection_reason": "Registered-agent provisioning could not be completed: the state rejected the agent designation."
    }
  }
}
```

### registered\_agent.change\_failed

*Fires when a partner-requested RA change cannot be completed.* Unlike an assignment failure, the change never took effect, so `status` reverts from the transient `pending` back to `active` — Palm remains the RA of record. `rejection_reason` explains the blocker.

```json wrap JSON theme={null}
{
  "id": "evt_1723456800000_c2d3e4f5a6b7",
  "object": "event",
  "type": "registered_agent.change_failed",
  "mode": "live",
  "created_at": "2026-08-12T09:00:00Z",
  "data": {
    "object": {
      "object": "registered_agent",
      "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "provider": "palm",
      "status": "active",
      "jurisdiction": "NC",
      "started_at": "2026-06-14T14:35:00Z",
      "ended_at": null,
      "rejection_reason": "Registered-agent change could not be completed: the destination agent did not confirm consent. Palm remains the registered agent."
    }
  }
}
```

### registered\_agent.changed

*Fires when an RA change moves the business to another provider.* `provider` becomes `external`, `status` is `terminated`, and `ended_at` is set.

```json wrap JSON theme={null}
{
  "id": "evt_1725192000000_e1f2a3b4c5d6",
  "object": "event",
  "type": "registered_agent.changed",
  "mode": "live",
  "created_at": "2026-09-01T12:00:00Z",
  "data": {
    "object": {
      "object": "registered_agent",
      "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "provider": "external",
      "status": "terminated",
      "jurisdiction": "NC",
      "started_at": "2026-06-14T14:35:00Z",
      "ended_at": "2026-09-01T12:00:00Z"
    }
  }
}
```

### registered\_agent.termination\_requested

*Fires when you ask Palm to resign* via `PATCH /v1/business/:business_id/registered-agent`. `status` moves to `termination_requested`; Palm stays the RA on file and keeps forwarding mail until operations completes the work.

```json wrap JSON theme={null}
{
  "id": "evt_1723111200000_c9d0e1f2a3b4",
  "object": "event",
  "type": "registered_agent.termination_requested",
  "mode": "live",
  "created_at": "2026-08-20T10:00:00Z",
  "data": {
    "object": {
      "object": "registered_agent",
      "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "provider": "palm",
      "status": "termination_requested",
      "jurisdiction": "NC",
      "started_at": "2026-06-14T14:35:00Z",
      "ended_at": null
    }
  }
}
```

### registered\_agent.terminated

*Fires when operations completes the termination and Palm is no longer the RA on file.* `status` is `terminated`, `provider` flips to `external`, and `ended_at` carries the close timestamp.

```json wrap JSON theme={null}
{
  "id": "evt_1725192000000_b9c0d1e2f3a4",
  "object": "event",
  "type": "registered_agent.terminated",
  "mode": "live",
  "created_at": "2026-09-01T12:00:00Z",
  "data": {
    "object": {
      "object": "registered_agent",
      "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "provider": "external",
      "status": "terminated",
      "jurisdiction": "NC",
      "started_at": "2026-06-14T14:35:00Z",
      "ended_at": "2026-09-01T12:00:00Z"
    }
  }
}
```

### registered\_agent.termination\_failed

*Fires when a termination cannot be completed* (state refused the resignation, a successor RA is required and none was supplied, etc.). `status` reverts to `active`, `rejection_reason` explains the blocker, and Palm keeps serving as RA. You can re-submit once it is resolved.

```json wrap JSON theme={null}
{
  "id": "evt_1724594400000_d0e1f2a3b4c5",
  "object": "event",
  "type": "registered_agent.termination_failed",
  "mode": "live",
  "created_at": "2026-08-25T14:00:00Z",
  "data": {
    "object": {
      "object": "registered_agent",
      "business_id": "b3f1c8a2-5d47-4e9b-8a1c-2f6d9e0b4a7c",
      "provider": "palm",
      "status": "active",
      "jurisdiction": "NC",
      "started_at": "2026-06-14T14:35:00Z",
      "ended_at": null,
      "rejection_reason": "State refused resignation form: a successor registered agent must be designated before Palm can resign."
    }
  }
}
```