Skip to main content

Additional Carrier Data

Xiao Mei

By using our API's to create Hi Marley cases, carriers have the option to include an optional object, in which custom carrier specific data can be stored. This allows carriers to store data associated to contacts, operators, or cases that is external to Hi Marley for easy reference during integration workflows. 

Table of Contents

How it Works:

  • Carriers have the ability store non-Hi Marley values as key:value pairs.
  • This object can optionally be added to the following Hi Marley object returned in our API's:
    • customer
    • Operator
    • caseData
  • Additional data can be added to the customer or caseData objects via our Case Creation API.
  • Additional data can be added or modified to the Operator object via our Operator Actions API's.
  • When included, this additonalCarrierData object (and associated key:value pairs) will be returned in all API response and webhook POSTS with the associated entity.

Limitations:

  • Values in this object must be stored as Key:Value pairs.
  • The maximum number of Key:Value pairs that can be stored in the additonalCarrierData object is 50.
  • The maximum Key length (the identifier of each field) is 40 characters.
  • The maximum value length (the data associated with they key) is 500 characters. 

Modifying additionalCarrierData:

  • The additionalCarrierData object can be modified in the caseData and operator objects.
  • additionalCarrierData in the customer object cannot currently be updated outside of the POST Create Case API request.

Examples:

Additional data in caseData object:

     "caseData": {
       "id": "2d434920-d816-4b9b-b2e1-b7772efaf374",
       "archived": false,
       "claimNumber": "claimNumber1023",
       "dateOfLoss": "2023-04-01T08:33:39.048Z",
       "policyNumber": "Vc93rw213872",
       "brand": "Lovable Insurance"
       "additonalCarrierData":{
         "communicationHubId":"sysId10248",
         "commSystemId": "123456a"
         }
     }
  • When added to the caseData object, this additional data will be associated with that specific Hi Marley case.
  • Once added, the additionalCarrierData will be included in all API responses and webhook POSTs containing that caseData object.

Additional data in customer object:

"customer": {
    "id": "e318c055-5f42-4e8b-b262-bb275428b0e6",
    "first": "Jean-Luc",
    "last": "Picard",
    "email": "captain@ncc1701d.org",
    "mobile": "+15553431701",
    "role": "enduser",
    "optStatus": true,
    "optStatusDetail": "OPTED_IN",
    "additionalCarrierData":{
      "communicationHubId":"sysId10248",
      "commSystemId": "123456a"
    }
  }
  • When added to the customer object, this additional data will be associated with that specific customer (policyholder) profile.
  • Once added, the additionalCarrierData will appear in all API responses and webhook POSTs that include that specific customer object.

Additional data in primaryContact object:

    "primaryContact": {
        "id": "20764b4a-0fe4-4bae-a100-40276b2d4d45",
        "first": "Carrier",
        "last": "Adjuster",
        "email": "carrier.adjuster@carrier.org",
        "role": "operator"
        "additionalCarrierData":{
          "communicationHubId":"sysId10248",
          "commSystemId": "123456a"
        }
    }
  • Additional data can be added or modified to the Operator object via our Operator Actions API's.
  • Once added, the additionalCarrierData will appear in all API responses and webhook POSTs that include that specific primaryContact object.

 

Example Use-Case:

In this scenario, a carrier needs to associate external, non-Hi Marley data with a specific customer. This data could represent identifiers, metadata, or attributes sourced from the carrier’s own systems (e.g., policy administration, CRM, or claims platforms).

Once attached, this data will persist as part of the customer object across Hi Marley’s data model - it will be included in all API Responses and Webhook POST's containing that entity.

Initial Create Case API Request:

{
  "caseData": {
    "claimNumber": "456764434563389",
    "brand": "Lovable",
    "dateOfLoss": "2024-05-25T16:00:00.000Z"
  },
  "caseType": "claim",
  "customer": {
    "first": "James",
    "last": "Zimmerman",
    "mobile": "+15552171840",
    "additionalCarrierData": {
      "communicationHubId": "sysId10248",
      "commSystemId": "123456a"
    }
  },
  "primaryContact": {
    "email": "james.zimmerman@himarley.com"
  }
}

In this scenario, the additionalCarrierData object is nested within the customer object.

Initial Create Case API Response:

{
  "caseData": {
    "id": "19ab0fc8-f640-4e9c-a78d-539aa77ba51e",
    "claimNumber": "456764434563389",
    "dateOfLoss": "2024-05-25T16:00:00.000Z",
    "brand": "Lovable"
  },
  "state": "open",
  "caseType": "claim",
  "customer": {
    "id": "8579f999-4483-438c-8422-b3dc62fae9ba",
    "first": "James",
    "last": "Zimmerman",
    "mobile": "+15552171840",
    "role": "enduser",
    "optStatusDetail": "REQUESTED",
    "additionalCarrierData": {
      "communicationHubId": "sysId10248",
      "commSystemId": "123456a"
    }
  }
}

The additionalCarrierData persists in the response, confirming that the data has been attached to the customer object.

Example Event 14 Message Webhook POST:

{
  "caseData": {
    "id": "19ab0fc8-f640-4e9c-a78d-539aa77ba51e",
    "claimNumber": "456764434563389",
    "brand": "Lovable"
  },
  "customer": {
    "id": "8579f999-4483-438c-8422-b3dc62fae9ba",
    "first": "James",
    "last": "Zimmerman",
    "mobile": "+15552171840",
    "role": "enduser",
    "additionalCarrierData": {
      "communicationHubId": "sysId10248",
      "commSystemId": "123456a"
    }
  },
  "messages": [
    {
      "id": "66779ca7-ad87-4915-86d7-3d676280af7f",
      "type": "text",
      "data": "Hello!",
      "author": {
        "_id": "8579f999-4483-438c-8422-b3dc62fae9ba",
        "profile": {
          "firstName": "James",
          "lastName": "Zimmerman"
        },
        "role": "enduser"
      },
      "createdAt": "2025-09-29T16:54:22.969Z"
    }
  ]
}
  • This webhook payload contains the same customer object (identifiable by the UUID at customer.id).
  • The additionalCarrierData object persists and continues to include the associated key-value pairs.

Example Create Case Request with the Same Customer:

{
  "caseData": {
    "claimNumber": "489",
    "brand": "Lovable",
    "dateOfLoss": "2024-05-25T16:00:00.000Z"
  },
  "caseType": "claim",
  "customer": {
    "first": "James",
    "last": "Zimmerman",
    "mobile": "+15552171840"
  }
}

Here, the additionalCarrierData object is omitted from the request. However, since it was already attached to this customer object, Hi Marley recognizes the customer (by mobile number) and retains the associated additional data.

Corresponding Create Case Response:

{
  "caseData": {
    "id": "d8cb05fd-6fb1-4fc5-a2f0-9a6c243fe2d9",
    "claimNumber": "489",
    "brand": "Lovable"
  },
  "state": "open",
  "caseType": "claim",
  "customer": {
    "id": "8579f999-4483-438c-8422-b3dc62fae9ba",
    "first": "James",
    "last": "Zimmerman",
    "mobile": "+15552171840",
    "role": "enduser",
    "additionalCarrierData": {
      "communicationHubId": "sysId10248",
      "commSystemId": "123456a"
    }
  }
}

The additional data stored on this customer object persists across future cases, webhook posts, and API responses.

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk