Case Creation API

Service Name	Open Case
Service Type	REST
Method	POST
UAT (Sandbox) URL	https://integration.uat.marley.ai/api/case/actions/open
Production URL	https://integration.himarley.io/api/case/actions/open
Technical Documentation	API Endpoint - Postman Collection

This API endpoint is generally the first point of integration and allows for a conversation in Marley to be created programmatically.

By integrating with this endpoint, a conversation about a claim or policy could be created in Hi Marley without the adjuster/employee inputting customer information, and case information manually. This will generally save time and reduce any possible human errors during the case creation process.  

Creating a case via API will open a case in Hi Marley with the same workflows as if it was open in the webapp including the opt-in process and any custom automated messages configured for your organization.

Table of Contents

• Case Creation API Flow
  • Validation Flow
  • Required Fields
  • Request Fields Breakdown
• Integration Flow Diagram
• Feature Integration during Case Creation
• Response Fields Breakdown
• Allow Multiple Cases: Request Path Variation
• Common Errors to Handle
• Implementation Recommendations
  • Pass Date of Loss in UTC
  • Store caseData.id value
  • Implement Direct Hi Marley Chat Links
• Common Integration Patterns
• Related Feature Integration Articles

Case Creation API Flow

Below are the steps the Hi Marley system takes when receiving an API request to create a case.

1. Hi Marley validates the assigned operator (primaryContact) has a valid Hi Marley account, API required fields in the body, and a valid mobile number for the customer (view full validation flow below)
2. Creates a case based on API request
3. Sends a welcome message to end-user/customer
   •  
     • If the customer is new or is not yet opted in, the message will include a request to opt in.
     • If they have already opted in, the default automated message will just provide information about their case, including the contact info of their rep.
       • Note: Marley automated messages can be modified based on carrier preferences
4. Adjusters from Carrier are enabled to text with a customer when they are opted-in 

Validation Flow 

1. If the primary contact is included, Hi Marley confirms that the operator account exists for your organization.
2. Check customer mobile, if the phone number is a landline returns an error.
3. Validates required fields based on caseType.
4. Validates brands if enabled with the Carrier org in Hi Marley.
5. Validates that the case is unique based on the claimNumber or policyNumber (depending on caseType) and customer mobile number.

Required Fields

• customer: Customer first name, last name, and mobile number
  • customer.first
  • customer.last
  • customer.mobile
• caseType: Type of Hi Marley case to open [ claim, policy, case ]
• caseData.brand (required if brands are implemented for the specific carrier org within the Hi Marley platform)

Required caseData Fields for claim caseType

• caseData.claimNumber
• caseData.dateOfLoss

Required caseData Fields for policy caseType

• caseData.policyNumber

Optional caseData Fields for case caseType

• reference
  • This will include a custom reference ID that can be used to identify your Hi Marley case internally

 

Request Fields Breakdown

Property	Required	Element	Description	Type	Required	Example
caseData	true	claimNumber	Fields associated to claim/policy record.	string	true (only claim caseType)	"claimNumber": "0002383632"
		dateOfLoss		dateTime	true (only claim caseType, passes in UTC by default)	"dateOfLoss": "2022-05-25T16:00:00.000Z"
		policyNumber		string	true (only policy caseType)
		deductible		int	false	"deductible": 0
		brand	Subsidiary/Underwriter associated with case	string	false	"brand": "TestBrand1"
		lineOfBusiness	Line Of business associated with the Hi Marley case	object	false	"lineOfBusiness": {       "type": "personal",       "subType": "auto" }
caseType	true		The type of Hi Marley Case. case claim policy	enum	true	"caseType": "claim"
businessName	false		Name of associated business for contact	string		"businessName": "Truckers United Co."
createdBy	false	email	The email of the person with active Hi Marley Account.	string	false	"createdBy":{"email":"[e-mail]"}
roleType	false		The role in the claim process.	enum roleType options: ('claimant' , 'insured' , 'agent' , 'injured-worker' , 'other')	false	"roleType":            "claimant"
customer	true	first	The customers given name.	string	true	"first": "Chili"
		last	The last name of the person assigned to the Hi Marley case.	string	true	"last": "Palmer"
		email	The customers email address.	string	false	"email": "[e-mail]"
		mobile	The customers mobile number.	string	true	"mobile": "[phone]"
		zipCode	The customers zip code. Zip Code must be: Accepts valid US ZIP codes (12345 or 12345-6789). Accepts valid Canadian postal codes (A1A 1A1, case-insensitive, space required). Rejects invalid formats according to each country’s specific pattern.	string	false	"zipCode": "02446"
primaryContact	false	first	The first name of the person assigned to the Hi Marley case.	string	false	"first": "Joe"
		last	The last name of the person assigned to the Hi Marley case.	string	false	"last": "Loop"
		email	The email of the person assigned to the Hi Marley case.	string	true	"email": "[e-mail]"
