Introduction

This documentation describes a subset of the API calls that will be most useful to developers looking to integrate with Mural Health’s system. This documentation will not go into details regarding Mural Health’s set up of client, contract, trial, site, etc. and the relationship between all of them. For this, please reference the 'Entities' section of Mural Health API library. Additionally, if there are any questions regarding definitions of APIs or endpoints, please search in the library. If the client is setting up the trial further documentation will be provided.

Registration

For a participant to be registered to a site for Mural Link, the add_particpant function and enroll must be called.The fields required to register a participant are first_name, last_name,email and dob. Then, the enroll function must be called once for each trial that the participant is to be enrolled in. This allows a single participant to be enrolled in multiple trials, either consecutively or concurrently. For clarification, the participant_uid is assigned dynamically by us. The subject_id is the randomization ID assigned to the participant by the sponsor.

The integrating client will then return the particpant_uid to Mural Health to be stored. Once this happens, Mural Health can then create a deep link to log the participant in directly to Mural Link without the need for a specific username or password. A conversation between developers should happen regarding whether keys can be exchanged in order to allow for this deep link to perpetually exist in the integrating client’s app.

Add Participant

Request

{
    "action": "add_participant",
    "session_id": "2Ip3OwmCJYQ6i0TVgWmqvd3IAKj",
    "payload": {
        "site_uid": "2Ip3OyDvhe1rWQT2HxHP6wwgBLj",
        "first_name": "Rebecca",
        "last_name": "Sears",
        "email": "Rebecca.Sears@example.com",
        "dob": "1981-09-21",
        "phone": "(792) 333-0323",
        "email_enabled": true,
        "address": {
            "street1": "1061 Bryant Blvd",
            "street2": "",
            "city": "Albany",
            "state": "NY",
            "post_code": "12212"
        },
        "emergency_contact": "Joe Pesci",
        "emergency_phone": "(212) 555-1212"
    }
}

Response

{
    "action": "add_participant",
    "payload": {
        "uid": "2Ip3OyNHFvKNVlqpox74u1MbW2q",
        "email": "rebecca.sears@example.com",
        "emergency_contact": "Joe Pesci",
        "emergency_phone": "(212) 555-1212",
        "enrollment_date": "2022-12-12",
        "first_name": "Rebecca",
        "last_name": "Sears",
        "phone": "(792) 333-0323",
        "site_uid": "2Ip3OyDvhe1rWQT2HxHP6wwgBLj",
        "time_zone": "America/New_York",
        "dob": "1981-09-21",
        "address": {
            "uid": "2Ip3OwEsewrRQb4HVEkZZlQTPdl",
            "street1": "1061 Bryant Blvd",
            "city": "Albany",
            "state": "NY",
            "post_code": "12212"
        }
    },
    "status_code": 200,
    "message": "participant added",
    "request_id": "2Ip3OqxR4K2Ydlkf7XtYKbHBcJf",
    "roles": [
        "admin"
    ],
    "user_type": "external"
}

Enroll

Request

{
    "action": "enroll",
    "session_id": "2Ip3OrvRX1UgkoYLdh2tVyV2WCK",
    "payload": {
        "participant_uid": "2Ip3OugTEw151vSFgMX2VcuuExg",
        "trial_uid": "2Ip3OtPLk0AjVzJaTYIchnQuClr",
        "site_uid": "2Ip3OtOIC4nJFRlpleCFXTyoQMM",
        "subject_id": "9999"
    }
}

Response

