Feature Blocks

The JSON object contains the following elements:

• The heading of the Module
  
• A list of menu items - each item contains a url link for each of the subsections within the same module indexed by its relative heading
  
• breadcrumbs - each item contains a heading and a url link for each of the subsections within the same module
  
• The main content for the subsection requested

It looks a bit like this:

    
    {
        "heading": "This Is Me",
        "menu_items": {},
        "breadcrumbs": {},
        "main_content": {}
    }
    
    

• The heading of this subsection
  
• An array of input fields

It looks a bit like this:

    
    {
        "heading": "Personal Details",
        "input_fields": {}
    }   
    
    

Each element in the input fields array represents a question/answer pair and is structured as follows:

• Each is indexed by the question_id. This is required when making a request to update the input values.
  
• The type value tells us how the question should function in the UI.
  
• The label is the label that should appear in the UI. The way the question is phrased. There are options here for a person-centered value "citizen" or a more formal wording that might be used in the context of a service provider app "service-provider".
  
• The validation_rules is an array containing validation codes which can be used to determine how the answer/value submitted in a PUT should be formatted.
  
• The input - the answer/value that is stored in the person’s PDS.

It looks something like:

    
    "also_known_as": {
        "type": "input-text",
        "label": {
            "citizen": "How else am I known",
            "service_provider": "Also known as (AKA)"
        },
        "validation_rules": [
            "is_text"
        ],
        "input": "Bobbi"
    }
    
    

Please click on the tabs below for more detail about each element of a single input field:

        
        "add_image": {
            "file": {
                "type": "image",
                "label": {
                    "citizen": "File",
                    "service-provider": "File"
                },
                "validation_rules": [
                    "base64_encoded",
                    "max_10_mb"
                ]
            },
            "file_name": {
                "type": "input-text",
                "label": {
                    "citizen": "File name",
                    "service-provider": "File name"
                },
                "validation_rules": [
                    "is_text"
                ]
            },
            "description": {
                "type": "input-text",
                "label": {
                    "citizen": "Description",
                    "service-provider": "Description"
                },
                "validation_rules": [
                    "is_text"
                ]
            }
        }
        
        

When updating the input field data for a given subsection, you must include the data you want to update in the body of the request. At its most basic, the body is formed of an array of values indexed by the ‘question_id’ that each input value relates to. For example:

    
    {
        "what_do_i_like_socially_environmentally" : ["Big groups"],
        "positive_qualities"  : "happy",
        "challenging_about_me"  : "impatient",
        "good_day_looks_like" : "Seeing family and friends",
        "bad_day_looks_like" : "having nothing to do",
        "area_of_my_goals" : ["Healthy eating", "Relaxation"],
        "like_to_get_back_to" : "studying",
        "achieve_in_future" : "visit my daughter in spain",
        "more_about_my_goals" : "I would like to get better at spanish so that I can understand my grandchildren better"
    }
    
    

The question_ids that you can see as indexes in that example match the question_ids you will get in the GET response, as described in the section on GET.

The validation rule in the form data tells us how an answer should be formatted. See the following section on validation rules for more information.

The table linked here describes the validation rules mapped to their codes. You will see these codes in the input fields within a subsection templates data structure.

Currently, if you are working with the /calendar/add-appointment route, you will also need access to the Referrals Feature Block, which you can find out about HERE. An appointment exists in the context of a referral, so we need to link the appointment to the referral by storing the referral id along with the appointment.

A request to this route will return all calendar events.

The following is an example payload of what you should expect to be returned on a GET all events request:

Example payload

{
    "success": 1,
    "events": [
        {
            "id": "70",
            "instance": "0",
            "source": "3939-40104",
            "created_timestamp": "1759838783",
            "updated_timestamp": "1759838783",
            "external_uid": "45",
            "title": "Hot stone Massage",
            "description": "",
            "start_timestamp": "1759818600",
            "end_timestamp": "1759908600",
            "organiser": "Ember Stone Wellness",
            "attendee": "Sophie Marlowe",
            "status": "INVITED",
            "location": "Ember Stone Wellness",
            "type": "Appointment",
            "tags": null,
            "trigger": null,
            "action": null,
            "reminder_description": null,
            "context_name": "Ember Stone Wellness"
        },
        {
            "id": "76",
            "instance": "0",
            "source": "3939-40104",
            "created_timestamp": "1761732677",
            "updated_timestamp": "1761732677",
            "external_uid": "",
            "title": "Oakwhistle village coffee morning",
            "description": "Coffee morning with my neighbours",
            "start_timestamp": "1762155000",
            "end_timestamp": "1762158600",
            "organiser": "Oakwhistle community members",
            "attendee": "",
            "status": "TENTATIVE",
            "location": "Oakwhistle community hall",
            "type": "",
            "tags": null,
            "trigger": null,
            "action": null,
            "reminder_description": null
        }
    ]
}

