Health PROMs

Health PROMs let your application collect Patient-Reported Outcome Measure answers from a User through the InsideTracker questionnaire flow. Use these APIs when you need to display the current questionnaire, submit the User's answers for today, or retrieve submitted answers for a date range.

How Health PROMs Work

The questionnaire defines the valid questions and answer options for the authenticated User. Your application displays those questions, keeps the returned question and answer option IDs, and submits the selected answer option ID for each question. PROM question IDs and answer option IDs are expected to remain stable; answer history returns submitted answer sets by date.

Where This Fits

Health PROMs are a customer-level data collection flow. Your application authenticates as the User, fetches the active questionnaire, presents the questions and answer options, and writes the User's response for the current day.

Use Health PROMs when:

• Your experience asks Users to report health status, symptoms, wellness, or similar survey-style observations.
• You need to preserve the exact question and answer option IDs supplied by InsideTracker.
• You need to retrieve previously submitted PROM answers for a User.

Before You Begin

You need:

• A customer access token for the User with the health-proms scope.
• The current PROM questionnaire from InsideTracker before building the submission payload.
• Dates formatted as YYYY-MM-DD.
• A workflow that handles a successful answer submission as 204 No Content.

The answer submission endpoint is intentionally strict. The request body must include every configured questionnaire question exactly once, every selected answer must be valid for its question, the path date must be today, and a User can submit answers only once per date.

Workflow

1. Fetch the PROM questionnaire for the authenticated User.
2. Render each question and answer option in your application.
3. Keep the id for each question and the selected answer option identifier.
4. Submit the complete answer set for today's date.
5. Read answer history when you need to display previously submitted responses.

Endpoint Overview

Get The Questionnaire

Call the questionnaire endpoint before asking the User to answer PROM questions. The response contains the list of questions and the available answer options for each question.

GET /health-proms/customer/v1/questionnaire

Store the returned question IDs and answer option IDs exactly as provided. Do not rely on display text as a stable identifier.

Submit Answers

Submit one answer item for each question in the current questionnaire. Replace {date} with today's date in YYYY-MM-DD format.

PUT /health-proms/customer/v1/answers/{date}
Content-Type: application/json

The array below shows the shape of an answer item. The actual request must include one item for every configured question.

[
  {
    "id": "QUESTION_ID",
    "answer": "ANSWER_OPTION_ID"
  }
]

Submission rules:

• The {date} path value must be today's date.
• The request body must be a non-empty array.
• Every configured question must appear exactly once.
• Each answer must use a valid answer option for that question.
• Answers can be submitted only once per User per date.

Handle Common Outcomes

Treat 204 No Content as a successful submission. The response does not include an answer body.

If submission fails because the payload contains an invalid, missing, or duplicate ID, fetch the current questionnaire again and rebuild the answer payload from the returned question and answer option IDs.

If the User has already submitted answers for the current date, do not retry the same request as a blind duplicate. Show that today's answers are already recorded, or route the User through the supported correction process if one is available for your integration.

Read Answers

Use the answer history endpoint to retrieve submitted PROM answers for an inclusive date range.

GET /health-proms/customer/v1/answers?startDate={startDate}&endDate={endDate}

Rules for answer history:

• startDate and endDate are required.
• startDate cannot be after endDate.
• The requested period cannot exceed 90 days.

Key Field Relationships

The PROM APIs use the same identifiers across the questionnaire, submission payload, and answer history. Keep the question identifier and selected answer option identifier as separate values.

Best Practices

Implementation Checklist

• Fetch the questionnaire using the authenticated User's customer token.
• Render every returned question and its answer options.
• Submit every question exactly once in the answer payload.
• Use today's date in the answer submission path.
• Handle 204 No Content as a successful submission.
• Validate answer history date ranges before calling the API.

Related API Reference

• Get PROM questionnaire
• Create PROM answers for a date
• Get PROM answers for a period

Related Topics

• Authentication and Users
• Profile Data
• Health Tags