API endpoints

Orders

📘

Custom Branded DNA kits

If you’re using custom-branded kits, you must order the specific item (e.g., dna-kit-companyname). Please confirm the exact item name with your account manager.

📘

For US users

For U.S. orders, the ship_to_state field is required and must be entered as the official 2-letter code (e.g., CA for California, NY for New York).

Quick Start Flow

  1. Place Order

  2. Track Order Shipment

  3. Register Sample (choose one method)

  4. Track Sample Processing

    • Monitor sample status via dna-kit-job endpoint
    • Status progression: registered → received_by_lab → analyzed_by_lab → processing_dna_file → completed
    • See Sample Status Updates section

📘

Set up webhooks to receive automated notifications for order shipment and sample processing updates.

Place an Order

To place an order you can use the following payload in the POST /order/ endpoint.

In line_items you can specify the list of items to order and their quantity. This is the list of supported items to order:

  • dna-kit-unbranded-us
  • dna-kit-unbranded-eu

Basic payload to create an order:

{
    "ship_to_name": "Test Name",
    "ship_to_address": "address",
    "ship_to_city": "city",
    "ship_to_state": "State",
    "ship_to_postal_code": "12345",
    "ship_to_country": "Canada",
    "ship_to_email": "[email protected]",
    "phone_number": "1234567890",
    "preferred_shipping_option": "DHL_PARCEL_EXPEDITED",
    "line_items": [
        {
            "quantity": 1,
            "item": "dna-kit-unbranded-us"
        }
    ]
}

Phone Number Validation

For clients using the new orders flow via GBG, phone numbers are validated based on the destination country:

  • US orders (ship_to_country: "United States of America"): Must be exactly 10 digits
  • International orders: Maximum 15 characters allowed

Ship-to Email

The ship_to_email field is used for supplier communications and shipping notifications. The field is optional, and if not provided, the account email will be used.

The response will have the id of the order created, which can be used later to fetch data about the order using the GET /order/{id}/ endpoint. You can also list all your orders using the GET /order/ endpoint.

Shipping Options

Before placing an order, you can retrieve the available shipping methods for a destination address using the POST /order/shipping-options/ endpoint. Each option includes the courier service, an estimated delivery date, and the final price. To ship with a specific method, include preferred_shipping_option, set to the courier_service_code returned by the endpoint, when you place the order.

Shipping options are currently available for: United States of America and Mexico. For any other country, the request is rejected; place the order directly without a preferred_shipping_option, and the default shipping method will be used.

Example request payload:

{
    "name": "Test Name",
    "address1": "123 Main St",
    "address2": "",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "United States of America",
    "phone_country_code": "1",
    "phone_number": "1234567890",
    "item": "dna-kit-unbranded-us",
    "quantity": 1
}

item and quantity identify the DNA kit being shipped (same item slugs used in line_items when placing an order). name, address1, city, postal_code, and country are required; address2, state, phone_country_code, and phone_number are optional.

Check Order Status

The GET /order/:id/ or GET /order/ endpoints can be used to check the status of orders created by you. It will return the response in following format:

{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "paid": true,
    "status": "received",
    "channel": "",
    "created_at": "2024-11-19T06:21:25.610702Z",
    "updated_at": "2024-11-19T06:21:25.610717Z",
    "coupon": "",
    "shipment_method": "UPS",
    "phone_country_code": "",
    "phone_number": "1234567890",
    "ship_to_name": "Test Name",
    "ship_to_company": "",
    "ship_to_contact": "",
    "order_type": "B2C",
    "ship_to_address": "address",
    "ship_to_address1": "",
    "ship_to_city": "city",
    "ship_to_state": "State",
    "ship_to_postal_code": "12345",
    "ship_to_country": "Canada",
    "ship_to_email": "[email protected]",
    "profile": null,
    "line_items": [
        {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "item": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "created_at": "2024-11-19T06:21:25.622226Z",
            "updated_at": "2024-11-19T06:21:25.622203Z",
            "quantity": 1,
        }
    ],
    "packages": [
        {
            "id": "fee9af21-f6f3-4ebd-9b23-0a355a5c72b2",
            "products": [
                {
                    "id": "ffd9eb65-b712-433d-9943-3e774cdee350",
                    "package": "fee9af21-f6f3-4ebd-9b23-0a355a5c72b2",
                    "item": "a1f0261d-53fb-4c7b-8088-05785d558597",
                    "profile_id": "1ca85f64-5717-4562-b3fc-2c963f66afa6",
                    "sample_id": "GFXC633223",
                    "status": "registered",
                    "error": null,
                }
            ],
            "updated_at": "2021-11-29T14:05:13.480700Z",
            "supplier_package_id": "w821862",
            "tracking_number": "9400110200830472781274",
            "supplier_order_number": "w821862",
        }
    ]
}