{
    "action": "enroll",
    "payload": {
        "uid": "2Ip3OxPwQICQ6u9zRfO0m7QQwGa",
        "trial_uid": "2Ip3OtPLk0AjVzJaTYIchnQuClr",
        "trial_site_uid": "2Ip3OsaLkGbtZ0m0Rj2IyuPhkU5",
        "participant_uid": "2Ip3OugTEw151vSFgMX2VcuuExg",
        "patient_uid": "2Ip3OugTEw151vSFgMX2VcuuExg",
        "subject_id": "9999",
        "payment_type_uid": "",
        "status": "enrolled",
        "payment_address": {},
        "patient": {
            "uid": "2Ip3OugTEw151vSFgMX2VcuuExg",
            "email": "savannah.lambert@example.com",
            "emergency_contact": "Joe Pesci",
            "emergency_phone": "(212) 555-1212",
            "enrollment_date": "2022-12-12",
            "first_name": "Savannah",
            "last_name": "Lambert",
            "phone": "(400) 892-6548",
            "user_uid": "2Ip3Oujld2998rWJtffebyFsqbm",
            "dob": "1999-09-24",
            "address": {
                "uid": "2Ip3Ox3dOjE8SXr60q5yE3enuNF",
                "street1": "626 Henly Dr",
                "city": "Beloit",
                "state": "WI",
                "post_code": "53511"
            }
        },
        "trial_site": {
            "uid": "2Ip3OsaLkGbtZ0m0Rj2IyuPhkU5",
            "site_uid": "2Ip3OtOIC4nJFRlpleCFXTyoQMM",
            "trial_uid": "2Ip3OtPLk0AjVzJaTYIchnQuClr",
            "site": {
                "uid": "2Ip3OtOIC4nJFRlpleCFXTyoQMM",
                "name": "Sherman Clinic"
            },
            "trial": {
                "uid": "2Ip3OtPLk0AjVzJaTYIchnQuClr",
                "contract_uid": "",
                "name": "Trial Hunter-82",
                "protocol_id": "XK3833-39530",
                "contract": {
                    "uid": "",
                    "client_uid": "",
                    "name": "",
                    "client": {
                        "uid": "",
                        "name": "",
                        "address": {}
                    }
                }
            }
        },
        "user_uid": "2Ip3Oujld2998rWJtffebyFsqbm"
    },
    "status_code": 200,
    "message": "OK",
    "request_id": "2Ip3OwDzNiPLLCHXu9XYgKAST3s",
    "roles": [
        "admin"
    ],
    "user_type": "external"
}

After being registered, the participant can use the provided deep link to login to the Mural Link app, where they can select their preferred payment method. For more information on the payment method selection process, please see the Mural Health API library for details on the get_payment_types and set_payment_type functions.

If a participant’s enrollment status changes during the trial, the set_enrollment_status function can be used to update the system about whether the participant is no longer active in the trial, for example due to dropping out or finishing the trial. The allowed values are enrolled, dropped, and completed.

Set Enrollment Status

Request

{
    "action": "set_enrollment_status",
    "session_id": "2Ip3P22DO8Q7Y2MTUmunLRqwb1g",
    "payload": {
        "status": "completed",
        "trial_uid": "2Ip3Oyp3wJOXsBEH7Oo3hMY2h48",
        "participant_uid": "2Ip3P08V65oeCa5oybuByXbyBZ2"
    }
}

Response

{
    "action": "set_enrollment_status",
    "payload": {
        "uid": "2Ip3P1v6HjTWywGqpog8jzucAju",
        "trial_uid": "2Ip3Oyp3wJOXsBEH7Oo3hMY2h48",
        "trial_site_uid": "2Ip3P4wkOqkD8oSHTtTwF09wsRs",
        "participant_uid": "2Ip3P08V65oeCa5oybuByXbyBZ2",
        "patient_uid": "2Ip3P08V65oeCa5oybuByXbyBZ2",
        "subject_id": "8038",
        "payment_type_uid": "",
        "status": "completed",
        "payment_address": {},
        "patient": {
            "uid": "2Ip3P08V65oeCa5oybuByXbyBZ2",
            "email": "jeremy.jacobson@example.com",
            "emergency_contact": "Joe Pesci",
            "emergency_phone": "(212) 555-1212",
            "enrollment_date": "2022-12-12",
            "first_name": "Jeremy",
            "last_name": "Jacobson",
            "phone": "(476) 180-5573",
            "user_uid": "2Ip3P3tfbOVX8BsR497xSAYmH8R",
            "dob": "1997-06-26",
            "address": {
                "uid": "2Ip3P685dwaBektDI6ipXIDVgi0",
                "street1": "1020 Burnet Dr",
                "city": "Phoenix",
                "state": "AZ",
                "post_code": "85026"
            }
        },
        "trial_site": {
            "uid": "2Ip3P4wkOqkD8oSHTtTwF09wsRs",
            "site_uid": "2Ip3OyfhCybA7pAqWgCmNXXFJJc",
            "trial_uid": "2Ip3Oyp3wJOXsBEH7Oo3hMY2h48",
            "site": {
                "uid": "2Ip3OyfhCybA7pAqWgCmNXXFJJc",
                "name": "Mercer Clinic"
            },
            "trial": {
                "uid": "2Ip3Oyp3wJOXsBEH7Oo3hMY2h48",
                "contract_uid": "",
                "name": "Trial Mayer-99",
                "protocol_id": "XK9599-13021",
                "contract": {
                    "uid": "",
                    "client_uid": "",
                    "name": "",
                    "client": {
                        "uid": "",
                        "name": "",
                        "address": {}
                    }
                }
            }
        }
    },
    "status_code": 200,
    "message": "OK",
    "request_id": "2Ip3P3HJxLSLPnLo0ldWsk1SfBy",
    "roles": [
        "admin"
    ],
    "user_type": "external"
}

