Developer Reference

Claim Approvals Webhook Reference

UnityTrip can notify your systems in real time as claims move through their lifecycle. When an event you've subscribed to occurs, UnityTrip sends an HTTP request to your configured endpoint with a JSON payload describing what happened. This document describes each event type and the structure of its payload so you can build and validate your receiving integration.

Delivery basics

Method: POST
Content-Type: application/json
Body: a single JSON object per event.
Endpoint: the Webhook URL you configure in Ops Manager (Webhooks).
A webhook fires only for the event types selected in its configuration.
Always respond with a 2xx status code to acknowledge receipt. Non-2xx responses may be treated as failed deliveries.

Common envelope

Every event shares the same top-level structure. The data object carries fields specific to each event type, while the remaining fields are common to all.

Field	Type	Description
`deliveryId`	string (UUID)	Unique ID for this individual delivery. Use it to detect and discard duplicates.
`claimId`	string (UUID)	Internal unique identifier of the claim.
`claimIdentifier`	string	Human-readable claim reference (e.g. `CLM-01533`).
`eventType`	string	The event name. Determines the shape of `data`.
`timestamp`	string (ISO 8601)	When the event was generated.
`data`	object	Event-specific metadata. See each event below.
`costCenter`	object	The cost centre associated with the claim.
`costCenter.id`	string (UUID)	Internal cost centre identifier.
`costCenter.name`	string	Display name of the cost centre.
`costCenter.identifier`	string	Short code for the cost centre (e.g. `NEIL1`).
`fund`	object	The fund associated with the claim.
`fund.id`	string (UUID)	Internal fund identifier.
`fund.name`	string	Display name of the fund.
`requestTitle`	string	Title given to the request.
`tripReason`	string	Stated reason for the trip (e.g. `Business`).
`requestDescription`	string	Free-text description of the request.
`link`	string (URL)	Deep link to the claim in the UnityTrip web app.

Common `data` fields

These fields appear within data across most event types:

Field	Type	Description
`$type`	integer	Internal discriminator identifying the event payload type.
`timestamp`	string (ISO 8601)	When the underlying action occurred.
`email`	string \| null	Email of the user associated with the action, when applicable. May be `null` for system-initiated actions.
`publishedAt`	string (ISO 8601)	When the event was published to the delivery queue.
`outOfSyncReason`	string \| null	Reason the claim was flagged out of sync, if any. Empty string or `null` when none.
`approvers`	array of objects	The approvers assigned to the claim, in approval order. See The `approvers` array below.

Event-specific data fields are listed under each event below.

The `approvers` array

Most events include an approvers array in their data object describing every person in the claim's approval chain, in the order they are required to act. This lets you answer "who is this claim waiting on?" and build views such as a list of pending bookings grouped by approver, without an additional API call. A cost centre can require a single approver or a multi-step chain — the array contains one object per approver, ordered by sequence.

The array is present on ClaimCreatedEvent, ClaimApprovedEvent, ClaimApproverAddedEvent, ClaimUpdatedEvent, ClaimRejectedEvent, ClaimClosedEvent, ClaimRevisionCreated, and ClaimRevisionApprovedEvent. It is not included on ClaimPartialApprovedEvent — see that event for how to advance your pending list.

Field	Type	Description
`approvers[].email`	string	Email address of the approver.
`approvers[].name`	string	Display name of the approver (e.g. `Mr Neil Test`).
`approvers[].employeeId`	string	The approver's employee identifier in your organisation.
`approvers[].sequence`	integer	Position of this approver in the approval chain, starting at `1`. Approvers act in ascending sequence order; a claim is fully approved only once the highest sequence has approved.
`approvers[].isSubstitution`	boolean	`true` if this approver is acting as a delegate or substitute for the originally assigned approver.

Example — a two-approver chain

A cost centre configured with two approvers produces an approvers array like this. The claim is presented to sequence 1 first; once they approve, it advances to sequence 2.

