Kit Ordering Integration Guide¶

Overview¶

The Kit Ordering integration allows your application to programmatically order genetic testing kits for your end-users through Gencove's API.

Key Concepts¶

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

• Sample: Represents a single genetic sample in Gencove. In the kit ordering workflow, one kit order equals one sample. The kit is what physically carries a sample. Each sample has a unique ID and tracks the entire lifecycle from kit request through sequencing and analysis.
• Sample Status: Samples progress through various states (e.g., kit_requested, kit_ordered, running, succeeded).
• Project: A container for organizing related samples in Gencove. All samples from kit orders must be assigned to a project.

How It Works¶

The kit ordering workflow involves four key parties:

1. Your end-user: The person requesting a genetic testing kit
2. Your application (consumer health company): Handles user requests and integrates with Gencove's API
3. Gencove: Orchestrates the kit ordering and processes sequencing results
4. Sequencing provider: Manufactures, ships, receives, and sequences the kits

sequenceDiagram
    autonumber
    actor EU as End-user
    participant CC as Consumer company
    participant GC as Gencove
    participant SP as Sequencing provider

    EU->>CC: Orders kit
    CC->>CC: Accept request, store information
    Note over CC,GC: CC uses Gencove API key for the request
    CC->>GC: POST https://api.gencove.com/api/v2/sample-kit/
    GC-->>CC: Return Gencove sample ID
    GC->>SP: Pass order information
    SP-->>EU: Ship kit to end-user
    EU-->>SP: Return kit
    SP->>SP: Process kit (sequencing)
    SP->>GC: Send sequencing results
    GC->>GC: Process results (Gencove analysis)

    alt Delivery back to CC via webhook
        GC-->>CC: POST results (webhook)
    else Delivery back to CC via API pull
        CC->>GC: Fetch results (API)
        GC-->>CC: GET https://api.gencove.com/api/v2/samples/{sample id}
    end

    CC-->>EU: Display results in application

sequenceDiagram
    autonumber
    actor EU as End-user
    participant CC as Consumer company
    participant GC as Gencove
    participant SP as Sequencing provider

    EU->>CC: Orders kit
    CC->>CC: Accept request, store information
    Note over CC,GC: CC uses Gencove API key for the request
    CC->>GC: POST https://api.gencove.com/api/v2/sample-kit/
    GC-->>CC: Return Gencove sample ID
    GC->>SP: Pass order information
    SP-->>EU: Ship kit to end-user
    EU-->>SP: Return kit
    SP->>SP: Process kit (sequencing)
    SP->>GC: Send sequencing results
    GC->>GC: Process results (Gencove analysis)

    alt Delivery back to CC via webhook
        GC-->>CC: POST results (webhook)
    else Delivery back to CC via API pull
        CC->>GC: Fetch results (API)
        GC-->>CC: GET https://api.gencove.com/api/v2/samples/{sample id}
    end

    CC-->>EU: Display results in application

Workflow Steps¶

1. Kit Request: Your end-user clicks "Order kit" in your application
2. Accept Request: Your application accepts the request and stores necessary information
3. Create Order: Your application makes an authenticated request to Gencove's API to create the kit order
4. Sample ID: Gencove returns a unique sample ID that you should store to track this kit/sample
5. Order Processing: Gencove passes the order information to the sequencing provider
6. Kit Shipment: The sequencing provider ships the kit directly to your end-user's address
7. Kit Return: Your end-user collects their sample and returns the kit to the sequencing provider
8. Sequencing: The sequencing provider processes and sequences the sample
9. Results to Gencove: The sequencing provider sends raw sequencing data to Gencove
10. Gencove Analysis: Gencove runs its analysis pipeline on the sequencing data
11. Results Delivery via Webhook: (RECOMMENDED) Gencove delivers results to your application via webhook when they're ready
12. Fetch results via API: Periodically ping Gencove API to get results
13. Results response: Use response to check if samples are ready
14. 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 ordering kits, you need at least one project to assign samples to.

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

Order a Kit¶

When your end-user requests a kit, your application should make a POST request to Gencove's kit ordering endpoint.

API Endpoint: POST https://api.gencove.com/api/v2/sample-kit/

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

Request Body:

{
  "project_id": "<project-uuid>",
  "recipient_address_name": "Jane Doe",
  "recipient_address_line1": "123 Main Street",
  "recipient_address_city": "San Francisco",
  "recipient_address_state_region": "CA",
  "recipient_address_postal_code": "94102",
  "recipient_address_country_code": "US",
  "recipient_email": "jane.doe@example.com",
  "recipient_phone": "+14155551234",
  "recipient_instructions": "Leave at front desk",
  "metadata": {
    "customer_id": "cust_12345",
    "order_number": "ORD-2025-001"
  }
}

Required Fields:

• project_id: The UUID of the Gencove project to assign this sample to
• recipient_address_name: Full name of the kit recipient
• recipient_address_line1: Street address
• recipient_address_city: City name
• recipient_address_state_region: State or region
• recipient_address_postal_code: Postal/ZIP code
• recipient_address_country_code: Two-letter ISO country code (e.g., "US", "GB", "CA")
• recipient_email: Email address for shipping notifications
• recipient_phone: Phone number (international format recommended)

Optional Fields:

• recipient_address_line2: Additional address information (apartment, suite, etc.)
• recipient_address_line3: Additional address information
• recipient_instructions: Special delivery instructions
• metadata: Custom key-value pairs to store with the sample (useful for linking back to your system)
• test_mode: Boolean flag for development testing (see Test Mode below)

Response:

{
  "sample_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Important: Store the returned sample_id in your database. This is the unique identifier you'll use to track the kit's status and retrieve results. Alternatively, if you include information in the metadata field when creating the order, you can search for samples using that metadata to find the correct sample without storing the sample ID.

Test Mode¶

Test mode allows you to create kit orders that go through the full API validation and workflow, but use a staging environment with the sequencing provider. No physical kit will be manufactured or shipped when test_mode is enabled.

When to use test mode:

• During initial integration development
• When testing your order creation flow
• When validating address formats and API responses

What happens in test mode:

• The API validates all fields exactly as in production
• A sample is created in your Gencove project with status kit_requested
• The order is sent to the provider's staging environment
• The sample will progress to kit_ordered status
• No physical kit is shipped and no kit ordering costs are incurred
• The sample will not receive sequencing results (since no kit is shipped)

To enable test mode, simply add "test_mode": true to your request body:

{
  "project_id": "<project-uuid>",
  "recipient_address_name": "Jane Doe",
  "recipient_address_line1": "123 Main Street",
  "recipient_address_city": "San Francisco",
  "recipient_address_state_region": "CA",
  "recipient_address_postal_code": "94102",
  "recipient_address_country_code": "US",
  "recipient_email": "jane.doe@example.com",
  "recipient_phone": "+14155551234",
  "test_mode": true
}

curl -X POST "https://api.gencove.com/api/v2/sample-kit/" \
  -H "Authorization: Api-Key $GENCOVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "06a5d04b-526a-4471-83ba-fb54e0941758",
    "recipient_address_name": "Jane Doe",
    "recipient_address_line1": "123 Main Street",
    "recipient_address_city": "San Francisco",
    "recipient_address_state_region": "CA",
    "recipient_address_postal_code": "94102",
    "recipient_address_country_code": "US",
    "recipient_email": "jane.doe@example.com",
    "recipient_phone": "+14155551234",
    "metadata": {
      "customer_id": "cust_12345"
    }
  }'

# Use test_mode for development - no kit will be shipped
curl -X POST "https://api.gencove.com/api/v2/sample-kit/" \
  -H "Authorization: Api-Key $GENCOVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "06a5d04b-526a-4471-83ba-fb54e0941758",
    "recipient_address_name": "Jane Doe",
    "recipient_address_line1": "123 Main Street",
    "recipient_address_city": "San Francisco",
    "recipient_address_state_region": "CA",
    "recipient_address_postal_code": "94102",
    "recipient_address_country_code": "US",
    "recipient_email": "jane.doe@example.com",
    "recipient_phone": "+14155551234",
    "test_mode": true
  }'

import os

import requests

API_KEY = os.getenv('GENCOVE_API_KEY')
PROJECT_ID = "67931e57-c374-4c0b-9616-8b809ad5b657"

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

