Array upload, for participants who already have genetic data on hand
Today, we're launching short-lived, embeddable, white-label forms for kit ordering and array upload. Health platforms can now offer genetic testing without having to build the interface themselves.Members can either upload existing data from AncestryDNA, 23andMe, or MyHeritage, or order a kit for first-time collection.
From your backend, the flow is simple:
Request a link
Hand it to the patient or member
The member places the order on a Gencove-hosted page with zero Gencove branding
Ordering a kit through the Gencove API is straightforward: a POST /api/v2/sample-kit/ request with a project and a recipient address places the order. The work is in that address. Before a partner can make the call, it has to build and maintain a shipping-address form, with state and ZIP validation, phone-number formatting, clear error messages, and a layout that works on a phone. That is real engineering effort, and none of it is specific to genetics.
Gencove already used a hosted-form pattern to solve this elsewhere. Partners collecting array data do not build an upload interface; they request a tokenized URL and hand it to the end-user, who uploads the file on a Gencove-hosted page. The same approach backs the consumer-facing PRS reports. Kit ordering was the remaining part of the white-label flow that still required partners to build an interface of their own. It no longer does.
What we released
A new endpoint, POST /api/v2/sample-kit-form/, returns a short-lived, single-use URL for an order form. The flow has four steps:
The partner’s application calls POST /api/v2/sample-kit-form/ with a project_id. No address is included.
Gencove returns a sample_id and a short-lived url.
The partner passes the url to the end-user, who opens it, enters shipping details, and submits.
Gencove places the kit order automatically, and the sample moves through the same statuses as the API path.
Unlike a direct-to-consumer kit order, where the end-user pays at checkout, this flow has no payment step. The kit is billed to the partner’s contract, exactly like the existing POST /api/v2/sample-kit/ path. The end-user never sees a checkout, and the partner does not have to build one.
project_id is the only required field. The optional fields cover common integration needs:
metadata: custom key-value pairs stored on the sample, useful for linking it back to an order or customer in the partner’s own system. It round-trips exactly like the metadata on the existing kit-ordering endpoint.
redirect_on_success and redirect_on_failure: HTTPS URLs the end-user is sent to after submitting. If omitted, Gencove shows a hosted confirmation page instead.
test_mode: routes the order to the provider’s staging environment, so no physical kit ships. It behaves the same as elsewhere in the kit-ordering API.
expires_in: how long the link remains valid before it is opened, in seconds. Defaults to 600 (10 minutes), with a minimum of 60 and a maximum of 3600.
The response includes the sample_id at session-creation time, rather than after the end-user submits. It identifies the sample for status tracking and result retrieval, and can be recorded in the partner’s system as soon as the session is created.
The end-user experience
The form carries no Gencove branding. The end-user sees a single page requesting recipient name, email, phone, address, and any delivery instructions, with no account, registration, or payment required. On success, the end-user is redirected to redirect_on_success when one is configured, or to a hosted confirmation page otherwise. When an order cannot be placed, the end-user is redirected to redirect_on_failure with a reason query parameter the partner can branch on, or to a Gencove-hosted error page when no redirect is configured.
The page is served by Gencove on consumer.gencove.com. It should be opened as a top-level page, such as a new browser tab, an iOS ASWebAuthenticationSession, or an Android Custom Tab, each of which returns control to the partner’s application once the end-user finishes. Gencove’s own Order a kit button, described below, opens it in a new tab.
Session timing
Two separate windows govern the link:
expires_in controls how long the link is valid before it is opened, 10 minutes by default.
Once the link is opened, the end-user has a fixed 15 minutes to complete and submit the form.
If either window closes, a new session is required. Sessions are best created at the point the end-user is ready to order, rather than in advance.
Tracking the order
Hosted-form samples pass through two statuses that the direct API path does not use:
Status
Meaning
consumer awaiting kit order
Session created; waiting for the end-user to submit
consumer session expired
Link expired before the end-user submitted
After submission, the sample follows the standard path: kit_requested, then kit_ordered, and onward through sequencing and results. Existing integrations for monitoring kit status and receiving results apply unchanged.
Sessions that are opened but never submitted do not remain open. They transition to consumer session expired automatically, so project dashboards reflect orders that are actually in progress rather than links that were opened once and left.
Single-use links
Because the link lets an anonymous end-user place an order for a physical kit, it is designed to be safe to distribute. Each link is tied to a single order and can be used only once: after the form is submitted, the link stops working and cannot be replayed or redirected to a different order. Links also expire within the timing windows above, so a link that is exposed has typically already lapsed. The endpoint is rate-limited on the same scope as the rest of the kit-ordering API. Together, these constraints mean the URLs do not need to be treated as long-lived secrets.
The array-data upload form
Kit ordering is the most recent hosted form, but not the only one. For workflows that begin with genotyping array data rather than a kit, POST /api/v2/array-data-upload-form/ returns the same kind of short-lived, single-use link. The end-user opens it and uploads a single .zip file on consumer.gencove.com instead of entering a shipping address, and Gencove validates the file type and size at upload time.
The rest of the model is identical. metadata, redirect_on_success, redirect_on_failure, and expires_in behave the same way, the same timing windows apply, the link opens as a top-level page, and the sample passes through consumer awaiting data (or consumer session expired if the link is abandoned) before joining the standard upload path. In the web platform, the New upload session button is the array-data counterpart to Order a kit.
The form can also be reached without writing any code. Consumer projects in the Gencove web platform now include an Order a kit button alongside the existing upload actions. Selecting it returns the same short-lived link the API produces and opens it in a new tab, where the order can be completed and the sample followed through the statuses above.
Because it calls the same endpoint as a full integration, it is a convenient way to verify a project’s configuration before any code is written.
Getting started
The hosted forms are available now for consumer projects. Existing setup carries over: the same API key, project, status monitoring, and result handling all work as before. The only change is where the form is rendered.
For a working reference, Gencove has published an end-to-end demo at github.com/gncv/gencove-hosted-forms-demo. It runs the full flow, from creating a session to placing the order, for both hosted forms, with interchangeable Node.js + Express and Python + Django backends.
Partners already ordering kits through POST /api/v2/sample-kit/ with their own form do not need to change anything; that path is unchanged and fully supported. Both paths share the same billing model, the same statuses, and now the same underlying code.
With API, OAuth, variant-level access, and now a family of hosted forms for kit ordering and data upload, a partner can deliver a complete consumer genetics product, from the initial kit order through to variant-level results.