Array Data Uploads Integration Guide¶

Overview¶

The Array Data Uploads integration allows your application to collect 23andMe, Ancestry, or MyHeritage raw genotyping exports from end-users through Gencove's API—without building your own file-upload infrastructure.

Key Concepts¶

Before integrating, it's helpful to understand a few core Gencove concepts:

• Sample: Represents a single genetic sample in Gencove. In the array-data upload workflow, one upload session equals one sample. Each sample has a unique ID and tracks the entire lifecycle from upload request through analysis.
• Sample Status: Samples progress through various states (e.g., consumer awaiting data, scheduled, running, succeeded).
• Project: A container for organizing related samples in Gencove. Upload sessions are created in a project Gencove provisions for your organization.

Accepted uploads¶

End-users must upload an unmodified .zip export from 23andMe, Ancestry, or MyHeritage. The maximum file size is 25 MB. The upload form rejects other file types and oversized files before analysis begins.

How It Works¶

The array-data upload workflow involves three key parties:

1. Your end-user: The person uploading their genotyping export
2. Your application (consumer health company): Handles user requests and integrates with Gencove's API
3. Gencove: Hosts the upload experience, stores the file, and runs analysis

sequenceDiagram
    autonumber
    actor EU as End-user
    participant CC as Consumer company
    participant CU as consumer.gencove.com
    participant API as Gencove API
    participant GC as Gencove

    EU->>CC: Ready to upload array data
    CC->>CC: Accept request, store information
    Note over CC,API: CC uses Gencove API key for the request
    CC->>API: POST https://api.gencove.com/api/v2/array-data-upload-form/
    API-->>CC: Return sample ID and upload URL
    CC-->>EU: Open upload URL (WebView or browser)
    EU->>CU: Upload .zip file
    CU->>GC: Store array data and sample metadata
    GC->>GC: Process array data

    alt Delivery back to CC via webhook
        GC-->>CC: POST results (webhook)
        CC-->>EU: Display results in application
    else Delivery back to CC via API pull
        CC->>API: GET https://api.gencove.com/api/v2/samples/{sample_id}
        API-->>CC: Sample status and deliverables
        CC-->>EU: Display results in application
    end

sequenceDiagram
    autonumber
    actor EU as End-user
    participant CC as Consumer company
    participant CU as consumer.gencove.com
    participant API as Gencove API
    participant GC as Gencove

    EU->>CC: Ready to upload array data
    CC->>CC: Accept request, store information
    Note over CC,API: CC uses Gencove API key for the request
    CC->>API: POST https://api.gencove.com/api/v2/array-data-upload-form/
    API-->>CC: Return sample ID and upload URL
    CC-->>EU: Open upload URL (WebView or browser)
    EU->>CU: Upload .zip file
    CU->>GC: Store array data and sample metadata
    GC->>GC: Process array data

    alt Delivery back to CC via webhook
        GC-->>CC: POST results (webhook)
        CC-->>EU: Display results in application
    else Delivery back to CC via API pull
        CC->>API: GET https://api.gencove.com/api/v2/samples/{sample_id}
        API-->>CC: Sample status and deliverables
        CC-->>EU: Display results in application
    end

Workflow Steps¶

1. Upload request: Your end-user is ready to submit their 23andMe, Ancestry, or MyHeritage export in your application
2. Accept request: Your application accepts the request and stores necessary information
3. Create session: Your application makes an authenticated request to Gencove's API to create an upload session
4. Sample ID and URL: Gencove returns a unique sample ID and a short-lived upload URL that you should hand off to the end-user
5. End-user upload: The end-user opens the URL and uploads their .zip file on Gencove-hosted pages
6. Gencove analysis: Gencove stores the file and runs analysis on the array data
7. Results delivery via webhook: (RECOMMENDED) Gencove delivers results to your application via webhook when they're ready
8. Fetch results via API: Periodically ping the Gencove API to get sample status and results
9. Display results: Your application displays the results to your end-user

Integration Guide¶

Get Your API Key¶

To make requests to Gencove's API, you'll need an API key. This key authenticates your application and should be kept secure (treat it like a secret or a password).

To generate an API key:

1. Log in to your Gencove account at web.gencove.com
2. In the left sidebar, click on Account
3. Navigate to the API Keys tab
4. Click the Generate new API key button
5. Copy the generated API key and store it securely

Security Best Practice: For production use, consider creating a separate Gencove user with Analyst level privileges specifically for API access, and use that user's API key. This follows the principle of least privilege and makes it easier to manage access if needed.