Reading the results

Events are returned in ascending order by start_timestamp i.e. the time the event is due to start.

Active fields that may have been written to on a POST/PUT request:

• external_uid, this links the event to the context that it was created in. For example this will store the value submitted as context_id on a POST Appointment request.
• title, the title given to the event e.g. "Oakwhistle village coffee morning"
• description, the description of the event
• start_timestamp, the time the event starts, stored as a unix timestamp
• end_timestamp, the time the event ends, stored as a unix timestamp
• organiser, who organised the event
• attendee, who is attending the event
• status, the status of the event e.g. "TENTATIVE"
• location, where is the event happening
• type, what type of event is this e.g. "Appointment"

Fields that are auto-populated on a POST/PUT request (as appropriate):

• id, autoincremented identifier of the record
• instance, the instance of the record
• source, the connection data for the connection that the record was created within
• created_timestamp / updated_timestamp, when the record was created/updated
• context_name, not always present in the payload, however this is the name of the organisation that the event relates to

Inactive fields that are "coming soon":

• tags
• trigger
• action
• reminder_description

A request to this route will return all appointments for a given context.

An Appointment must exist within a certain context e.g. a Referral. So for example, let's say a person has been referred to a service, any appointments made in the context of that referral will be linked to it by the id of that referral.

To get appointments linked to a given context e.g. linked to a Referral this route requires to know the context that it was created within, along with the specific instance of that context.

Current valid contexts are as follows:

• referral — for Referral Management, visit the Referrals Feature Block documentation here.

The request must include query parameters:

• context, the context that the appointment exists within.
• context_id, the specific instance of that context that the appointment relates to.

The following is an example payload of what you should expect to be returned on a GET appointments request:

Example payload

{
    "success": 1,
    "appointments": [
        {
            "id": "56",
            "instance": "0",
            "source": "3939-40102",
            "created_timestamp": "1758120493",
            "updated_timestamp": "1758120493",
            "external_uid": "63",
            "title": "Occupational Health Initial Appointment",
            "description": "One-on-one chat to discuss expectations and plan our time together",
            "start_timestamp": "1754289000",
            "end_timestamp": "1754292600",
            "organiser": "Evan Harper",
            "attendee": null,
            "status": "INVITED",
            "location": "SafeSteps Occupational Care",
            "type": "Appointment",
            "tags": null,
            "trigger": null,
            "action": null,
            "reminder_description": null
        }
    ]
}

Reading the results

Events are returned in ascending order by start_timestamp i.e. the time the event is due to start.

Active fields that may have been written to on a POST/PUT request:

• external_uid, this links the event to the context that it was created in. For example this will store the value submitted as context_id on a POST Appointment request.
• title, the title given to the event e.g. "Oakwhistle village coffee morning"
• description, the description of the event
• start_timestamp, the time the event starts, stored as a unix timestamp
• end_timestamp, the time the event ends, stored as a unix timestamp
• organiser, who organised the event
• attendee, who is attending the event
• status, the status of the event e.g. "TENTATIVE"
• location, where is the event happening

Fields that are auto-populated on a POST/PUT request (as appropriate):

• id, autoincremented identifier of the record
• instance, the instance of the record
• source, the connection data for the connection that the record was created within
• created_timestamp / updated_timestamp, when the record was created/updated
• type, this will always default to "Appointment"

Inactive fields that are "coming soon":

• tags
• trigger
• action
• reminder_description

This route enables adding generic calendar events, i.e., ones that are not linked to a specific context. The body of the request should contain the following field/values.

Required Fields

• title — The title of the appointment, e.g., “Initial meeting”.
• start_timestamp — The time the appointment starts as a Unix timestamp.
• end_timestamp — The time the appointment ends as a Unix timestamp.
• status — The status of the appointment, e.g., “INVITED”. If no value is passed in the request, this will default to TENTATIVE.

Optional Fields

• description — A description of the appointment, e.g., “Meeting to discuss expectations”.
• organiser — The person/entity that created the appointment/event.
• attendee — Who the appointment is with, e.g., “Ellen Sykes”.
• location — Where the appointment/event will take place.
• type — The type of event, e.g., “Appointment”.

Example Request Body

{
    "title": "Lunch with Ellen",
    "start_timestamp": "1754289000",
    "end_timestamp": "1754292600"
}

An appointment can be created within a given context, e.g., a referral. When making a request to add an appointment, the body of the request should contain the following field/values.

Required Fields

