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.

Gencove-Hosted Kit Ordering Form¶

The Order a Kit flow above has your application collect the recipient's shipping address and submit it to POST /api/v2/sample-kit/. As an alternative, Gencove can host the order form for you: your backend requests a short-lived, tokenized URL and hands it to the end-user, who enters their own shipping details on a Gencove-hosted page and submits. The kit order is then placed automatically—with no payment step, billed by contract exactly like the API path above.

Use this when you'd rather not build and validate a shipping-address form yourself. Everything else in this guide applies unchanged—getting an API key, creating a project, monitoring status, and receiving results.

How the Hosted Form Works¶

1. Your application calls POST /api/v2/sample-kit-form/ with a project_id (no address).
2. Gencove returns a sample_id and a short-lived url.
3. You hand the url to your end-user, who opens it, fills in their shipping details, and submits on consumer.gencove.com.
4. Gencove places the kit order automatically, and the sample proceeds through the same statuses as the API path.

Create an Order-Form Session¶

When your end-user is ready to order, your application makes a POST request to Gencove's kit-order-form endpoint.

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

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

Request Body:

{
  "project_id": "<project-uuid>",
  "metadata": {
    "customer_id": "cust_12345",
    "order_number": "ORD-2025-001"
  },
  "redirect_on_success": "https://partner.example.com/order/done",
  "redirect_on_failure": "https://partner.example.com/order/error",
  "expires_in": 600
}

Required Fields:

• project_id: The UUID of the Gencove project to assign this sample to

Optional Fields:

• metadata: Custom key-value pairs stored on the sample (useful for linking back to your system)
• redirect_on_success: HTTPS URL to send the end-user to after they submit the order; omit to send them to a generic Gencove-hosted confirmation page
• redirect_on_failure: HTTPS URL to send the end-user to if the order cannot be completed, with a reason query parameter appended; omit to send them to Gencove's hosted error page instead. Only failures Gencove can tie back to this order link reach your URL—see Failure reasons
• test_mode: Boolean flag for development testing (see Test Mode above); defaults to false
• expires_in: How long the order-form link stays valid before the end-user opens it, in seconds (default 600 / 10 minutes, minimum 60, maximum 3600)

The shipping address is not part of this request—your end-user enters it on the hosted form.

Response:

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

Important: Store the returned sample_id in your database to track the sample's status and retrieve results. Hand the returned url to your end-user when they are ready to order, opening it as a top-level page (see Opening the Order Form). Create the session shortly before ordering—the link expires after expires_in seconds.

curl -X POST "https://api.gencove.com/api/v2/sample-kit-form/" \
  -H "Authorization: Api-Key $GENCOVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "06a5d04b-526a-4471-83ba-fb54e0941758",
    "metadata": {"customer_id": "cust_12345"},
    "redirect_on_success": "https://partner.example.com/order/done",
    "expires_in": 600
  }'

import os

import requests

API_KEY = os.getenv("GENCOVE_API_KEY")
PROJECT_ID = "06a5d04b-526a-4471-83ba-fb54e0941758"

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

payload = {
    "project_id": PROJECT_ID,
    "metadata": {"customer_id": "cust_12345"},
    "redirect_on_success": "https://partner.example.com/order/done",
    "expires_in": 600,
}

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

test_mode works exactly as described in Test Mode above and is passed here at session-creation time; the resulting order goes to the provider's staging environment and no physical kit is shipped.

End-User Order Experience¶

After your end-user opens the url:

1. Gencove validates the link and shows the order form on consumer.gencove.com
2. The end-user enters their shipping details—recipient name, email, phone, address, and any delivery instructions—and submits
3. Gencove places the kit order automatically; there is no payment step
4. On success, they are redirected to redirect_on_success, or to a generic Gencove-hosted confirmation page when you did not configure one
5. If the order cannot be placed, they are redirected to redirect_on_failure with a reason query parameter appended; otherwise they are sent to Gencove's hosted error page (see Failure reasons)

Once the form is submitted, the kit order is placed automatically—you do not need to make a separate API call.

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

Opening the Order Form¶

Open the returned url as a top-level page. Embedding the order form in an iframe is not supported.

If you configure redirect_on_success or redirect_on_failure, the end-user lands on your page in that same context when the flow ends, so you can resume your own application's flow there.

Failure Reasons¶

When an order cannot be completed, the end-user lands on a page with a reason query parameter describing what went wrong. Branch on reason to show the right message in your own UI, and treat an unrecognised value as a generic failure—more may be added over time.

These reasons are sent to your redirect_on_failure:

These are always shown on Gencove's hosted error page, even if you configured redirect_on_failure:

The hosted error page is at https://consumer.gencove.com/sample-kit-form/failure/ and accepts the same reason parameter, so you can open any row above directly—for example https://consumer.gencove.com/sample-kit-form/failure/?reason=already_ordered—to see exactly what your end-user would see, without creating an order-form session first. The confirmation page at /sample-kit-form/success/ works the same way.

Additional Sample Statuses¶

Hosted-form samples pass through two extra statuses before kit_requested (all other statuses match the Monitor Kit Status section above):

Manual Testing¶

You can start an order-form session from the Gencove web UI:

1. Open your consumer project
2. Click Order a kit on the project page
3. Open the returned link, fill in the shipping details, and submit

This uses the same 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 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