Order Status Types

The possible statuses for order are:

  1. received: After the order is created, the initial status is received.
  2. submitted: Within one hour the status will change to submitted, which means the kit is being prepared by the supplier.
  3. shipped: The kit has been shipped.
  4. cancelled: The order has been cancelled.
  5. payment_failed: The payment for the order has failed.
  6. error: There is an error with the order. Please contact us for more info.

You can lookup the samples associated with an order by checking the products under the packages key. For possible status values see below.

Listing Orders

GET /service/health-analysis/b2b-integrations/order/ returns your orders, sorted by created_at, newest first, with a maximum of 100 orders per request. The response is a plain JSON array of Order objects — the same schema as before pagination was introduced. There is no pagination envelope, so nothing changes about how you parse the response.

Pagination parameters

ParameterDefaultNotes
page11-indexed page number. page=2 returns orders 101–200, page=3 returns 201–300, and so on.
page_size100Orders per page. Capped at 100 — larger values are silently clamped.
ordering-created_at-created_at = newest first (default). created_at = oldest first.

Ordering is deterministic: orders sharing the same created_at are broken by id, so a record never appears on two pages and never gets skipped between pages.

Stopping condition

Stop paging when a page returns fewer than 100 orders — that is the last page. Requesting a page beyond the last one returns 404 Not Found. If you page blindly, treat a 404 on a page request as "no more results" rather than as an error.

Incremental syncing

Rather than re-walking every page, combine pagination with the created_at filters to pull only what is new since your last sync:

GET /order/?created_at_gte=2026-08-01T00:00:00Z
GET /order/?created_at_gte=2026-08-01T00:00:00Z&page=2

Or page oldest-first for a stable backfill that is not disturbed by new orders arriving at the top:

GET /order/?ordering=created_at&page=1

Filtering by ID

The 100-per-request cap also applies when filtering: ?id=<uuid1>,<uuid2>,... returns at most 100 matches. If you need to look up more than 100 orders by ID, split the request into batches of 100 or page through the results.

Error responses

StatusCause
400 Bad Requestpage or page_size is not a positive integer (e.g. page_size=abc, page=0).
404 Not Foundpage is beyond the last page of results.

Registering Samples

Before registering a DNA sample, you must have created the profile you will associate it with. To do so, please refer to the POST /profile/ endpoint.

A DNA kit job is an entity that represents the flow of a DNA kit from registration by the user, to receipt and analysis by the lab, all the way to file processing completion.

To create a DNA kit job, refer to POST /dna-kit-job/ endpoint.

Payload to generate a DNA kit job:

{
  "profile_id": "1ca85f64-5717-4562-b3fc-2c963f66afa6",
  "sample_id": "GFXC633223"
}

profile_id is the id of the pre-created profile

sample_id is a unique identifier of a given kit (should be displayed prominently on the kit)

Sample Status Updates