privacy	false		The case privacy status. public private-redacted	enum	false	"privacy": "public"
languagePreference	false		The preferred language for the current Hi Marley case.	enum	false	"languagePreference": "en"
secondaryOperators   (array)	false	email	The email of the person assigned to the Hi Marley case.	string	false	"email": "[e-mail]"

 

Integration Flow Diagram

Feature Integration During Case Creation

The case creation API features optional fields that enable Hi Marley to leverage functionality available to your organization. Learn more about each feature you can integrate below:

• Integrating Hi Marley Translate
• Integrating Case Visibility
• Integrating Secondary Operator Management
• Integrating Brands and LOBs

 

Response Fields Breakdown

Property	Element	Description	Type	Required	Example
caseData	id	The case identifier for the Hi Marley Case.	string	true	"id": "364ef9bb-fae5-4e2a-a746-cdca465a9c00"
	archived	Indicates if case is closed.	string	true	"archived": false
	claimNumber	Fields associated to claim/policy record.	string	true (only claim caseType)	"claimNumber": "0002383632"
	dateOfLoss		string	false	"dateOfLoss": "2022-05-25T16:00:00.000Z"
	policyNumber		string	true (only policy caseType)
	deductible		string	false
	brand	Subsidiary/Underwriter associated with case	string	true (only if brands are in-use)	"brand": "TestBrand1"
state		The current status of the case state. open close	enum	true	"state": "open"
caseType		The type of Hi Marley Case. case claim policy	enum	true	"caseType": "claim"
customer	id	The identifier generated and assigned to the customer.	string	true	"id": "3c2ea77a-5f3f-4260-8f46-5706d2ad7a28"
	first	The customers given name.	string	true	"first": "Chili"
	last	The last name of the person assigned to the Hi Marley case.	string	true	"last": "Palmer"
	email	The customers email address.	string	false	"email": "[e-mail]"
	mobile	The customers mobile number.	string	true	"mobile": "[phone]"
	role	The customers role. Always set to enduser.	enum	true	"role": "enduser"
	optStatus	The current opt status for the customer.	boolean	true	"optStatus": true
	optStatusDetail	Description of the current opt status for the customer.	string	true	"optStatusDetail": "OPTED_IN"
primaryContact	id	The identifier of the person assigned to the Hi Marley case.	string	false	"id": "18576b89-cd47-4dae-82d0-35ac08ec6387"
	first	The first name of the person assigned to the Hi Marley case.	string	false	"first": "Joe"
	last	The last name of the person assigned to the Hi Marley case.	string	false	"last": "Loop"
	email	The email of the person assigned to the Hi Marley case.	string	false	"email": "[e-mail]"
	role	The role of the person assigned to the Hi Marley case.	string	false	"role": "operator"
createTime		The time of the case creation.	smalldatetime	true	"createTime": "2022-05-26T12:24:45.562Z"
referenceId		The case reference identifier for the Hi Marley Case. The referenceId will equal claim number if the case type = claim. The referenceId will equal Policy number if the case type = policy. The referenceId will equal the referenceId if case type = case	string	true	"referenceId": "0002383632"
privacy		The case privacy status. public private-redacted	enum	true	"privacy": "public"
marleyNumber		The assigned phone number from an organization pool used to conduct messaging for the current case.	string	true	"marleyNumber": "[phone]"
languagePreference		The preferred language for the current Hi Marley case.	enum	true	"languagePreference": "en"
secondaryOperators   (array)	id	The identifier of the person assigned to the Hi Marley case.	string	false	"id": "48e2ebc5-6055-4028-b384-66f03caba5th"
	first	The first name of the person assigned to the Hi Marley case.	string	false	"first": "Linda"
	last	The last name of the person assigned to the Hi Marley case.	string	false	"last": "Moon"
	email	The email of the person assigned to the Hi Marley case.	string	false	"email": "[e-mail]"
	role	The role of the person assigned to the Hi Marley case.	enum	false	"role": "operator"

 

Allow Multiple Cases: Request Path Variation

Typically, Hi Marley's case creation API limits the number of cases that can be created per phone number/claim number combination to one; this means you can only have one Hi Marley case per contact per claim.

However, you can circumvent this restriction by adding the "?allowMultiple=true" property to your case creation request path. By adding this, you can create more than one case per claim number/phone number combination.

https://integration.uat.marley.ai/api/case/actions/open?allowMultiple=true

 

Common Errors to Handle

• [404] Primary Contact Not Found -More Details

Landline

Description

The customer's mobile number has been verified as a landline through our SMS provider API.

Example 

{
   "errors" : [
      {
         "code" : "PhoneIsLandline",
         "category" : "DataIntegrityError",
         "retryable" : false,
         "status" : 400,
         "detail" : "The customer.mobile was a landline",
         "path" : "/case/actions/open",
         "method" : "POST",
         "requestId" : String - UUID
      }
   ]
}