• title — The title of the appointment, e.g., “Initial meeting”.
• start_timestamp — The time the appointment starts as a Unix timestamp.
• end_timestamp — The time the appointment ends as a Unix timestamp.
• status — The status of the appointment, e.g., “INVITED”.
• context — The context within which the appointment has been made, e.g., “referral”.
• context_id — The specific ID for the given context that the appointment relates to, e.g., 5.

Optional Fields

• description — A description of the appointment, e.g., “Meeting to discuss expectations”.
• organiser — The person/entity that created the appointment/event.
• attendee — Who the appointment is with, e.g., “Emma White, Physiotherapist”.
• location — Where the appointment/event will take place.

Example Request Body

In this example, the PDS owner has been referred to a service and the referral has ID 8. The service provider then invites the PDS owner to attend an appointment “Initial meeting with Physio”. Submitting the context referral and context_id 8 links the appointment to this specific referral. This means that all appointments relating to this specific referral can be grouped together.

{
    "context": "referral",
    "context_id": 8,
    "title": "Initial meeting with Physio",
    "start_timestamp": "1754289000",
    "end_timestamp": "1754292600",
    "status": "INVITED"
}

Any event can be updated via this route by passing the ID of the event to update along with the data to update in the body of the request. The ID must be for an existing event. The body of the request should contain the following field/values.

Required Fields

• id — The ID of the event to update.

Optional Fields

At least one of the following optional fields should also be submitted:

• title — The title of the appointment, e.g., “Initial meeting”.
• start_timestamp — The time the appointment starts as a Unix timestamp.
• end_timestamp — The time the appointment ends as a Unix timestamp.
• status — The status of the appointment, e.g., “INVITED”. If no value is passed in the request, this will default to TENTATIVE.
• description — A description of the appointment, e.g., “Meeting to discuss expectations”.
• organiser — The person/entity that created the appointment/event.
• attendee — Who the appointment is with, e.g., “Ellen Sykes”.
• location — Where the appointment/event will take place.
• type — The type of event, e.g., “Appointment”.

Use this route to delete an event by passing the id in the body of the request. The id must be for an existing event record.

This route retrieves all timeline items. The timeline is arranged in ascending order by item_timestamp. The data returned for each record is a brief containing only headline information. A full record for each item can be requested using the /timeline/single-item endpoint.

Example response:

{
    "success": 1,
    "timeline": [
        {
            "id": 2,
            "feature_block": "referrals",
            "feature_block_id": "32",
            "start_timestamp": "14th January 2022, 9:30 am",
            "item_timestamp": "1642137822",
            "service_description": "Assistance with job placement and CV review",
            "service_name": "Employment Support Program",
            "contact_name": "John Smith",
            "contact_title": "Career Advisor",
            "memo": "Client requires additional guidance for CV formatting and interview prep",
            "status": "Accepted"
        },
        {
            "id": 3,
            "feature_block": "secure_messages",
            "feature_block_id": "1",
            "start_timestamp": "8th July 2025, 3:12 pm",
            "item_timestamp": "1751987551",
            "created_timestamp": "1751987551",
            "message_from": "",
            "message_to": "Daniel Johnson",
            "message_content": "Hello, how are you?"
        },
        {
            "id": 4,
            "feature_block": "calendar",
            "feature_block_id": "82",
            "start_timestamp": "4th August 2025, 7:30 pm",
            "item_timestamp": "1754289000",
            "end_timestamp": "4th August 2025, 10:30 pm",
            "title": "Landless gig",
            "location": "Usher Hall",
            "organiser": "",
            "description": "Landless gig with Ellen",
            "status": "TENTATIVE",
            "duration_string": "3 hours",
            "duration_of_event": 0.125
        }
    ]
}

Reading the results

Each timeline item returned is a brief of the data for that given item. Currently, three different types of timeline items are returned, but some fields are common to each:

• id, the timeline ID
• feature_block, the feature block that this item belongs to, e.g., "referrals"
• feature_block_id, the ID of this item as it pertains to its feature block
• start_timestamp, when the item is initiated as a human-readable value. The meaning of this will differ according to the type of data record:
  • "referrals": the time the referral was made
  • "secure_messages": the time the message was sent or received
  • "calendar": the time the event is due to start
• item_timestamp, the Unix timestamp version of start_timestamp

Additional fields vary depending on which feature block the item pertains to:

• "referrals"
  • service_description: description of the service the referral relates to
  • service_name: name of the service the referral relates to
  • contact_name: name of the contact for this referral
  • contact_title: title of the contact for this referral
  • memo: any notes relating to this referral
  • status: status of the referral, e.g., "Accepted"
• "secure_messages"
  • created_timestamp: time the message was sent/received as a Unix timestamp
  • message_from: who the message is from (empty if this is a sent message)
  • message_to: who the message is to (empty if this is a received message)
  • message_content: the content of the message, i.e., what the message says