"approvers": [
  {
    "email": "[email protected]",
    "name": "Mr First Approver",
    "employeeId": "11111",
    "sequence": 1,
    "isSubstitution": false
  },
  {
    "email": "[email protected]",
    "name": "Mr Second Approver",
    "employeeId": "8888",
    "sequence": 2,
    "isSubstitution": true
  }
]

Tip — pending bookings by approver: To surface what each approver still needs to action, track the open claims from ClaimCreatedEvent and ClaimRevisionCreated and group them by approvers[].email (or employeeId). The current approver is the one with the lowest sequence who has not yet approved — show the claim only on their list. When a ClaimPartialApprovedEvent arrives, one approver in the chain has approved but the claim still needs the next one, so advance it to the next sequence. Remove the claim from all pending lists when you receive a ClaimApprovedEvent (final approval), ClaimRejectedEvent, or ClaimClosedEvent.

ClaimCreatedEvent

Fired when a new claim is created.

Example payload

{
  "deliveryId": "8c7b97c2-6cbe-4ceb-9bee-93cb1fcf8bb9",
  "claimId": "db9adf7d-1522-45ad-ac61-b789a2156267",
  "claimIdentifier": "CLM-01533",
  "eventType": "ClaimCreatedEvent",
  "timestamp": "2026-06-02T01:12:15.9707421+00:00",
  "data": {
    "$type": 7,
    "timestamp": "2026-06-02T01:12:13.9291571+00:00",
    "email": "[email protected]",
    "publishedAt": "2026-06-02T01:12:14.5512303+00:00",
    "approvers": [
      {
        "email": "[email protected]",
        "name": "Mr Neil Test",
        "employeeId": "11111",
        "sequence": 1,
        "isSubstitution": false
      }
    ]
  },
  "costCenter": {
    "id": "4beda99c-9efd-4b51-ae32-8fcc1b0b48b2",
    "name": "Example Cost Centre",
    "identifier": "NEIL1"
  },
  "fund": {
    "id": "50ba2af9-40f7-41b5-8e10-1a8ba774f746",
    "name": "Training"
  },
  "requestTitle": "Example request",
  "tripReason": "Business",
  "requestDescription": "NEIL1 - Training",
  "link": "https://app.unitytrip.app/claims/db9adf7d-1522-45ad-ac61-b789a2156267"
}

`data` fields

Uses the common envelope and common data fields. $type is 7.

ClaimApprovedEvent

Fired when a claim is fully approved. In a multi-step approval chain this is the final approval — the last approver in sequence order has approved. Earlier approvals in the chain fire ClaimPartialApprovedEvent instead.

Example payload

{
  "deliveryId": "8ab890dc-95d7-47f8-b69d-573ed1831ffb",
  "claimId": "db9adf7d-1522-45ad-ac61-b789a2156267",
  "claimIdentifier": "CLM-01533",
  "eventType": "ClaimApprovedEvent",
  "timestamp": "2026-06-02T01:21:07.3115601+00:00",
  "data": {
    "$type": 1,
    "outOfSyncReason": "",
    "timestamp": "2026-06-02T01:21:05.7020226+00:00",
    "email": "[email protected]",
    "publishedAt": "2026-06-02T01:21:05.8547919+00:00",
    "approvers": [
      {
        "email": "[email protected]",
        "name": "Mr Neil Test",
        "employeeId": "11111",
        "sequence": 1,
        "isSubstitution": false
      }
    ]
  },
  "costCenter": {
    "id": "4beda99c-9efd-4b51-ae32-8fcc1b0b48b2",
    "name": "Example Cost Centre",
    "identifier": "NEIL1"
  },
  "fund": {
    "id": "50ba2af9-40f7-41b5-8e10-1a8ba774f746",
    "name": "Training"
  },
  "requestTitle": "Example request",
  "tripReason": "Business",
  "requestDescription": "NEIL1 - Training",
  "link": "https://app.unitytrip.app/claims/db9adf7d-1522-45ad-ac61-b789a2156267"
}

`data` fields

Uses the common envelope and common data fields. $type is 1.