Pay Patients

When Mural Health sets up the trial, they will also create a milestone schedule. Please refer to Mural Health API library add_milestone and payment_schedule to learn more. After creating milestones, Mural Health will send over the milestone_uid for each milestone event so that the integrating party can trigger the correct milestone_payment once the event has occurred in their own system. Once milestone_payment is triggered, a particpant will be allowed to claim their payments within the Mural Link app through the claim_payments API.

Milestone payments

Request

{
    "action": "milestone_payment",
    "session_id": "2Ip3PYi4EibrsZQZKZpEi5q8BPE",
    "payload": {
        "participant_uid": "2Ip3Pag8jtOO91Z08AAGfRc9dWU",
        "milestone_uid": "2Ip3PaPOV6tAEaHVCX6aREyDixw",
        "note": "test suite"
    }
}

Response

{
    "action": "milestone_payment",
    "payload": {
        "uid": "2Ip3PVlZtGu0Q8QdRlkkQJTo9xE",
        "enrollment_uid": "2Ip3PXL4MNFXuaDDbNyBNcQ5hGx",
        "payment_type": "milestone",
        "milestone_uid": "2Ip3PaPOV6tAEaHVCX6aREyDixw",
        "amount": 75,
        "currency": "USD",
        "note": "test suite",
        "status": "unclaimed",
        "created_by": "admin",
        "creator": {
            "uid": "",
            "email": "",
            "first_name": "",
            "last_name": "",
            "address": {},
            "email_verified": false,
            "sms_verified": false,
            "patient": {
                "address": {}
            },
            "caregiver": {
                "address": {},
                "patient": {
                    "address": {}
                }
            },
            "email_enabled": false,
            "sms_enabled": false,
            "push_enabled": false
        },
        "enrollment": {
            "payment_type_uid": "",
            "payment_address": {},
            "patient": {
                "address": {}
            },
            "trial_site": {
                "site": {
                    "uid": "",
                    "name": ""
                },
                "trial": {
                    "uid": "",
                    "contract_uid": "",
                    "name": "",
                    "protocol_id": "",
                    "contract": {
                        "uid": "",
                        "client_uid": "",
                        "name": "",
                        "client": {
                            "uid": "",
                            "name": "",
                            "address": {}
                        }
                    }
                }
            }
        },
        "milestone": {
            "uid": "",
            "effective_date": "0001-01-01T00:00:00Z",
            "milestone": "",
            "amount": 0,
            "currency": "",
            "sort_order": 0
        }
    },
    "status_code": 200,
    "message": "OK",
    "request_id": "2Ip3PUXOWwz31ax9zFWZulTGmkW",
    "roles": [
        "admin"
    ],
    "user_type": "external"
}

Payment History and Reporting

There are a few options for the integrating client to see payment history and reporting. The first is to access the Mural Link client portal. An alternative would be to add Mural Link’s data via API into the integrating client’s own system. To do this, the trial_payment_report function can be used to get the overall payment history for a trial. The get_particpant_payments function can be used to see a particular participant’s payment history. Other reports such as funding balance can be pulled with the funding_report function.