• "calendar"
  • end_timestamp: the time the event is due to end as a Unix timestamp
  • title: the title of the event
  • location: where the event is located
  • organiser: who organised the event
  • description: a description of the event
  • status: the status of the event, e.g., "TENTATIVE"
  • duration_string: how long the event lasts as a human-readable string, e.g., "3 days"
  • duration_of_event: the calculable duration of the event in terms of days, i.e., how many days long the event is

This route supports requests for a single timeline item. In order to make a successful request to this route the following query parameters must be included:

• feature_block, tells us which feature block the item belongs to
• feature_block_id, tells us the specific id for that item as it pertains to its feature block

Upon requesting a single item from the timeline, a full record will be returned that often includes additional data points to those returned on a GET /timeline request.

Example response:

In this example, a request has been made as follows:

https://api.mydex.org/timeline/single-item?uid=3919&con_id=3919-67898&feature_block=secure_messages&feature_block_id=96

{
    "success": 1,
    "timeline_item": {
        "feature_block": "secure_messages",
        "feature_block_id": "96",
        "start_timestamp": "17th July 2025, 12:19 pm",
        "item_timestamp": "1752754774",
        "created_timestamp": "1752754774",
        "updated_timestamp": "1752754774",
        "conversation_id": "referral-0",
        "time_sent": "1752754774",
        "time_received": "",
        "message_from": "",
        "message_to": "Marco's Org",
        "message_content": "Hi there"
    }
}

To use this route you will need to pass a value for the org-id, the id allocated to your organisation.

For example, if your organisation ID is ‘1’ - this is the ID to use in the MRD Endpoint, like so:

The resulting payload should look something like this:

[
    {
        "id": "35",
        "organisation_id": "1",
        "service_id": "10",
        "service_name": "Support Plan Service",
        "service_email": "test2@gmail.com",
        "service_url": "https:\/\/carers.quarriers.org.uk\/services\/moray\/",
        "service_description": "Sign up here to get in touch with our team. They will help you create a support plan and look at what resources may be available to you. To get the most out of this, please complete the This is Me and My Supporting Role sections of your About Me.",
        "service_contact_number": "0771234567",
        "service_slug": "support-plan-service",
        "status": "Live",
        "service_start": "1725408000",
        "service_end": "1851638400",
        "created_timestamp": "1725437887",
        "updated_timestamp": "1725437915"
    }
]

The example above represents the ‘Live’ services from organisation with ID 1.

A request to this route will return all referrals.

The following is an example payload of what you should expect to be returned on a GET all referrals request:

Example payload

{
    "success": 1,
    "referrals": [
        {
            "id": "87",
            "created_timestamp": "1760439590",
            "service_id": "0",
            "service_name": "Community Wellness & Support Services",
            "service_description": "Provides emotional support, resource navigation, and guidance for individuals or families seeking help with stress, life challenges, or overall well-being.",
            "service_contact_number": "01620 482117",
            "service_email": "support@communitywellness.org",
            "service_url": "https://www.communitywellness.org",
            "type": "Self Referred",
            "status": "Referred"
        },
        {
            "id": "88",
            "created_timestamp": "1761124272",
            "service_id": "5",
            "service_name": "Integrated Mental Health Outreach",
            "service_description": "Offers accessible mental health support—such as counselling, check-ins, and referrals—aimed at reaching people in the community who may need early or ongoing assistance.",
            "service_contact_number": "01620 739660",
            "service_email": "contact@imhoutreach.org",
            "service_url": "https://www.imhoutreach.org",
            "type": "Self Referred",
            "status": "Accepted"
        },
        {
            "id": "89",
            "created_timestamp": "1761124823",
            "service_id": "5",
            "service_name": "Personal Growth & Counselling Center",
            "service_description": "A therapeutic service focused on helping individuals work through personal struggles, build coping skills, and foster long-term emotional and psychological growth.",
            "service_contact_number": "01620 214893",
            "service_email": "info@pgcounselingcenter.com",
            "service_url": "https://www.pgcounselingcenter.com",
            "type": "Self Referred",
            "status": "Referred"
        }
    ]
}

Reading the results

Each referral returned contains data about the service the referral relates to:

• service_id
• service_name
• service_description
• service_contact_number
• service_email
• service_url

As well as the specifics of the referral itself:

• id unique identifier for this referral
• created_timestamp the time the referral was created as a unix timestamp
• type the type of referral e.g. "Self Referred"
• status the status of the referral e.g. "Rejected"

A request to this route will return all referrals for a given service.

Pass the service_id as a query parameter to specify which service the referrals belong to.

The following is an example payload of what you should expect to be returned on a GET referrals per service request:

Example payload