Field	Type	Description
`outOfSyncReason`	string \| null	Reason the claim was out of sync, if any e.g., an admin chose to override and cancel a claim.

ClaimPartialApprovedEvent

Fired when one approver in a multi-step approval chain approves but the claim still requires approval from one or more later approvers. The claim now advances to the next sequence. A final ClaimApprovedEvent follows once the last approver acts.

Note: Unlike most events, ClaimPartialApprovedEvent does not include the approvers array. Use the chain you captured from ClaimCreatedEvent (or ClaimApproverAddedEvent) to determine who the next approver is. The email field identifies the approver who just acted.

Example payload

{
  "deliveryId": "2e9b40ca-48b2-4c58-89f8-17a47bac21e3",
  "claimId": "b2aa03e8-1fcc-437e-9081-7213b7c52563",
  "claimIdentifier": "CLM-01536",
  "eventType": "ClaimPartialApprovedEvent",
  "timestamp": "2026-06-05T00:55:58.2794482+00:00",
  "data": {
    "$type": 19,
    "outOfSyncReason": "",
    "timestamp": "2026-06-05T00:55:58.1703789+00:00",
    "email": "[email protected]",
    "publishedAt": "2026-06-05T00:55:58.1806732+00:00"
  },
  "costCenter": {
    "id": "d6181b11-ff27-487e-bb40-43e1897a6315",
    "name": "Example Cost Centre (2 approvers)",
    "identifier": "NEIL2"
  },
  "fund": {
    "id": "713a0a07-aac4-4514-9ce0-440e8593448c",
    "name": "Business Meetings"
  },
  "requestTitle": "Example request",
  "tripReason": "Business",
  "requestDescription": "NEIL2 - Business Meetings",
  "link": "https://app.unitytrip.app/claims/b2aa03e8-1fcc-437e-9081-7213b7c52563"
}

`data` fields

Uses the common envelope and common data fields. $type is 19. The approvers array is not included.

Field	Type	Description
`email`	string	Email of the approver who just approved this step.
`outOfSyncReason`	string \| null	Reason the claim was out of sync, if any e.g., an admin chose to override and cancel a claim.

ClaimUpdatedEvent

Fired when an existing claim is updated.

Example payload

{
  "deliveryId": "54d93a54-a99e-411e-9a9c-19849daaf9b2",
  "claimId": "75da7441-5a94-43cf-af42-1f9ee060533c",
  "claimIdentifier": "CLM-01458",
  "eventType": "ClaimUpdatedEvent",
  "timestamp": "2026-06-02T01:24:10.4166107+00:00",
  "data": {
    "$type": 6,
    "reason": "Clarification change made2",
    "timestamp": "2026-06-02T01:24:10.3362989+00:00",
    "email": null,
    "publishedAt": "2026-06-02T01:24:10.3746569+00:00",
    "approvers": [
      {
        "email": "[email protected]",
        "name": "Mr Neil Test",
        "employeeId": "11111",
        "sequence": 1,
        "isSubstitution": false
      }
    ]
  },
  "costCenter": {
    "id": "1c143e48-3335-4b88-90d3-721ff20f62c5",
    "name": "Example Cost Centre",
    "identifier": "NEIL1"
  },
  "fund": {
    "id": "50ba2af9-40f7-41b5-8e10-1a8ba774f746",
    "name": "Training"
  },
  "requestTitle": "Example request",
  "tripReason": "Business",
  "requestDescription": "NEIL1 - Training",
  "link": "https://app.unitytrip.app/claims/75da7441-5a94-43cf-af42-1f9ee060533c"
}

`data` fields

Uses the common envelope and common data fields. $type is 6.

Field	Type	Description
`reason`	string	Reason given for the update.

ClaimRejectedEvent

Fired when a claim is rejected.

Example payload