payload = {
    "project_id": PROJECT_ID,
    "recipient_address_name": "Jane Doe",
    "recipient_address_line1": "123 Main Street",
    "recipient_address_city": "San Francisco",
    "recipient_address_state_region": "CA",
    "recipient_address_postal_code": "94102",
    "recipient_address_country_code": "US",
    "recipient_email": "jane.doe@example.com",
    "recipient_phone": "+14155551234",
    "metadata": {
        "customer_id": "cust_12345"
    }
}

response = requests.post(
    "https://api.gencove.com/api/v2/sample-kit/",
    headers=headers,
    json=payload
)

sample_id = response.json()["sample_id"]
print(f"Kit ordered! Sample ID: {sample_id}")

import os

import requests

API_KEY = os.getenv('GENCOVE_API_KEY')
PROJECT_ID = "67931e57-c374-4c0b-9616-8b809ad5b657"

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

# Use test_mode=True for development - no kit will be shipped
payload = {
    "project_id": PROJECT_ID,
    "recipient_address_name": "Jane Doe",
    "recipient_address_line1": "123 Main Street",
    "recipient_address_city": "San Francisco",
    "recipient_address_state_region": "CA",
    "recipient_address_postal_code": "94102",
    "recipient_address_country_code": "US",
    "recipient_email": "jane.doe@example.com",
    "recipient_phone": "+14155551234",
    "test_mode": True,  # Enable test mode
}

response = requests.post(
    "https://api.gencove.com/api/v2/sample-kit/",
    headers=headers,
    json=payload
)

sample_id = response.json()["sample_id"]
print(f"Test kit ordered! Sample ID: {sample_id}")

Monitor Kit Status¶

After ordering a kit, you can monitor its progress through various stages. Each sample progresses through different statuses from kit request to final results.

Common Sample Statuses:

• kit_requested: Kit has been requested through the API
• kit_ordered: Gencove has placed the order with the sequencing provider
• running: Sequencing data is being analyzed by Gencove
• succeeded: Analysis complete, results are ready
• failed_qc: Analysis failed (rare, contact support if this occurs)

Check Status via API:

curl "https://api.gencove.com/api/v2/samples/$SAMPLE_ID/" \
  -H "Authorization: Api-Key $GENCOVE_API_KEY"

import os

import requests

API_KEY = os.getenv('GENCOVE_API_KEY')
SAMPLE_ID = "3fa85f64-5717-4562-b3fc-2c963f66afa6"

headers = {
    "Authorization": f"Api-Key {API_KEY}"
}

response = requests.get(
    f"https://api.gencove.com/api/v2/samples/{SAMPLE_ID}/",
    headers=headers
)

sample_data = response.json()
print(f"Sample status: {sample_data['last_status']['status']}")

Simplified response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "client_id": "",
  "last_status": {
    "status": "running",
    "created": "2025-10-31T12:34:56Z"
  },
  "project": "67931e57-c374-4c0b-9616-8b809ad5b657",
  "metadata": {
    "customer_id": "cust_12345"
  }
}

Receive Results¶

Once sequencing and analysis are complete, you need to retrieve the results. Gencove offers two approaches:

Option 1: Webhooks (Recommended)¶

Webhooks allow Gencove to automatically notify your application when samples reach a final status (succeeded or failed_qc). This is more efficient than polling and provides real-time updates when results are ready.

To set up webhooks see our integration guide.

Option 2: API Polling¶

If webhooks aren't feasible for your infrastructure, you can periodically poll the samples API to check for status updates.

For polling it's better to use the /project-samples/{project_id} endpoint that can be used for querying many samples at once. See our API reference for a detailed list of endpoints.

Note: If using polling, we recommend checking no more frequently than every 1 hour. Typical turnaround time from order placed to results is measured in weeks.

System Responsibilities¶

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

Your Application's Responsibilities¶

• Handle end-user requests for kits
• Collect and validate shipping addresses
• Store the Gencove sample ID for each kit order
• 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 kit ordering
• Coordinate with the sequencing provider
• Receive raw sequencing data from the provider
• Run analysis on the sequencing data
• Deliver results via webhooks or API
• Provide sample status tracking

Sequencing Provider's Responsibilities¶

• Manufacture and ship kits to end-user addresses
• Receive returned samples
• Perform sequencing on samples
• Deliver raw sequencing data to Gencove

Support¶

If you have questions about the Kit Ordering integration or encounter any issues:

• API Reference
• Gencove Support