After registering the kit, the DNA kit must be shipped back to the lab in question. The status of the kit can then be tracked directly from the DNA kit job.

  1. shipped: The sample has been shipped, but has not yet been registered.
  2. registered: The sample has been successfully registered but has not yet been received by the laboratory.
  3. received_by_lab: The sample has been received by the laboratory.
  4. analyzed_by_lab: The sample is currently being analyzed by the laboratory.
  5. processing_dna_file: Our servers have received the sample data and are imputing the whole genome file.
  6. completed: The processing of the sample is complete.
  7. failed: The processing of the sample has failed. See error field for details, which can have either of the following values:
    1. "Low quality sample."
    2. "Missing profile."
    3. “Genome file processing failed”
    4. "Sex mismatch detected."
    5. “Unknown error.” (contact support)

      Recovering from Sex mismatch detected.

      Unlike other failure reasons, a job that fails with Sex mismatch detected. can be recovered without re-shipping a kit. Update the profile's sex field via PATCH /profile/{id}/. The system will:

      1. Reset the underlying sample for re-validation.
      2. Refresh the failed DnaKitJob from the new internal state and clear its notification history.
      3. Re-fire the webhook for the job once it reaches a terminal state (completed if the new sex matches, or failed again if it still doesn't).

      No new dna-kit-job registration is required.

Registering via https://registerdnakit.com/

When users register directly via the online portal, a dna-kit-job will be back-populated in b2b-integrations. Its status can be queried there in the same way you would for api created dna-kit-jobs. Webhook notifications will also be emitted in the usual way.

Webhooks

📘

Please check our webhooks guide for detailed instructions on using webhooks.

Both orders and DNA kit jobs are webhook compliant. To leverage webhooks, you need to create a user-webhook of type order_job and dna_kit_job respectively.

For orders, a notification will be sent when the order is shipped or errored.

A sample payload of the order job webhook notification in case of order shipped is given below:

{
  "order_id": "4b96d2b8-39c5-436b-9436-73dc6f62860d",
  "user_id": "b1e5cd20-274b-4fd7-8b45-219196a8ef98",
  "status": "shipped",
  "error": "",
  "order": {
    "id": "4b96d2b8-39c5-436b-9436-73dc6f62860d",
    "paid": true,
    "coupon": "",
    "status": "shipped",
    "channel": "",
    "profile": "1c9d1277-464c-438b-8006-3d9d49e8f14b",
    "user_id": "b1e5cd20-274b-4fd7-8b45-219196a8ef98",
    "packages": [
      {
        "id": "aadfcc6f-fcf7-44cf-8599-3117a3fa1ea7",
        "products": [
          {
            "id": "62eb9823-786a-4e30-95f3-ef5a0659b997",
            "item": "a1f0261d-53fb-4c7b-8088-05785d558597",
            "error": null,
            "status": "shipped",
            "package": "aadfcc6f-fcf7-44cf-8599-3117a3fa1ea7",
            "sample_id": "KITaadfcc6f0",
            "profile_id": "1c9d1277-464c-438b-8006-3d9d49e8f14b"
          }
        ],
        "updated_at": "2025-05-21T08:28:02.469159Z",
        "tracking_number": "",
        "supplier_package_id": "4b96d2b8-39c5-436b-9436-73dc6f62860d-0",
        "supplier_order_number": "4b96d2b8-39c5-436b-9436-73dc6f62860d"
      },
      {
        "id": "689e8ec7-44a3-4ce4-b24c-a594491c3a18",
        "products": [],
        "updated_at": "2025-05-21T09:41:17.793590Z",
        "tracking_number": "123456789",
        "supplier_package_id": "test",
        "supplier_order_number": "test"
      }
    ],
    "created_at": "2025-05-21T07:34:32.635641Z",
    "line_items": [
      {
        "id": "431d986e-e2db-4abf-a649-fe0f89d03f4c",
        "item": "a1f0261d-53fb-4c7b-8088-05785d558597",
        "quantity": 1,
        "created_at": "2025-05-21T07:34:32.654601Z",
        "updated_at": "2025-05-21T07:34:32.654574Z"
      }
    ],
    "order_type": "B2C",
    "updated_at": "2025-05-21T07:36:51.263643Z",
    "phone_number": "1234567890",
    "ship_to_city": "city",
    "ship_to_name": "Test Name",
    "ship_to_state": "State",
    "ship_to_address": "address",
    "ship_to_company": "",
    "ship_to_contact": "",
    "ship_to_country": "Canada",
    "shipment_method": "Slovenia Post",
    "ship_to_address1": "",
    "phone_country_code": "",
    "ship_to_postal_code": "12345"
  }
}

Apart from the order-job's metadata fields order_id, user_id, status, error, the notification payload also contains the order field which has the same schema as mentioned above for the retrieve order endpoint. This field essentially contains complete information of the order, thus saving the client an extra API call to fetch the order details upon receiving shipped notification.

Similarly, for a DNA kit job, a notification will be sent on job failure or completion.

Updated 3 months ago

Did this page help you?

Updated 3 months ago

Did this page help you?