{
  "deliveryId": "ba4592d2-3c9e-4b60-9bd9-4ffef38159cb",
  "claimId": "7d2e71d0-b8eb-4956-9437-3e4be5c646ff",
  "claimIdentifier": "CLM-01462",
  "eventType": "ClaimRejectedEvent",
  "timestamp": "2026-06-02T01:26:32.5960592+00:00",
  "data": {
    "$type": 2,
    "reason": "",
    "outOfSyncReason": null,
    "timestamp": "2026-06-02T01:26:32.4997626+00:00",
    "email": null,
    "publishedAt": "2026-06-02T01:26:32.5627479+00:00",
    "approvers": [
      {
        "email": "[email protected]",
        "name": "Mr Neil Test",
        "employeeId": "11111",
        "sequence": 1,
        "isSubstitution": false
      }
    ]
  },
  "costCenter": {
    "id": "1c143e48-3335-4b88-90d3-721ff20f62c5",
    "name": "Example Cost Centre",
    "identifier": "NEIL1"
  },
  "fund": {
    "id": "50ba2af9-40f7-41b5-8e10-1a8ba774f746",
    "name": "Training"
  },
  "requestTitle": "Example request",
  "tripReason": "Business",
  "requestDescription": "NEIL1 - Training",
  "link": "https://app.unitytrip.app/claims/7d2e71d0-b8eb-4956-9437-3e4be5c646ff"
}

`data` fields

Uses the common envelope and common data fields. $type is 2.

Field	Type	Description
`reason`	string	Reason given for the rejection. May be an empty string.
`outOfSyncReason`	string \| null	Reason the claim was out of sync, if any e.g., an admin chose to override and cancel a claim.

ClaimClosedEvent

Fired when a claim is closed.

Example payload

{
  "deliveryId": "ad84ae04-c2fb-49fb-901c-7f8fecacfada",
  "claimId": "b8fd7e64-5789-42bc-ae5c-087ee3812eb3",
  "claimIdentifier": "CLM-01532",
  "eventType": "ClaimClosedEvent",
  "timestamp": "2026-06-02T01:09:40.879154+00:00",
  "data": {
    "$type": 8,
    "reason": "Closed by admin",
    "byAdmin": true,
    "timestamp": "2026-06-02T01:09:39.777797+00:00",
    "email": null,
    "publishedAt": "2026-06-02T01:09:39.8600662+00:00",
    "approvers": [
      {
        "email": "[email protected]",
        "name": "Mr Neil Test",
        "employeeId": "11111",
        "sequence": 1,
        "isSubstitution": false
      }
    ]
  },
  "costCenter": {
    "id": "4beda99c-9efd-4b51-ae32-8fcc1b0b48b2",
    "name": "Example Cost Centre",
    "identifier": "NEIL1"
  },
  "fund": {
    "id": "50ba2af9-40f7-41b5-8e10-1a8ba774f746",
    "name": "Training"
  },
  "requestTitle": "Example request",
  "tripReason": "Business",
  "requestDescription": "NEIL1 - Training",
  "link": "https://app.unitytrip.app/claims/b8fd7e64-5789-42bc-ae5c-087ee3812eb3"
}

`data` fields

Uses the common envelope and common data fields. $type is 8.

Field	Type	Description
`reason`	string	Reason the claim was closed.
`byAdmin`	boolean	`true` if the claim was closed by an administrator.

ClaimRevisionCreated

Fired when a revision of a claim is created.

Example payload

{
  "deliveryId": "182967b4-f015-4f0b-b1b9-67fb3c15cef0",
  "claimId": "db9adf7d-1522-45ad-ac61-b789a2156267",
  "claimIdentifier": "CLM-01533",
  "eventType": "ClaimRevisionCreated",
  "timestamp": "2026-06-02T01:26:05.8002028+00:00",
  "data": {
    "$type": 10,
    "reason": "2 days testing of change",
    "version": 1,
    "outOfSyncReason": null,
    "timestamp": "2026-06-02T01:26:05.7511428+00:00",
    "email": null,
    "publishedAt": "2026-06-02T01:26:05.778295+00:00",
    "approvers": [
      {
        "email": "[email protected]",
        "name": "Mr Neil Test",
        "employeeId": "11111",
        "sequence": 1,
        "isSubstitution": false
      }
    ]
  },
  "costCenter": {
    "id": "4beda99c-9efd-4b51-ae32-8fcc1b0b48b2",
    "name": "Example Cost Centre",
    "identifier": "NEIL1"
  },
  "fund": {
    "id": "50ba2af9-40f7-41b5-8e10-1a8ba774f746",
    "name": "Training"
  },
  "requestTitle": "Example request",
  "tripReason": "Business",
  "requestDescription": "NEIL1 - Training",
  "link": "https://app.unitytrip.app/claims/db9adf7d-1522-45ad-ac61-b789a2156267"
}