Duplicate Case Exists

Description

The API request to create a case attempted to create a duplicate case based on the unique combination of the customer mobile number and either claimNumber or policyNumber (depending on caseType).

To note, though the error below will throw, if the customer object is changing with the same phone number (i.e first name), the Customer information will update accordingly. This ensures the current case reflects the latest data from the System of Record. 

 

Example - Duplicate Claim Case

{
    "errors": [
        {
            "status": 400,
            "category": "DataIntegrityError",
            "code": "ClaimExists",
            "detail": "Claim already exists for your requests customer mobile and reference combination.",
            "retryable": false,
            "requestId": "c441a746-d9db-4fdd-93c4-e18f59df1e33",
            "method": "POST",
            "path": "/case/actions/open"
        }
    ]
}

Branding Mismatch

Description

The brand that was included with the API Request is not a valid brand for the organization in Hi Marley

Possible Resolutions

• Resend API request with proper brand name
• Contact your Hi Marley CSM to add the new brand to your Hi Marley organization and resend the API request afterward.

Example

{
    "errors": [
        {
            "status": 400,
            "category": "DataValidationError",
            "code": "BrandingMismatch",
            "detail": "Brand: \"Lovable3\" not valid for org: 798f6745-d733-477f-acc4-c1c18hndgtw2. Use a valid brand to create case for org",
            "retryable": false,
            "requestId": "0bf4b5a7-3bec-4876-9f78-053dfd00f70f",
            "method": "POST",
            "path": "/case/actions/open"
        }
    ]
}

User is Opted Out

Description

The customer opted out of texting with Hi Marley. We are not allowed to create a case and send additional messages to that mobile number.

Example

{
   "errors" : [
      {
         "code" : "InvalidUser",
         "category" : "DataIntegrityError",
         "retryable" : false,
         "status" : 400,
         "detail" : "User is opted out.",
         "path" : "/case/actions/open",
         "method" : "POST",
         "requestId" : String - UUID
      }
   ]
}

User Not Found

Description

The Hi Marley Operator passed in the primarycontact field does not have a Hi Marley account.

Example

{
    "errors": [
        {
            "code": "UserNotFound",
            "category": "DataIntegrityError",
            "retryable": false,
            "status": 400,
            "detail": "No user found for primaryContact: {\"email\":\"[e-mail]\"}",
            "path": "/case/actions/open",
            "method": "POST",
            "requestId": "71ff6c6c-ef14-4eb0-af01-90ce9d1b40fb"
        }
   ]
}

Max Case Count

Description

The customer (mobile number) has hit the max case count threshold for 'Active'/Open Cases.  The default is 5, but can be increased.  This is tied to the number of 'Marley Numbers' for an Org in their number pool.

Example

{
    "errors": [
        {
            "code": "CreateCaseIssue",
            "category": "DataIntegrityError",
            "retryable": false,
            "status": 400,
            "detail": "Customer has maximum number of cases.",
            "path": "/case/actions/open",
            "method": "POST",
            "requestId": "8ef85df0-7633-41e8-bdc3-687e5b45923e"
        }
    ]
}

Implementation Recommendations

Pass Date of Loss to UTC

The Date of Loss field in the Case Creation request is processed by default in the UTC timezone. The Hi Marley browser will use the operator's timezone. This means that, if Date of Loss is not converted from your timezone, for example EST, to UTC, then a case could theoretically appear with a different timezone in the webapp compared to the Date of Loss passed via API. The Date of Loss field should be converted to the UTC timezone before sending the Case Creation API request to create a case.

Store caseData.id value 

After a successful API response, Hi Marley will respond with the data about the case that has been created including several new id values for different entities. 

The caseData.id value is a unique identifier for the Hi Marley case. We recommend storing this value in your system along with the associated system record (claim/policy) to enable other integrations that require this identifier to be included in the API request to ensure we trigger actions to the correct case (e.g operator reassignment, close/reopen case, send message). 

Implement Direct Hi Marley Chat Links

In most cases, integrations with case creation via API can benefit from exposing a redirect link from the carrier system using a direct chat URL to provide adjusters/agents an easy way to jump into a specific case in Hi Marley.

The direct Hi Marley chat link uses the casedata.id value attached to the chats URL: 

https://<webappurl>/chats/<caseData.id>

Example Direct URL (Production Environment)

https://chat.marley.ai/chats/712d7971-cw09-4221c-ace26-47271126a

 

Common Integration Patterns

• Online FNOL Form: Embed Hi Marley Open Case API call into online FNOL process if the customer indicates texting as the preferred method of communication.
• Implement Open Case API call to execute on a button press associated with a participant from your system in a claim or policy .

Related Feature Integration Articles

• Integrating Hi Marley Translate
• Integrating Secondary Operator Management
• Integrating Case Visibility