For companies and labs · Updated 23 September 2026
Ancient Matches via API for DNA-testing companies and labs
Send a customer's DNA file with one API call and receive the ancient individuals it shares DNA with, as JSON: more than 13,000 people dated 3000 BC to 1400 AD, every shared stretch with its position, length and marker evidence. Create a company account, make a key and build on the free sandbox today. A delivered sample costs 15 EUR.
Order ord_01j9m · scan result
- status
- completed · 201 then 200
- Italy_Imperial
- 412.6 cM · 71 individuals
- Russia_Steppe_EBA
- 391.4 cM · 79 individuals
- Croatia_IronAge
- 377.1 cM · 64 individuals
- matches
- 214 · strongest 200 listed
- Clears the thresholds
- Strongest match so far
What the API is
Ancestrify compares a genotype file with more than 13,000 published ancient individuals, dated 3000 BC to 1400 AD, one person at a time, and reports every stretch of DNA the two share. The API is programmatic access to the same scan, the same panel and the same thresholds behind every Ancient Matches report on the site, for organisations that handle many samples rather than one.
It is deliberately narrow. You send a raw DNA export or a whole-genome VCF with a reference of your own and a consent statement. No sex, no declared ancestry and never a name. You receive data only: the matched individuals with where and when they lived, each shared segment by chromosome and position, and a roll-up by population. There is no artwork and no map in the response, because the presentation is yours to design.
Two things it is not. The method is identity by state: stretches where two genomes read the same. A match is shared ancestral background with the population that person belonged to, never descent from that individual, and your product should say so. And it is not instant: a scan takes up to two hours and scans run one at a time, so a sample usually completes the same day and your integration polls or receives a webhook.
One exchange, three calls
Exchangeillustrative, not a contract
Authorization: Bearer anc_your_api_keyfile=@sample-0001.txtmetadata={ "externalId": "cust-0001", "rawDataSource": "TwentyThreeAndMe", "consent": { "geneticDataProcessing": true, "authorityToSubmit": true }}HTTP 201 Created{ "id": "ord_01j9m", "status": "received" }
HTTP 200 OK{ "id": "ord_01j9m", "externalId": "cust-0001", "environment": "live", "status": "completed", "resultAvailable": true}received, analysing,completed
HTTP 200 OK{ "method": "ibs", "totalMatches": 214, "returnedMatches": 200, "populations": [ { "population": "Italy_Imperial", "totalCm": 412.6, "individualCount": 71 } ], "matches": [{ "rank": 1, "sampleId": "I00001", "population": "Italy_Imperial", "totalCm": 18.4, "segmentCount": 3, "longestCm": 6.9, "country": "Italy", "dateBp": 1850, "dateLabel": "1 to 200 AD", "segments": [ { "chromosome": 6, "startBp": 31204518, "endBp": 38977120, "lengthCm": 6.9, "informativeSnps": 412, "snpsPerCm": 59.7 } ] }]}
A whole integration: submit, poll or receive a webhook, read the matches. The numbers are illustrative and the lists are cut short; the paths and field names are the real ones.
What you can build on it
Self-serve from day one
Create a company account, make up to five keys and buy credits by card, 1 to 50 at a time. 15 EUR per delivered sample, whole-genome files included, and credits never expire.
Data only, yours to present
Every matched individual with population, locality, country, coordinates, date, haplogroups, coverage and publication, and every shared segment by chromosome, start, end, length and marker count, as JSON.
A free sandbox, the same key
One key works on both environments. The sandbox validates your file and metadata exactly as production does, answers with a fixed invented result, and never spends a credit.
Calibrated thresholds
A shared stretch is reported only when it clears a minimum length, a minimum marker count and a minimum marker density. The thresholds are calibrated so that shuffled, unrelated genotypes produce zero matches, and every result states them.
Webhooks or polling
A scan takes up to two hours, so samples are asynchronous. Poll the order, or register a signed webhook and let us call you when it completes, is declined or fails.
Your data, in the EU
Samples are pseudonymous, and the DNA is stored and scanned on our own servers in Germany and Finland under GDPR. Delete a sample by API at any time; the raw DNA is erased 30 days after delivery.
How a sample moves through the pipeline
Receive
Sample accepted
Formats23andMe · AncestryDNA · MyHeritage · FTDNA · VCFA raw microarray export or a whole-genome VCF, validated by its content rather than by vendor. A credit is reserved, not charged.
Align
Aligned to the panel
Alignmentchromosome and position · GRCh37Matched on chromosome and coordinate, never on marker name. Strand-ambiguous positions, indels and mismatches are dropped, and the result counts each class.
Scan
Compared one person at a time
Panel13,000+ individuals · 3000 BC to 1400 ADEvery ancient individual in the panel, across the 22 autosomes, entirely on our own servers. Scans run one at a time and each takes up to two hours.
Judge
Held to calibrated thresholds
ThresholdscM · informative SNPs · SNPs per cMA stretch is reported only when it clears all three. The density rule is what stops a long, thinly covered run from being presented as a strong match.
Deliver
Matches returned
DeliveryJSON · webhook or poll · data onlyReleased to your next poll or announced to your webhook when the scan completes. The credit is charged at this moment, not before.
The numbers behind every scan
- Method
- Identity by state: stretches where the sample and an ancient individual read the same, found by a calibrated automated scan.
- Reference panel
- >13,000 individualsPublished ancient individuals dated 3000 BC to 1400 AD, compared one at a time.
- Matches listed
- 200 at mostThe list holds the strongest matches in full detail. The totals and the population roll-up cover every match the scan found.
- Thresholds
- minimum cM · minimum informative SNPs · minimum SNPs per cM. Calibrated so that shuffled, unrelated genotypes produce zero matches, and stated in every result.
- Per match
- rank, sampleId, population, totalCm, segmentCount, longestCm, informativeSnps, calledSites, locality, country, latitude, longitude, dateBp, dateLabel, yHaplogroup, mtHaplogroup, coverage, publication.
- Per segment
- chromosome, startBp, endBp, lengthCm, informativeSnps, snpsPerCm, on GRCh37.
- Validated on
- Samples of European ancestry. The scan runs on any sample, and other ancestries yield fewer matches.
- In progress at once
- 25 samplesPer product. Submit more as earlier samples complete.
- Data location
- Our own servers in Germany and Finland, under GDPR.
What you integrate
- POST
/v1/partner/ancient-matches/ordersSubmit a DNA file with your externalId and the consent statement. The externalId is the idempotency key, so a retry never creates a second sample.
- GET
/v1/partner/ancient-matches/orders/{id}Poll the sample: received, analysing, then completed, declined or failed. in_review means a scan stopped and our staff are looking at it. Or receive a signed webhook.
- GET
/v1/partner/ancient-matches/orders/{id}/resultRead the panel, the thresholds, the alignment, the population roll-up and the strongest 200 matches with every segment.
- DELETE
/v1/partner/ancient-matches/orders/{id}Erase the file, the analysis and the result of one sample, at any time.
- POST
/v1/partner/uploadsOpen an upload for a large file such as a whole-genome VCF, then pass its uploadId when you submit.
These are the real paths. The full reference, with upload completion, order listing, webhooks, errors and code samples, is in the Developers area of every company account.
Data and compliance
DNA files are stored and scanned on our own servers in the European Union, in Germany and Finland, under GDPR, and the scan itself runs entirely there, with no outside service involved. A whole-genome VCF is converted to the panel's markers at upload and the original is not stored. Files are never matched against other customers' files, and there is no cross-customer database of any kind.
For an organisation this means a data processing agreement, deletion by API at any time, and raw DNA erased 30 days after a result is delivered. Samples reach us under your own reference, never a name, and the scan needs neither the person's sex nor their origins. Our subprocessor list names every provider by category and location, including the few outside the European Economic Area, and none of those ever receives a DNA file. The operator is a registered sole trader in Albania; the legal notice and the privacy notice apply to API traffic as they do to the site.
The privacy notice and the legal notice name the controller and the hosting. What a match does and does not mean is set out on the Ancient Matches page.
Who it is for
Consumer DNA-testing companies
Add an ancient-individuals feature to a product that ships an ethnicity estimate today, designed in your own brand, with evidence a customer can check.
Genetic-genealogy services and labs
Scan many kits without curating an ancient reference panel, its metadata and a calibrated segment scan yourselves.
Research groups and consultancies
Put a cohort through one consistent panel and one consistent set of thresholds, and keep every segment.
Questions
Is this the same scan as the Ancient Matches report on the site?
Yes. The same panel, the same alignment, the same thresholds and the same scan. The API changes how samples arrive and how results leave, and it leaves out the presentation: you receive the data and design the experience yourself.
Can I sign up and get an API key today?
Yes. Create a company account, confirm your email and make a key in the Developers area. The same key works on the free sandbox and in production, and it buys qpAdm as well as Ancient Matches.
What does a result contain?
The method, the panel, the thresholds the scan applied, how the file aligned, the total number of matches, a roll-up by population, and the strongest 200 matches. Each match carries the individual's population, locality, country, coordinates, date, haplogroups, coverage and publication, and every shared segment with its chromosome, start, end, length in centimorgans and marker evidence on GRCh37.
What does a match mean?
That the sample and that ancient individual read the same along a stretch of the genome long enough and densely enough covered to clear the thresholds. The method is identity by state. It is evidence that both draw on the same ancestral population, and it is never proof of descent from that person. We ask every company to present it that way.
Does somebody check each result by hand?
No. Ancient Matches is a calibrated automated scan, and its result is released as soon as the scan completes. Nobody edits or ranks the matches by hand. If a scan stops, the sample shows in_review while our staff look at it, and it then completes, is declined or fails.
How long does a sample take?
A scan takes up to two hours and scans run one at a time, so a sample usually completes the same day. Your integration polls the order or receives a signed webhook. You can have at most 25 samples in progress per product.
What does it cost?
15 EUR per delivered sample, whole-genome files included. You buy credits by card, 1 to 50 at a time, and they never expire. One credit buys one delivered sample of either product. A credit is reserved when you submit and charged only when the scan completes; it is returned if the file cannot be read or we decline the sample. The sandbox is free. For larger volumes, write to info@ancestrify.io.
Does it work for every ancestry?
It runs on any sample, but it is validated on samples of European ancestry, and other ancestries yield fewer matches. We quote no typical match count: it is a fact about the sample and about the published ancient record.
Where is the data processed and how long is it kept?
The DNA is stored and scanned on our own servers in Germany and Finland under GDPR, and no provider outside the European Economic Area ever receives it. You can delete a sample by API at any time, which erases the file, the analysis and the result, the raw DNA is erased 30 days after delivery, and nothing is matched against other customers' files.
See the method first
The Ancient Matches page describes the scan in the words we use with our own customers, including what a shared stretch does not mean. Ancient DNA matches explained reads the centimorgan figures and the three thresholds, and the free Raw DNA File Check says in advance what a file can support.
The same key and the same credits also buy qpAdm: qpAdm via API returns formally tested ancestry models from the same kind of file, and one credit buys one delivered sample of either product.
Create a company account and send your first sample today.
Sign up as a company, create a key and test against the free sandbox. There is nothing to request and nobody to wait for. For volume pricing, invoicing or a data processing agreement, write to info@ancestrify.io.