`data` fields

Uses the common envelope and common data fields. $type is 10.

Field	Type	Description
`reason`	string	Reason given for the revision.
`version`	integer	Version number of the revision.
`outOfSyncReason`	string \| null	Reason the claim was out of sync, if any e.g., an admin chose to override and cancel a claim.

ClaimRevisionApprovedEvent

Fired when a claim revision is approved.

Example payload

{
  "deliveryId": "c2fd953c-0038-496a-a0ad-4beb36df4a5a",
  "claimId": "db9adf7d-1522-45ad-ac61-b789a2156267",
  "claimIdentifier": "CLM-01533",
  "eventType": "ClaimRevisionApprovedEvent",
  "timestamp": "2026-06-02T01:28:24.2506214+00:00",
  "data": {
    "$type": 14,
    "version": 1,
    "outOfSyncReason": "",
    "timestamp": "2026-06-02T01:28:24.1943104+00:00",
    "email": "[email protected]",
    "publishedAt": "2026-06-02T01:28:24.2195565+00:00",
    "approvers": [
      {
        "email": "[email protected]",
        "name": "Mr Neil Test",
        "employeeId": "11111",
        "sequence": 1,
        "isSubstitution": false
      }
    ]
  },
  "costCenter": {
    "id": "4beda99c-9efd-4b51-ae32-8fcc1b0b48b2",
    "name": "Example Cost Centre",
    "identifier": "NEIL1"
  },
  "fund": {
    "id": "50ba2af9-40f7-41b5-8e10-1a8ba774f746",
    "name": "Training"
  },
  "requestTitle": "Example request",
  "tripReason": "Business",
  "requestDescription": "NEIL1 - Training",
  "link": "https://app.unitytrip.app/claims/db9adf7d-1522-45ad-ac61-b789a2156267"
}

`data` fields

Uses the common envelope and common data fields. $type is 14.

Field	Type	Description
`version`	integer	Version number of the approved revision.
`outOfSyncReason`	string \| null	Reason the claim was out of sync, if any e.g., an admin chose to override and cancel a claim.

ClaimApproverAddedEvent

Fired when an approver is added to a claim's approval chain — for example when a substitute or an additional approver is assigned. In addition to the common approvers array, this event's data carries an approver object with the full profile of the person who was added.

Example payload

{
  "deliveryId": "aeacf3d3-e333-4962-96b8-2be2f4f2ee55",
  "claimId": "26c8d4c2-ad48-4ab1-b44f-f556294fcb2b",
  "claimIdentifier": "CLM-01535",
  "eventType": "ClaimApproverAddedEvent",
  "timestamp": "2026-06-05T00:41:33.2669466+00:00",
  "data": {
    "$type": 18,
    "approver": {
      "title": "Mr",
      "firstname": "Second",
      "lastname": "Approver",
      "displayname": "Mr Second Approver",
      "normalizedSearchValue": "mr second approver [email protected] 45454",
      "email": "[email protected]",
      "phone": "45454",
      "employeeId": "8888",
      "employeeLevel": "B (Level 13-15)",
      "division": "LSS",
      "department": "LSS",
      "unit": "7",
      "passengerType": "Staff",
      "subPassengerType": 0,
      "locationId": "225336756",
      "policyGroupId": "45",
      "id": "6e761b17-9dce-4494-9373-316c779a3469"
    },
    "byAdmin": false,
    "timestamp": "2026-06-05T00:41:33.2103192+00:00",
    "email": "[email protected]",
    "publishedAt": "2026-06-05T00:41:33.2191833+00:00",
    "approvers": [
      {
        "email": "[email protected]",
        "name": "Mr First Approver",
        "employeeId": "11111",
        "sequence": 1,
        "isSubstitution": false
      },
      {
        "email": "[email protected]",
        "name": "Mr Second Approver",
        "employeeId": "8888",
        "sequence": 2,
        "isSubstitution": true
      }
    ]
  },
  "costCenter": {
    "id": "d6181b11-ff27-487e-bb40-43e1897a6315",
    "name": "Example Cost Centre (2 approvers)",
    "identifier": "NEIL2"
  },
  "fund": {
    "id": "713a0a07-aac4-4514-9ce0-440e8593448c",
    "name": "Business Meetings"
  },
  "requestTitle": "Example request",
  "tripReason": "Business",
  "requestDescription": "NEIL2 - Business Meetings",
  "link": "https://app.unitytrip.app/claims/26c8d4c2-ad48-4ab1-b44f-f556294fcb2b"
}