{
    "success": 1,
    "referrals_per_service": {
        "10": {
            "service_id": 10,
            "referrals": [
                {
                    "id": "54",
                    "created_timestamp": "1756376399",
                    "updated_timestamp": "1756376399",
                    "type": "Self Referred",
                    "status": "Accepted"
                },
                {
                    "id": "64",
                    "created_timestamp": "1759316193",
                    "updated_timestamp": "1759316193",
                    "type": "Self Referred",
                    "status": "Referred"
                },
                {
                    "id": "65",
                    "created_timestamp": "1759316233",
                    "updated_timestamp": "1759316233",
                    "type": "Self Referred",
                    "status": "Accepted"
                }
            ]
        }
    }
}

Reading the results

In this case we already know what service we are requesting referrals for and so we only need to return the data specific to the referral itself:

• id unique identifier for this referral
• created_timestamp the time the referral was created as a unix timestamp
• updated_timestamp the time the referral was updated as a unix timestamp
• type the type of referral e.g. "Self Referred"
• status the status of the referral e.g. "Rejected"

A request to this route will return a single referral.

Pass the id as a query parameter to specify which referral to return.

The following is an example payload of what you should expect to be returned on a GET single referral request:

Example payload

{
    "success": 1,
    "referral": {
        "id": "96",
        "created_timestamp": "1764260644",
        "service_id": "2",
        "type": "Self Referred",
        "status": "Referred",
        "memo": "Support needed for emotional regulation, coping strategies, and guidance with personal and social challenges."
    }
}

Reading the results

Here we are getting the specifics for an individual referral scoped to include a bit more detail i.e. to include notes/memo data:

• id unique identifier for this referral
• created_timestamp the time the referral was created as a unix timestamp
• type the type of referral e.g. "Self Referred"
• status the status of the referral e.g. "Rejected"
• memo any notes related to this referral such as a description of why the referral has been made

Use this route for self-referrals. This route adds a referral to a service for a specified PDS. In the body of the request, pass the following fields to create a referral.

Required Fields

• service_id — The ID of the service that the referral is to.

Fields

• referree_background — Background of the referred person in the context of this referral.
• referree_requirements — Requirements of the referred person for this referral.
• referree_availability — Date/times the referred person is available to attend this service.
• referrer_name — Name of who made the referral.
• service_name — Name of the service.
• service_description — Description of the service.
• service_url — Service URL.
• service_email — Service email address.
• contact_number — Contact number for the service.
• memo — Any notes related to the referral.
• start_time — The date/time the referral starts.

Use this route for updating the status of a referral.

Required Fields

• id — The ID of the referral to update.
• status — The status of the referral.

Optional Fields

None

Currently, if you are working with any of the Secure Messaging routes, you will also need access to the Referrals Feature Block, which you can find out about HERE. A conversation exists in the context of a referral, so we need to link those messages to the referral by storing the referral id with each message that forms part of the conversation.

This route gets messages that form part of a specific conversation. Remember a conversation occurs as part of a given context which is described by the conversation_id i.e. {context}-{context-id}. To request a conversation, the conversation_id, formatted as such, is passed as a query parameter e.g. ?conversation_id=referral-44.

If no conversation exists in the given context, then an empty array will be returned, otherwise any messages will be returned ordered by the time they were created with the most recent appearing at the end of the array.

Example response:

[
    {
        "id": "343",
        "conversation_id": "referral-44",
        "message_to": "Jane",
        "time_sent": "1757948121",
        "message_content": "Hello",
        "status": "sent"
    },
    {
        "id": "344",
        "conversation_id": "referral-44",
        "message_from": "Andy",
        "time_received": "1757948123",
        "message_content": "Hello",
        "status": "received"
    },
    {
        "id": "345",
        "conversation_id": "referral-44",
        "message_from": "Andy",
        "time_received": "1757948142",
        "message_content": "How are you",
        "status": "received"
    },
    {
        "id": "346",
        "conversation_id": "referral-44",
        "message_to": "Jane",
        "time_sent": "1757948144",
        "message_content": "I'm good thanks",
        "status": "sent"
    }
]

Optional additional query parameters:

• after return messages after a given id
• before return messages before a given id
• limit return a specified max number of results

Either before or after query parameters can be used with or without the limit parameter to affect pagination in a way that supports a typical messaging service experience.

Without the additional query parameters, a GET conversation request will return the most recent messages and will default to a limit of 20 i.e. the 20 most recent messages. To get older messages, a GET request can be made with the addition of the before query parameter and setting it to the oldest message id of the previous request/response. The default limit is 20; if a different limit is required, this value can be passed in the request (max limit is 100).

Example requests:

• GET /secure-messages/conversation?conversation_id=referral-44&limit=8
• GET /secure-messages/conversation?conversation_id=referral-44&before=343&limit=8
• GET /secure-messages/conversation?conversation_id=referral-44&after=343

This route is used for sending a message from the PDS owner. It writes the message to the PDS and sets a value for message_to to indicate who the message was sent to.

In the body of the request, the following fields are expected:

• message_content the content of the message
• message_to who the message is sent to
• conversation_id the conversation id that links the messages to a specified context e.g. a referral

The following fields are written to by default: time_sent, calculated as the unix timestamp the send request is received.

Example request body:

{
    "conversation_id": "referral-44",
    "message_to" : "Andy Brown",
    "message_content" : "Hello"
}

This route is used for sending a message to the PDS owner. It writes the message to the PDS and sets a value for message_from to indicate who the message was sent from.

In the body of the request, the following fields are expected:

• message_content the content of the message
• message_from who the message is sent from
• conversation_id the conversation id that links the messages to a specified context e.g. a referral

The following fields are written to by default: time_received, calculated as the unix timestamp the receive request is received.

Example request body:

{
    "conversation_id": "referral-44",
    "message_to" : "Rae Wilson",
    "message_content" : "Hi there"
}

This is a dedicated Measurement Log for single value items. We currently support 29 different single value Measurements. An example is Weight which represents a given point in time capture of a specific value and is therefore available for tracking overtime. All single value measurements can be added via dedicated routes which are explained in the Developer Guidance below .

These forms of measurement require multiple values to provide a complete record. They are as follows:

Oxygen Saturation Log – Blood oxygen level is recorded. It can also record methods of measurement, location, forms of administration, and the supplemental flow rate, which is the rate at which additional oxygen is supplied to a user in litres per minute. Set to zero if no supplemental oxygen is provided.

Blood Glucose Log – Blood glucose measurement including means of capturing blood glucose, cross-reference to the Nutrition Log including meal type. Can be added as a cross-reference to the specific record ID of the meal record.

Blood Pressure Log – Records blood pressure readings: the diastolic and systolic measurements in mmHg. In addition, the position of the individual during the reading and where the measurement was taken on the body.

Body Temperature Log – Body temperature, location on the body where temperature was taken, as well as the source device type.

Nutrition Log – A top-level record of nutrition— essentially meals and snacks—which can be categorised and tracked over time. This is supported by a detailed record of the meal consumed in the Nutrition Consumption Log that breaks down into a much more granular level, of great interest to dieticians and clinicians. Many food-logging apps provide easy meal and snack capture through lookups of products using barcodes from databases of products and food types. These generate the data payload for storage in the Nutrition Consumption Log.

Workout Log – The workout log stores exercises of many different types and the specific metadata about a workout including start and end times, repetitions, and resistance levels. Many wearables and apps capture this information, including—for example—specific events that gather step count, which can be classified as a type of exercise.

Cervical Mucus Log – Cervical mucus is a fluid produced by the cervix that changes in consistency throughout a woman's menstrual cycle. People track it to identify their most fertile window—when they are most likely to conceive—by observing these changes in texture and amount, which are influenced by hormone fluctuations. Many apps that track the menstrual cycle can record and generate this type of measurement data.

Cervical Position Log – Cervical position refers to the location and position of a woman's cervix within the vagina, which changes throughout her menstrual cycle. People track it primarily to identify their most fertile window by observing when the cervix is high, soft, and open, indicating ovulation is approaching. The same apps that monitor the menstrual cycle can gather this information in the same way.

As part of our roadmap, where source data contains additional metadata which can be provided in payloads, we will be able to apply this information as a linked record in relevant datasets for future retrieval as part of Measurement requests.

Location Data – Many measurement solutions can also access or make use of location data collected by the devices that are also collecting measurement data. Location data can be delivered in bulk independently of activity, but it can also be cross-referenced with measurement data.

Device Record – You can register the devices that are used to collect the measurement data so that measurements can be linked to specific devices. This has been considered valuable for comparative analysis between different consumer wearable devices and clinically certified wearable devices that may be prescribed by a health and care professional as part of a support service.

Our SSC Roadmap for the Measurements Feature Block will be the provision of dedicated routes that support additional parameters and logic that will automatically manage the linking and interconnectivity with other Feature Blocks, and allow Third Party Integrators to more easily integrate, as all the rules in terms of PDS record management and linking will be managed by the PDX API.

Measurements will have its own OAuth scopes and be integrated into the Data Sharing and Services Agreement and Dedicated Connections as a Feature Block.

We are currently implementing Phase 1 of our Feature Block for Measurements (MESM) and have released Single Value Measurements and Blood Pressure Multi Value Measurements, supported by our MRD API Measurements Lookup service.

