Introduction

The purpose of a public API into Marley is to enable carriers to quickly integrate their systems with Marley, enabling operators (adjusters/underwriters/customer service reps/etc.) to seamlessly include communicating via Marley into their everyday workflow. There are many API's built to help with this process and minimize any manual work on the part of the operator.

From time to time as Hi Marley releases new features additional fields will be added to API responses and webhook payloads. API users and Webhook consumers should be flexible enough to accept additive changes to the payload. Any breaking changes (meaning changes to the structure of the payload, removal of fields or events, and changes to datatypes) will be handled with versioning of APIs and webhooks.

Technical Overview
API Throttling
Endpoint Specific Articles List
Differences Between Hi Marley API and Webapp
Other Integration related Overviews
Response Headers

Technical Overview

Our public API is a REST API that uses the GET, POST, PUT, DELETE methods to enable our customers to automate actions that are similarly taken within our WebApp UI.

Other aspects to note about our API:

Accepts and returns payloads in JSON format
Secured with TLS
Requires API Key authentication in each request under the header, x-api-key
Includes API throttling per second (more information below)

Public Technical Documentation available on Postman

API Throttling

The Hi Marley Public API will include a throttle limit to ensure the concurrent load of API requests per API Key doesn't adversely affect our system. Hitting the throttle limit will result in an error with the category ThrottleError and code THROTTLED.

This limit was set based on current customer implementation in production to prevent the need for implementation changes.

Throttling Settings:

20 requests per second average
15 concurrent requests (burst)

API Endpoint Specific Articles

Below you will find specific information on API endpoints that are commonly used in Carrier integrations. All available endpoints can be discovered in our technical Postman documentation.

API Actions Group	API Endpoint Article	Description	Integration Guide
Case Management	Case Creation	Create a Case in Hi Marley
	Close Case	Close an Existing Case
	Reopen Case	Reopen an Existing Case
	Reassign Case	Reassign an Existing Case
	Update Case by ID	Update Case fields for a specific case

Retrieve Case Data	Get Case By Case ID	Retrieve Case details using the unique ID
	Get Case By Reference ID	Retrieve Case details using the reference ID
	Get Case Notes	Retrieve Case Notes for a single case
	Get Case IDs for Cases Updated	Get Updated Cases within a day range
	Get Active Cases by ID	Get open cases for a user by their UUID, Email, or Mobile Number
	Get Active Cases by Email
	Get Active Cases by Mobile Number

Send Message	Send Message	Send text as a message from either an adjuster or Marley
	Send Template Message	Send variables on an existing template to generate a message from either an adjuster or Marley
	Resend Welcome Message	Trigger the welcome message on a case
	Send Survey Message	Trigger the 2-question survey flow

Operator Management	Create Operator	Create a new operator account.
	Update Operator	Update existing operator account.
	Delete Operator	Delete an operator account.

Manage Scheduled Messages	Create Scheduled Message	Create a new message to be sent at a future time
	Get All Scheduled Messages for a Case	Retrieve all messages scheduled for a case
	Delete Scheduled Message	Delete a specific message that is scheduled (but not sent)

Transcript Actions	Download Case Transcript (PDF or JSON)	Generate a PDF or JSON transcript for a case
Transcript Actions	Push Transcript to SFTP	Generate a PDF transcript and push it to the Hi Marley SFTP site for batchprocessing	SFTP Integration for Case Transcripts and Media Files

Group Management	Create Group	Create a group	Integrating Group Management
	Update Group	Update a group
	Delete Group	Delete a group
	Retrieve Group by ID	Retrieve a single group
	Retrieve All Groups in your Organization	Retrieve all groups

Differences Between Hi Marley API and Webapp

Hi Marley has certain functionality that are not supported through our API but are achievable through the Hi Marley webapp.

Insights & Analytics

The Hi Marley Insights tab within the webapp is where a Hi Marley user with the correct permissions can gather analytics information about their organization's Hi Marley usage. More information is available on this page: Hi Marley Org Insights

Currently, we do not have an API or a webhook that provides equivalent data or analytics. The best place for data and analytics (whether your adjusters are operating via the webapp or via an integration) is through the Insights tab in the Hi Marley webapp.

Multiple Cases with the same Phone Number/Claim Number Combination

Through Hi Marley's API, operators cannot open multiple with the same phone number and claim number combination. That means that, if created via API, only one Hi Marley case can be created per claim with a single individual; multiple cases can be created on a claim with multiple phone numbers, but not multiple cases with the same individual. This can be achieved by using the Hi Marley webapp.

Updating the Customer

Through our API, operators cannot change the policyholder's phone number, name, additional info on a Hi Marley case. If the phone number needs to be updated via API, the operator should close the existing case with the incorrect phone number and create a new case with the correct phone number.

Phone numbers can be updated in the Hi Marley webapp, but this will not trigger a webhook; this means that your claim system and Hi Marley could have two different phone numbers listed for the same case. That is why our general recommendation is to have adjusters close a case with the incorrect phone number and open a new case rather than to replace the phone number on an existing case.

Other Integration-Related Overviews

Webhook Overview: Learn more about our event-driven webhooks that can automatically trigger key workflow actions like uploading transcripts, posting user data etc.

SFTP Overview: Learn more about the Hi Marley SFTP site offered to all of our customers for transcript and media uploads.

Response Headers

All Hi Marley Public API responses will include the following headers:

X-Frame Options: DENY
Content Security Policy: default-src 'self'
Strict-Transport-Security: max-age= 63072000; includeSubDomains
X-Content-Type-Options: nosniff
Referrer Policy: strict-origin-when-cross-origin

These headers are included to enhance our Public API's security posture. These headers enforce secure behavior and ensure safe interactions with our API.

Are we missing something? Any Questions?

This documentation covers some of the key aspects of our API, endpoints, and use cases. Our documentation is always changing and growing as we learn what information is useful for our customers.

Please feel free to contact us with any questions around integrations that may not be addressed in this article

API Overview