`data` fields

Uses the common envelope and common data fields. $type is 18.

Field	Type	Description
`byAdmin`	boolean	`true` if an administrator added the approver.
`approver`	object	Full profile of the approver who was added. See below.

The `approver` object

Field	Type	Description
`id`	string (UUID)	Internal unique identifier of the approver.
`title`	string	Honorific title (e.g. `Mr`).
`firstname`	string	Given name.
`lastname`	string	Family name.
`displayname`	string	Full display name.
`normalizedSearchValue`	string	Lower-cased, concatenated search string used internally for lookup. Not intended for display.
`email`	string	Email address.
`phone`	string	Contact phone number.
`employeeId`	string	Employee identifier in your organisation.
`employeeLevel`	string	Employee grade or band (e.g. `B (Level 13-15)`).
`division`	string	Division the approver belongs to.
`department`	string	Department the approver belongs to.
`unit`	string	Organisational unit.
`passengerType`	string	Passenger classification (e.g. `Staff`).
`subPassengerType`	integer	Numeric sub-classification of the passenger type.
`locationId`	string	Identifier of the approver's location.
`policyGroupId`	string	Identifier of the policy group the approver is assigned to.

Quick reference: event types and `$type` values

Event type	`$type`	Description
`ClaimCreatedEvent`	7	A new claim is created.
`ClaimApprovedEvent`	1	A claim is fully approved (final approval).
`ClaimPartialApprovedEvent`	19	One approver in a multi-step chain approves; further approval is still required.
`ClaimApproverAddedEvent`	18	An approver is added to the claim's approval chain.
`ClaimUpdatedEvent`	6	An existing claim is updated.
`ClaimRejectedEvent`	2	A claim is rejected.
`ClaimClosedEvent`	8	A claim is closed.
`ClaimRevisionCreated`	10	A revision of a claim is created.
`ClaimRevisionApprovedEvent`	14	A claim revision is approved.

Note: Always switch on the eventType string rather than the numeric $type discriminator, as $type is an internal value subject to change.

Example payloads above use placeholder emails, names, titles, and URLs. Real payloads will contain your organisation's actual data.

Claim Approvals Webhook Reference

Delivery basics

Common envelope

Common data fields

The approvers array

Example — a two-approver chain

ClaimCreatedEvent

Example payload

data fields

ClaimApprovedEvent

Example payload

data fields

ClaimPartialApprovedEvent

Example payload

data fields

ClaimUpdatedEvent

Example payload

data fields

ClaimRejectedEvent

Example payload

data fields

ClaimClosedEvent

Example payload

data fields

ClaimRevisionCreated

Example payload

data fields

ClaimRevisionApprovedEvent

Example payload

data fields

ClaimApproverAddedEvent

Example payload

data fields

The approver object

Quick reference: event types and $type values

Common `data` fields

The `approvers` array

`data` fields

`data` fields

`data` fields

`data` fields

`data` fields

`data` fields

`data` fields

`data` fields

`data` fields

The `approver` object

Quick reference: event types and `$type` values