This use case is where you are recording a specific measurement, which we will store in the PDS ds_measurements_log when you submit a POST request via the dedicated Measurements Route. For a measurement like ‘Weight’, we only need a single row in ds_measurements_log added via the Dedicated Measurements routes.

The MRD API has a number of measurement-related endpoints which are used as lookup values related to the relevant dedicated routes and the underlying dataset record to map specific lookup values relevant to a record. For example: measurement types, unit measurements, and measurement groups to be used as values in the PDS record fields.

Measurement type (id value) must map into the PDS ds_measurements_log.measurement_field_type. This goes with measurement_type (varchar) which stores the type of measurement, e.g., ‘Weight’. So measurement_field_type would be a value like ’11’, which is the code for Weight in our measurement types lookup table.

You can get a list of measurement types for single value measurements using the MRD endpoint: {{MRD_API_URL}}/measurements/types

We currently support 29 different types of single Measurement values. You get the list via MRD Lookup, which also provides validations related to them.

This will return a list of all measurement type values which include the name (e.g., ‘Weight’) and the internal code for this measurement type (e.g., ’11’) as well as any other specific metadata related to that measurement, such as the unit measure. When creating the new Measurement record in the PDS, you will only need to supply the measurement_name value (e.g., ‘Weight’). We will internally map the other fields to the log entry.

The returned measurement type list from the MRD API looks like this (shortened version of the complete list of 29 single value measurements):

[
    {
        "measurement_id": "1",
        "measurement_name": "BMR",
        "measurement_group": "Health",
        "measurement_unit": "kcal per day"
    },
    {
        "measurement_id": "2",
        "measurement_name": "Calories Burned",
        "measurement_group": "Activity",
        "measurement_unit": "kcal"
    }
]

You can then select the appropriate value for the type of measurement to send in your POST Request for us to file in the PDS in the relevant dataset (in this case, ds_measurement_log). For Weight, use ‘kgs’ in the measurement_unit field. The value itself is stored in measurement_value (e.g., ’75.8’).

Adding the measurement via the PDX API (POST)

Note: As with any other PDX API requests (like Templates), you should request an OAuth 2.0 Bearer token with the required scopes. The scopes required for single value measurements and Blood Pressure are:

get:/api/pds/view-measurements
put:/api/pds/update-measurements
post:/api/pds/add-measurements
get:/api/pds/view-blood-pressure
put:/api/pds/update-blood-pressure
post:/api/pds/add-blood-pressure

Adding a new Measurement entry for a single value measurement uses the PDX API endpoint {{PDS_API_URL}}/api/pds/add-measurements. Just like with Mydex templates (e.g., MAM), you must pass the Connection-Token header as well as query parameters with uid and con_id. A typical request looks like this:

curl --location 'https://api.mydex.org/api/pds/add-measurements?uid=4043&con_id=4043-40102' \
--header 'Connection-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--data '[
    {
      "source_device_type": "Mobile",
      "source_name": "Apple Health Kit",
      "measurement_type": "Weight",
      "measurement_timestamp_start": 1648633780,
      "measurement_timestamp_end": 1648633780,
      "measurement_value": 175.8
    }
]'

Here’s an example request body of a complete ‘Weight’ Measurement record:

[
    {
      "source_device_type": "Mobile",
      "source_name": "Apple Health Kit",
      "measurement_type": "Weight",
      "measurement_timestamp_start": 1648633780,
      "measurement_timestamp_end": 1648633780,
      "measurement_value": 75.8
    }
]

The fields source_name and source_device_type are free text fields; use these to store the source and device type. The measurement_type field MUST be a value from the measurement types MRD lookup table, otherwise validation will fail. The measurement_value is a float, so ensure it’s valid (e.g., 75.0 for 75kg weight).

Batch Adding Multiple Rows

You can send more than one measurement record in a single POST request (up to 50 records) by adding additional elements to the request body array. For example, adding both ‘Weight’ and ‘Height’:

[
    {
      "source_device_type": "Mobile",
      "source_name": "Apple Health Kit",
      "measurement_type": "Weight",
      "measurement_timestamp_start": 1648633780,
      "measurement_timestamp_end": 1648633780,
      "measurement_value": 75.8
    },
    {
      "source_device_type": "Mobile",
      "source_name": "Apple Health Kit",
      "measurement_type": "Height",
      "measurement_timestamp_start": 1648633790,
      "measurement_timestamp_end": 1648633790,
      "measurement_value": 180.5
    }
]

When adding multiple entries, the last_insert_id in the response will be an array with each element added:

{
    "last_insert_id": [
        "140",
        "141"
    ]
}

To mitigate errors, you can update a single measurement_value after the record has been created. You cannot change any other fields. Use the record’s id with the PUT endpoint {{PDS_API_URL}}/api/pds/update-measurements:

{
  "id": "2",
  "measurement_value": 175.0
}

The response shows the updated record:

{
    "updated_value": {
        "id": "2",
        "measurement_value": "175.0"
    }
}

To get all single measurement records stored in the PDS, make a GET request to {{PDS_API_URL}}/api/pds/view-measurements. Example response:

[
    {
        "id": "1",
        "instance": "0",
        "source": "4043-40102",
        "source_device_type": "Mobile",
        "source_name": "Apple Health Kit",
        "source_instance": "0",
        "record_created_timestamp": "",
        "record_updated_timestamp": "1744882148",
        "measurement_group": "Body",
        "measurement_type": "Weight",
        "measurement_timestamp_start": "1648633780",
        "measurement_timestamp_end": "1648633780",
        "measurement_field_type": "11",
        "measurement_unit": "kgs",
        "measurement_value": "175.0"
    }
]

Filtering GET Requests

You can filter requests to get specific measurement types (e.g., ‘Weight’ or ‘Height’). Additional filtering options (timestamps, device types, source names) will be added in the future. Filter by passing the query parameter measurement_field_type (from the MRD lookup value). For Weight, use 11 to filter results.

Adding Blood Pressure records is much the same as adding new single measurement records. The differences are in the endpoint, payload, and MRD lookup values. You will need the lookup ID values for body_position and measurement_location.

For body_position you can make a request to {{MRD_API_URL}}/measurements/body-position. The response will look like this:

[
    {
        "id": "1",
        "body_position_id": "1",
        "description": "Standing up"
    },
    {
        "id": "2",
        "body_position_id": "2",
        "description": "Sitting down"
    },
    {
        "id": "3",
        "body_position_id": "3",
        "description": "Lying down"
    },
    {
        "id": "4",
        "body_position_id": "4",
        "description": "Reclining"
    }
]

You will then use the id/body_position_id as the value in the POST request to the PDX API.

For measurement_location, you can make a GET request to {{MRD_API_URL}}/measurements/blood-pressure-measurement. The response looks like this:

[
    {
        "id": "1",
        "blood_pressure_measurement_id": "1",
        "description": "Left wrist"
    },
    {
        "id": "2",
        "blood_pressure_measurement_id": "2",
        "description": "Right wrist"
    },
    {
        "id": "3",
        "blood_pressure_measurement_id": "3",
        "description": "Left upper arm"
    },
    {
        "id": "4",
        "blood_pressure_measurement_id": "4",
        "description": "Right upper arm"
    }
]

Putting this together, if you are adding a blood pressure record where the body position was sitting down and the measurement location was right upper arm, you would use the values 2 and 4 respectively.

You can add a new row by making a POST request to {{PDS_API_URL}}/api/pds/add-blood-pressure. The request body should look like this:

[
    {
        "blood_pressure_timestamp_end": "1648633780",
        "blood_pressure_timestamp_start": "1648633780",
        "body_position": "2",
        "diastolic": 75.7,
        "measurement_group": "Activity",
        "measurement_location": "4",
        "source_device_type": "Mobile",
        "source_name": "Apple Health Kit",
        "systolic": 120.7
    }
]

As with single value measurements, systolic and diastolic should be float values. source_name and source_device_type are used in the same way as with other measurements.

You can only update the values (systolic and diastolic). Other fields cannot be changed. The updated timestamp will be updated automatically. Specify the id of the record to update. The PUT endpoint is {{PDS_API_URL}}/api/pds/update-blood-pressure. A typical request body:

{
    "id": "1",
    "systolic": 122.0,
    "diastolic": 83.0
}

Response with the updated values:

{
    "updated_value": {
        "id": "9",
        "systolic": "122.0",
        "diastolic": "83.0"
    }
}

Retrieve all blood pressure log entries with a GET request to {{PDS_API_URL}}/api/pds/view-blood-pressure. Example response:

[
    {
        "id": "1",
        "instance": "0",
        "source": "4043-40102",
        "measurement_id": "0",
        "source_device_type": "PDA",
        "source_name": "Google Fit",
        "source_instance": "0",
        "record_created_timestamp": "1744810213",
        "record_updated_timestamp": "1744810213",
        "measurement_group": "Activity",
        "blood_pressure_timestamp_start": "1648633780",
        "blood_pressure_timestamp_end": "1648633780",
        "systolic": "120.7",
        "diastolic": "75.7",
        "body_position": "1",
        "body_position_description": "Standing up",
        "measurement_location": "1",
        "measurement_location_description": "Left wrist"
    }
]

Filtering Blood Pressure GET Requests

Filtering options will be available in a future phase of the Measurements Feature Block release.