Trial Payment Report

Retrieve all payments for a clinical trial.

Request

{
    "action": "trial_payment_report",
    "session_id": "2Ip3PiZR1nDnTyvLkukHz5lHih4",
    "payload": {
        "trial_uid": "2Ip3PdwdcymzDHoOT3szz4f7z42",
        "format": "csv"
    }
}

Response

{
    "action": "trial_payment_report",
    "payload": "http://api:6666/reports/2Ip3PihpEBiRLWITNGECpNUcxkE",
    "status_code": 200,
    "message": "OK",
    "request_id": "2Ip3PgLSVo4f5o1E9yUDFwOBQQC",
    "roles": [
        "admin"
    ],
    "user_type": "external"
}

Get Participant Payments

Request

{
    "action": "get_participant_payments",
    "session_id": "2Ip3PYi4EibrsZQZKZpEi5q8BPE",
    "payload": {
        "participant_uid": "2Ip3Pag8jtOO91Z08AAGfRc9dWU",
        "trial_uid": "2Ip3PUP40puFiq13rUM4U2RMucl"
    }
}

Response

{
    "action": "get_participant_payments",
    "payload": [
        {
            "uid": "2Ip3PVlZtGu0Q8QdRlkkQJTo9xE",
            "enrollment_uid": "2Ip3PXL4MNFXuaDDbNyBNcQ5hGx",
            "payment_type": "milestone",
            "milestone_uid": "2Ip3PaPOV6tAEaHVCX6aREyDixw",
            "amount": 75,
            "currency": "USD",
            "note": "test suite",
            "status": "unclaimed",
            "date": "2022-12-12",
            "created_by": "admin",
            "creator": {
                "uid": "",
                "email": "",
                "first_name": "",
                "last_name": "",
                "address": {},
                "email_verified": false,
                "sms_verified": false,
                "patient": {
                    "address": {}
                },
                "caregiver": {
                    "address": {},
                    "patient": {
                        "address": {}
                    }
                },
                "email_enabled": false,
                "sms_enabled": false,
                "push_enabled": false
            },
            "enrollment": {
                "uid": "2Ip3PXL4MNFXuaDDbNyBNcQ5hGx",
                "subject_id": "3420",
                "payment_type_uid": "",
                "status": "enrolled",
                "payment_address": {},
                "patient": {
                    "address": {}
                },
                "trial_site": {
                    "site": {
                        "uid": "",
                        "name": ""
                    },
                    "trial": {
                        "uid": "2Ip3PUP40puFiq13rUM4U2RMucl",
                        "contract_uid": "",
                        "name": "Trial Gibbs-86",
                        "protocol_id": "XK5747-27611",
                        "contract": {
                            "uid": "",
                            "client_uid": "",
                            "name": "",
                            "client": {
                                "uid": "",
                                "name": "",
                                "address": {}
                            }
                        }
                    }
                }
            },
            "created": "2022-12-12",
            "updated": "2022-12-12",
            "milestone": {
                "uid": "2Ip3PaPOV6tAEaHVCX6aREyDixw",
                "effective_date": "2022-12-12T17:04:33.335885Z",
                "milestone": "First Visit",
                "amount": 75,
                "currency": "USD",
                "sort_order": 0
            }
        }
    ],
    "status_code": 200,
    "message": "OK",
    "request_id": "2Ip3PbO8gTnkfTIwh4rXYJ3DVFh",
    "roles": [
        "admin"
    ],
    "user_type": "external"
}

Funding Report

Request

{
    "action": "funding_report",
    "session_id": "2Ip3PexPkuzH0cZE3YZKjNpwHmA",
    "payload": {
        "contract_uid": "2Ip3PbbYeRMzhAom87MXMqUHCQY",
        "format": "xlsx"
    }
}

Response

{
    "action": "funding_report",
    "payload": "http://api:6666/reports/2Ip3PncpYp92lfecYH0dZsdRSJq",
    "status_code": 200,
    "message": "OK",
    "request_id": "2Ip3Pmgeb6vnwinfLFWWUEJepOG",
    "roles": [
        "admin"
    ],
    "user_type": "external"
}