Create a Gencove Project¶

Before creating upload sessions, you need a project for array-data samples.

Gencove support should have created a properly configured project during onboarding; if not, please contact our team.

Create an Upload Session¶

When your end-user is ready to upload, your application should make a POST request to Gencove's array-data upload endpoint.

API Endpoint: POST https://api.gencove.com/api/v2/array-data-upload-form/

Authentication: Include your API key in the Authorization header: Authorization: Api-Key $GENCOVE_API_KEY

Request Body:

{
  "metadata": {
    "customer_id": "cust_12345",
    "channel": "ios_webview"
  },
  "redirect_on_success": "https://partner.example.com/upload/done",
  "redirect_on_failure": "https://partner.example.com/upload/error",
  "expires_in": 600
}

Optional Fields:

Response:

{
  "sample_id": "6c3437b4-35fc-4224-9bb0-4623a16e6735",
  "url": "https://consumer.gencove.com/array-data-upload?token=<jwt>",
  "expires_at": "2026-06-02T12:34:56Z"
}

Important: Store the returned sample_id in your database. This is the unique identifier you'll use to track the sample's status and retrieve results. You can also find samples later using values in metadata.

Hand the returned url to your end-user when they are ready to upload (for example, open it in a mobile WebView). Create the session shortly before upload—the link expires after expires_in seconds.

Example Request¶

curl -X POST "https://api.gencove.com/api/v2/array-data-upload-form/" \
  -H "Authorization: Api-Key $GENCOVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {"customer_id": "cust_12345"},
    "redirect_on_success": "https://partner.example.com/upload/done",
    "redirect_on_failure": "https://partner.example.com/upload/error",
    "expires_in": 600
  }'

import os

import requests

API_KEY = os.getenv("GENCOVE_API_KEY")

headers = {
    "Authorization": f"Api-Key {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "metadata": {"customer_id": "cust_12345"},
    "redirect_on_success": "https://partner.example.com/upload/done",
    "redirect_on_failure": "https://partner.example.com/upload/error",
    "expires_in": 600,
}

response = requests.post(
    "https://api.gencove.com/api/v2/array-data-upload-form/",
    headers=headers,
    json=payload,
)
response.raise_for_status()
session = response.json()
print(f"Sample ID: {session['sample_id']}")
print(f"Upload URL: {session['url']}")

End-User Upload Experience¶

After your end-user opens the url:

1. Gencove validates the link and shows a branded upload form on consumer.gencove.com
2. The end-user uploads their .zip file
3. On success, they are redirected to redirect_on_success or see a Gencove confirmation page
4. On failure, they are redirected to redirect_on_failure when configured

Once the file is uploaded, the sample is scheduled for analysis automatically. You do not need to make a separate API call to start processing.

Session timing: The upload link is valid for expires_in seconds before it is opened. After the end-user opens it, they have 15 minutes to complete the upload. If either window expires, create a new session.

One file per sample: Each upload session accepts a single .zip file. If a file was already uploaded for that sample, the link will no longer accept another upload.

Tracking Sample Status¶

Relevant statuses for array-data upload samples:

We recommend using event notifications to learn when a sample reaches succeeded. Alternatively, poll GET https://api.gencove.com/api/v2/samples/{sample_id}.

Note: If using polling, check sample status periodically rather than on every page load. Analysis turnaround time depends on queue load and is typically shorter than kit-based workflows.

WebView and iframe Integration¶

The upload pages can be embedded in an iframe or opened in a mobile WebView so the experience stays inside your application.

Manual Testing¶

You can start an upload session from the Gencove web UI:

1. Open your array-data upload project
2. Click New upload session on the project page
3. Open the returned link and upload a test .zip file

This uses the same API endpoint as the integration described above.

System Responsibilities¶

Understanding what each system is responsible for helps clarify the integration:

Your Application's Responsibilities¶

• Handle end-user requests to upload array data
• Create upload sessions via the Gencove API
• Store the Gencove sample ID for each upload session
• Hand off the upload URL to the end-user at the right time
• Monitor sample status (via webhooks or polling)
• Retrieve and display results to your end-users
• Manage your end-users' accounts and permissions
• Keep the Gencove API Key secure

Gencove's Responsibilities¶

• Provide the API for creating upload sessions
• Host the end-user upload experience on consumer.gencove.com
• Store uploaded files and run array-data analysis
• Deliver results via webhooks or API
• Provide sample status tracking

Support¶

If you have questions about the Array Data Uploads integration or encounter any issues:

• API Reference
• Event Notifications
• Gencove Support