Consumer Reports Integration Guide

Feature Availability

The Consumer Reports feature is enabled on demand. Please contact Gencove support to have it switched on for your organization before attempting the integration described below.

Overview

Consumer Reports allow partners to mint short-lived, presigned links that deliver a consumer-friendly polygenic risk score (PRS) report for samples. Each link redirects customers to https://consumer.gencove.com/reports/view?token=..., where a secure browser session is initiated that renders a PRS report directly from Gencove. This approach keeps report rendering logic on Gencove infrastructure while letting you surface results inside your product (for example, inside a mobile WebView).

What the Report Displays

Each PRS trait in the sample's report renders:

• A risk label ('High risk' vs 'Not high risk') derived from sample's results
• Percentile visualization with threshold markers that illustrate where the individual falls relative to the population
• Recommendation cards with high- or low-risk suggestions for addressing the trait

This content lives entirely on Gencove infrastructure, so you do not need to replicate trait logic or visualizations in your app.

Integration Guide

See the 'Get your API key' section for instructions on obtaining a Gencove API key.

API Workflow

• Endpoint: POST https://api.gencove.com/api/v2/sample-consumer-report/<sample_id>
• Authentication: Authorization: Api-Key $GENCOVE_API_KEY
• Request body:

{
  "report_type": "prs",
  "expires_in": 600
}

Field	Description	Notes
report_type (Optional)	Report type to generate	Defaults to "prs"
expires_in (Optional)	Lifetime of the presigned JWT in seconds	Default 600, minimum 60, maximum 3600

• Success response (201):

{
  "url": "https://consumer.gencove.com/reports/view?token=<jwt>",
  "expires_at": "2026-01-01T12:34:56Z"
}

The url can then be used to redirect customers to the report. Note that when making the request, the report_type and expires_in parameters are optional and will default to "prs" and 600 respectively.

Example Request

curl -X POST "https://api.gencove.com/api/v2/sample-consumer-report/6c3437b4-35fc-4224-9bb0-4623a16e6735" \
  -H "Authorization: Api-Key $GENCOVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "report_type": "prs", "expires_in": 600 }'

Error Codes

Status	When it happens
403 Forbidden	Consumer mode disabled or organization mismatch
400 Bad Request	Sample incomplete
400 Bad Request	Sample missing trait scores
401/403	API key missing or lacks adequate permissions

End-User Flow

1. Create the link – Call the endpoint immediately before presenting results, choosing an expires_in as needed (recommended ≤10 minutes). This returns a JWT that expires after expires_in seconds.
2. Redirect or deep link – Send the customer to the returned url. For mobile apps, open the URL inside a WebView to keep the experience in-app.
3. Session establishment – GET /reports/view validates the token and creates a browser session.
4. Report rendering – The browser is 303-redirected to GET /reports/<report_type>/<session_uuid>. This session remains valid for 15 minutes (note that this is separate from the JWT lifetime set via expires_in in step 1).

If the JWT or session expires, the customer receives HTTP 403. In this case, reissue a new presigned link by repeating step 1.

Manual Testing

For ease of testing, you can view a sample's consumer report directly from Gencove's web UI. This view is accessible via the sample details page (e.g. https://web.gencove.com/projects/<project_id>/samples/<sample_id>), where a "View Consumer Report" button is present if the sample is in a completed state and has PRS trait scores available.

Support

If you have questions about Consumer Report integration or encounter any issues:

• API Reference
• Gencove Support