API Reference

Welcome to the documentation for our current API endpoints. Our deprecated (but still supported) API endpoints can be found here, although we encourage you to use the ones listed below.


Some 23andMe API endpoints return non-user-specific reference data and provide unrestricted access, while others return user-specific data and thus require the user's authorization.

Authorization

API requests for profile-level data use OAuth 2.0 bearer tokens over SSL in the Authorization header (read through our authorization reference to find out how to get a token). If you get a non-200 response, check this list of errors.

Your token grants access to data from the customer who authorized it. For example:

curl "https://api.23andme.com/3/account/" -H "Authorization: Bearer 081239h0f71hf"

For development, you can skip the OAuth flow by using a demo token, demo_oauth_token, to fetch sample data. Example:

curl "https://api.23andme.com/3/account/" -H "Authorization: Bearer demo_oauth_token"

Data returned for the demo token is not linked to a real account and is for testing purposes only.

Enveloping

Every endpoint returning a list of resources is "enveloped" to include a link for the next "page" of data, if it exists. Example:

    {
        "data": [resources...],
        "links": {
            "next": "https://api.23andme.com/3/marker/?accession_id=NC_000002.11&start=47807&end=48607"
        }
    }
    

Though the next link may be null if pagination is not supported or there are no additional pages, lists of resources will always be enveloped in this manner.


Account & Profile Endpoints


Account Object

A user signs into their account. An account may own one or more profiles.

id
string
the unique id associated with the account
first_name
string
the first name of the account owner
last_name
string
the last name of the account owner
email
string
the email of the account owner
profiles
list
a list of profile ids (or objects - see the include parameter) owned by this account
endpoint required scope example call and result

GET /3/account/

parameters:
  • include string, optional
Requires OAuth requires token Back To Top ↑
basic names email

Returns a list containing the user account associated with the token.

curl "https://api.23andme.com/3/account/" \
 -H "Authorization: Bearer demo_oauth_token"
# JSON response:
{
    "data": [
        {
            "id": "demo_account_id",
            "first_name": "Erin",
            "last_name": "Mendel",
            "email": "erinmendel+nobody@23andme.com",
            "profiles": [
                {
                    "id": "demo_profile_id"
                }
            ]
        }
    ],
    "links": {
        "next": null
    }
}

The optional include parameter can be set to profiles to expand the list of profile ids into profile objects:

curl "https://api.23andme.com/3/account/?include=profiles" \
 -H "Authorization: Bearer demo_oauth_token"
# JSON response:
{
    "data": [
        {
            "id": "demo_account_id",
            "first_name": "Erin",
            "last_name": "Mendel",
            "email": "erinmendel+nobody@23andme.com",
            "profiles": [
                {
                    "id": "demo_profile_id",
                    "first_name": "Erin",
                    "last_name": "Mendel",
                    "is_genotyped": true
                }
            ]
        }
    ],
    "links": {
        "next": null
    }
}

GET /3/account/account_id

parameters:
  • include string, optional
Requires OAuth requires token Back To Top ↑
basic names email

Returns the account for the specified account_id (will 403 if the account_id is not the one authorized for the token).

curl "https://api.23andme.com/3/account/demo_account_id/" \
 -H "Authorization: Bearer demo_oauth_token"
# JSON response:
{
    "id": "demo_account_id",
    "first_name": "Erin",
    "last_name": "Mendel",
    "email": "erinmendel+nobody@23andme.com",
    "profiles": [
        {
            "id": "demo_profile_id"
        }
    ]
}

The optional include parameter can be set to profiles to expand the list of profile ids into profile objects:

curl "https://api.23andme.com/3/account/demo_account_id/?include=profiles" \
 -H "Authorization: Bearer demo_oauth_token"
# JSON response:
{
    "id": "demo_account_id",
    "first_name": "Erin",
    "last_name": "Mendel",
    "email": "erinmendel+nobody@23andme.com",
    "profiles": [
        {
            "id": "demo_profile_id",
            "first_name": "Erin",
            "last_name": "Mendel",
            "is_genotyped": true
        }
    ]
}
Profile Object

Each customer that has submitted a DNA sample has a profile. Each profile belongs to an account, which manages one or more profiles.

id
string
the unique id associated with the profile
first_name
string
the first name of the profile owner
last_name
string
the last name of the profile owner
is_genotyped
boolean
true if the profile has been genotyped
endpoint required scope example call and result

GET /3/profile/

parameters:

  • account_id string

Requires OAuth requires token Back To Top ↑
basic names email

Returns a list of active profiles owned by the account. The account_id must be provided.

curl "https://api.23andme.com/3/profile/?account_id=demo_account_id" \
 -H "Authorization: Bearer demo_oauth_token"
# JSON response:
{
    "data": [
        {
            "id": "demo_profile_id",
            "first_name": "Erin",
            "last_name": "Mendel",
            "is_genotyped": true
        }
    ],
    "links": {
        "next": null
    }
}

GET /3/profile/profile_id

Requires OAuth requires token Back To Top ↑
basic names email

Returns a single profile for the given profile_id.

curl "https://api.23andme.com/3/profile/demo_profile_id/" \
 -H "Authorization: Bearer demo_oauth_token"
# JSON response:
{
    "id": "demo_profile_id",
    "first_name": "Erin",
    "last_name": "Mendel",
    "is_genotyped": true
}

Genetic Data Endpoints


Accession Object

23andMe uses the NCBI build 37 reference assembly. This is a set of standardized reference sequences where each accession corresponds to a chromosome (1-22, X, Y, & Mitochondrial). These endpoints will provide high-level reference data about the accession. For more in-depth exploration of the reference genome sequences, download seqseek and use Build 37.

id
string
the accession id associated with the chromosome
chromosome
string
the chromosome name (1-22, X, Y, and MT for mitochondrial)
length
integer
the nucleotide length of the chromosome
endpoint example call and result

GET /3/accession/

parameters:

  • chromosome string, optional

Back To Top ↑

Returns a list of accessions available on 23andMe platforms.

curl "https://api.23andme.com/3/accession/"
# JSON response:
{
    "data": [
        {
            "id": "NC_000001.10",
            "chromosome": "1",
            "length": 249250621
        },
        {
            "id": "NC_000002.11",
            "chromosome": "2",
            "length": 243199373
        },
        ...
    ],
    "links": {
        "next": null
    }
}

The optional chromosome parameter can be used to request the accession information for a single chromosome. If this parameter is provided, the next link will paginate through subsequent chromosomes.

curl "https://api.23andme.com/3/accession/?chromosome=1"
# JSON response:
{
    "data": [
        "id": "NC_000001.10",
        "chromosome": "1",
        "length": 249250621
    ],
    "links": {
        "next": https://api.23andme.com/3/accession/?chromosome=2
    }
}

GET /3/accession/accession_id

Back To Top ↑

Returns a single accession.

curl "https://api.23andme.com/3/accession/NC_000001.10"
# JSON response:
{
    "id": "NC_000001.10",
    "chromosome": "1",
    "length": 249250621
}
Marker Object

A marker is an identifier for multiple alleles that may exist at a genetic locus, or region, on a chromosome. Most of the markers will use the standardized NCBI rs# (reference SNP cluster id) that can be searched for in dbSNP, but others have "i-ids" (they start with i), which are internal to 23andMe and will not exist in dbSNP.

id
string
the primary id for the marker
alternate_ids
list
alias ids for the marker
gene_names
list
the display names of any genes at the marker
accession_id
string
the unique id for the accession on which the marker is found
start
integer
the chromosomal location of the start of the marker (counting from 0)
end
integer
the chromosomal location of the end of the marker (counting from 0)
variants
list
the different possible variants at this marker
endpoint example call and result

GET /3/marker/

parameters:

  • gene_name string
or
  • accession_id string
  • start integer, optional, default 0
  • end integer, optional, default start + 10000, min 0, max is the last end position of the specified accession (length + 1)
  • limit integer, optional, default 100, min 1, max 10000
  • offset integer, optional, default 0, min 0

Back To Top ↑

Gets a list of genetic markers ordered by their start and end positions. Must use one of either gene_name or accession_id. Optionally, start and end can be used with accession_id, using limit and offset to page through results. Note that the offset is automatically incremented by limit in the next link of the resource envelope. Additionally, if the number of returned items is 0 or less than the limit, then all results have been exhausted.

The gene_name parameter will return a list of markers for that gene.

curl "https://api.23andme.com/3/marker/?gene_name=ACTN3"

The accession_id parameter will return a list of markers on that chromosome.

curl "https://api.23andme.com/3/marker/?accession_id=NC_012920.1"
# JSON response:
{
    "data": [
        {
            "id": "i4001200",
            "alternate_ids": [],
            "gene_names": [],
            "accession_id": "NC_012920.1",
            "start": 2,
            "end": 3,
            "variants": [
                {
                    "accession_id": "NC_012920.1",
                    "start": 2,
                    "end": 3,
                    "allele": "C"
                },
                {
                    "accession_id": "NC_012920.1",
                    "start": 2,
                    "end": 3,
                    "allele": "T"
                }
            ]
        },
        {
            "id": "i4001110",
            "alternate_ids": [],
            "gene_names": [],
            "accession_id": "NC_012920.1",
            "start": 6,
            "end": 7,
            "variants": [
                {
                    "accession_id": "NC_012920.1",
                    "start": 6,
                    "end": 7,
                    "allele": "A"
                },
                {
                    "accession_id": "NC_012920.1",
                    "start": 6,
                    "end": 7,
                    "allele": "G"
                }
            ]
        },
        {
            "id": "i4001358",
            "alternate_ids": [],
            "gene_names": [],
            "accession_id": "NC_012920.1",
            "start": 8,
            "end": 9,
            "variants": [
                {
                    "accession_id": "NC_012920.1",
                    "start": 8,
                    "end": 9,
                    "allele": "A"
                },
                {
                    "accession_id": "NC_012920.1",
                    "start": 8,
                    "end": 9,
                    "allele": "G"
                }
            ]
        },
        ...
    ],
    "links": {
        "next": "https://api.23andme.com/3/marker/?accession_id=NC_012920.1&limit=100&offset=100"
    }
}

When used with accession_id, the start parameter will load markers with end positions greater than or equal to this value. It must be greater than or equal to 0 and less than the length of the accession. It is 0 by default.

The end parameter will load markers with start positions less than or equal to end. It must be greater than or equal to 0 and less than the length of the specified accession. It is start + 10000 by default.

Note that markers returned inside the specified start and end range do not have to be entirely contained within that range. Any overlapping markers will be returned.

start and end can be used to page through the markers for the specified accession_id by incrementing the offset by limit. For example, limit=10 and offset=0 will return items 1-10. Furthermore, limit=10 and offset=10 will return items 11-20.

curl "https://api.23andme.com/3/marker/?accession_id=NC_000015.9&start=75042285&end=75042485&limit=1&offset=0"
# JSON response:
{
    "data": [...],
    "links": {
        "next": "https://api.23andme.com/3/marker/?accession_id=NC_000015.9&start=75042285&end=75042485&limit=1&offset=1"
    }
}

In the above example, the next link contains an auto-incremented offset, which will return the next page of data. This process can be repeated until the number of items returned is 0 or less than the limit.

GET /3/marker/marker_id

Back To Top ↑

Returns a single marker.

curl "https://api.23andme.com/3/marker/rs10195681"
# JSON response:
{
    "id": "rs10195681",
    "alternate_ids": [],
    "gene_names": [],
    "accession_id": "NC_000002.11",
    "start": 18673,
    "end": 18674,
    "variants": [
        {
            "accession_id": "NC_000002.11",
            "start": 18673,
            "end": 18674,
            "allele": "A"
        },
        {
            "accession_id": "NC_000002.11",
            "start": 18673,
            "end": 18674,
            "allele": "C"
        }
    ]
}

In the event that there are multiple markers for the same set of variants, the other, "alias" marker ids of the requested marker will be listed under the alternate_ids attribute of the returned object. For example:

curl "https://api.23andme.com/3/marker/i5019493"
# JSON response:
{
    "id": "i5019493",
    "alternate_ids": ['i5035002'],
    ...
}

i5035002 is an alias for the requested marker, i5019493.

Profile Marker Object

In addition to the reference data provided by the marker object, the profile marker includes genetic data specific to a profile owner's genotype.

. . . (same attributes as marker; instead of variant objects, variants will be a list of profile variants.)
is_genotyped
boolean
true if the profile marker has been successfully genotyped for the profile (i.e. true if is_assayed is true and is_no_call is false).
is_assayed
boolean
true if all profile variants were assayed for the profile marker
is_no_call
boolean
true if the assay was performed and there were no results for any of the the profile marker's profile variants
endpoint required scope example call and result

GET /3/profile/profile_id/marker/

parameters:

  • gene_name string
or
  • accession_id string
  • start integer, optional, default 0
  • end integer, optional, default start + 10000, min 0, max is the last end position of the specified accession (length + 1)
  • limit integer, optional, default 100, min 1, max 10000
  • offset integer, optional, default 0, min 0

Requires OAuth requires token Back To Top ↑
  • genomes - all genetic loci
or
  • accession:<accession_id> - all genetic loci on the specified accession. Example:
    accession:NC_000023.10
or
  • [marker_id (SNP), ...] for each requested marker. Example:
    rs3784780 i4000396

Additionally, the profile owner must opt into the Raw Data Tool before their genetic information can be accessed.

For a user's profile, gets a list of profile markers ordered by their start and end positions.

Accepts the same request parameters as GET /marker.

curl "https://api.23andme.com/3/profile/demo_profile_id/marker/?accession_id=NC_012920.1" \
 -H "Authorization: Bearer demo_oauth_token"
# JSON response:
{
    "data": [
        {
            "id": "i4001200",
            "alternate_ids": [],
            "gene_names": [],
            "accession_id": "NC_012920.1",
            "start": 2,
            "end": 3,
            "is_genotyped": true,
            "is_assayed": true,
            "is_no_call": false,
            "variants": [
                {
                    "accession_id": "NC_012920.1",
                    "start": 2,
                    "end": 3,
                    "allele": "C",
                    "dosage": 0,
                    "is_assayed": true,
                    "is_no_call": false
                },
                {
                    "accession_id": "NC_012920.1",
                    "start": 2,
                    "end": 3,
                    "allele": "T",
                    "dosage": 1,
                    "is_assayed": true,
                    "is_no_call": false
                }
            ]
        },
        {
            "id": "i4001110",
            "alternate_ids": [],
            "gene_names": [],
            "accession_id": "NC_012920.1",
            "start": 6,
            "end": 7,
            "is_genotyped": false,
            "is_assayed": false,
            "is_no_call": false,
            "variants": [
                {
                    "accession_id": "NC_012920.1",
                    "start": 6,
                    "end": 7,
                    "allele": "A",
                    "dosage": null,
                    "is_assayed": false,
                    "is_no_call": false
                },
                {
                    "accession_id": "NC_012920.1",
                    "start": 6,
                    "end": 7,
                    "allele": "G",
                    "dosage": null,
                    "is_assayed": false,
                    "is_no_call": false
                }
            ]
        },
        {
            "id": "i4001358",
            "alternate_ids": [],
            "gene_names": [],
            "accession_id": "NC_012920.1",
            "start": 8,
            "end": 9,
            "is_genotyped": false,
            "is_assayed": false,
            "is_no_call": false,
            "variants": [
                {
                    "accession_id": "NC_012920.1",
                    "start": 8,
                    "end": 9,
                    "allele": "A",
                    "dosage": null,
                    "is_assayed": false,
                    "is_no_call": false
                },
                {
                    "accession_id": "NC_012920.1",
                    "start": 8,
                    "end": 9,
                    "allele": "G",
                    "dosage": null,
                    "is_assayed": false,
                    "is_no_call": false
                }
            ]
        }
        ...
    ],
    "links": {
        "next": "https://api.23andme.com/3/profile/demo_profile_id/marker/?accession_id=NC_012920.1&limit=100&offset=100"
    }
}

GET /3/profile/profile_id/marker/marker_id

Requires OAuth requires token Back To Top ↑
  • genomes - all genetic loci
or
  • accession:<accession_id> - all genetic loci on the specified accession. Example:
    accession:NC_000023.10
or
  • [id, ...] for each requested marker. Example:
    rs3784780 i4000396

Additionally, the profile owner must opt into the Raw Data Tool before their genetic information can be accessed.

For a user's profile, returns a single profile marker.

curl "https://api.23andme.com/3/profile/demo_profile_id/marker/rs10195681" \
 -H "Authorization: Bearer demo_oauth_token"
# JSON response:
{
    "id": "rs10195681",
    "alternate_ids": [],
    "gene_names": [],
    "accession_id": "NC_000002.11",
    "start": 18673,
    "end": 18674,
    "is_genotyped": true,
    "is_assayed": true,
    "is_no_call": false,
    "variants": [
        {
            "accession_id": "NC_000002.11",
            "start": 18673,
            "end": 18674,
            "allele": "A",
            "dosage": 0,
            "is_assayed": true,
            "is_no_call": false
        },
        {
            "accession_id": "NC_000002.11",
            "start": 18673,
            "end": 18674,
            "allele": "C",
            "dosage": 2,
            "is_assayed": true,
            "is_no_call": false
        }
    ]
}

In the event that there are multiple profile markers for the same set of variants, the other, "alias" marker ids of the requested profile marker will be listed under the alternate_ids attribute of the returned object. For example:

curl "https://api.23andme.com/3/marker/i5019493"
# JSON response:
{
    "id": "i5019493",
    "alternate_ids": ['i5035002'],
    ...
}

i5035002 is an alias for the requested profile marker, i5019493.

Variant Object

A variant, or allele, is a possible variation at a genetic locus, or region, on a chromosome. The set of variants at a locus may be denoted by a particular marker.

accession_id
string
the unique id for the accession to which the variant belongs
start
integer
the chromosomal location of the start of the variant (counting from 0)
end
integer
the chromosomal location of the end of the variant (counting from 0)
allele
string
the nucleotide sequence of the variant
endpoint example call and result

GET /3/variant/

parameters:

  • accession_id string
  • start integer, optional, default 0
  • end integer, optional, default start + 10000, min 0, max is the last end position of the specified accession (length + 1)
  • limit integer, optional, default 100, min 1, max 10000
  • offset integer, optional, default 0, min 0

Back To Top ↑

Gets a list of variants ordered by start, end. The accession_id must be specified.

curl "https://api.23andme.com/3/variant/?accession_id=NC_012920.1"
# JSON response:
{
    "data": [
        {
            "accession_id": "NC_012920.1",
            "start": 1001,
            "end": 1002,
            "allele": "C"
        },
        {
            "accession_id": "NC_012920.1",
            "start": 1001,
            "end": 1002,
            "allele": "T"
        },
        ...
    ],
    "links": {
        "next": "https://api.23andme.com/3/variant/?accession_id=NC_012920.1&limit=100&offset=100"
    }
}

The start parameter will load variants with end positions greater than or equal to this value. It must be greater than or equal to 0 and less than the length of the accession. It is 0 by default.

The end parameter will load variants with start positions less than or equal to end. It must be greater than or equal to 0 and less than the length of the specified accession. It is start + 10000 by default.

Note that variants returned inside the specified start and end range do not have to be entirely contained within that range. Any overlapping variants will be returned.

start and end can be used to page through the variants for the specified accession_id by incrementing the offset by limit. For example, limit=10 and offset=0 will return items 1-10. Furthermore, limit=10 and offset=10 will return items 11-20.

curl "https://api.23andme.com/3/variant/?accession_id=NC_000015.9&start=75042285&end=75042485"
# JSON response:
{
    "data": [...],
    "links": {
        "next": "https://api.23andme.com/3/variant/?accession_id=NC_000015.9&start=75042385&end=75042485&limit=100&offset=100"
    }
}

In the above example, the next link contains an auto-incremented offset, which will return the next page of data. This process can be repeated until the number of items returned is 0 or less than the limit.

Profile Variant Object

In addition to the reference data provided by the variant object, the profile variant includes genetic data specific to a profile owner's genotype.

. . . (same attributes as variant)
dosage
integer
the occurrence of the allele in the profile owner's genotype (0: no occurrences of the allele, 1: heterozygous, 2: homozygous)
is_assayed
boolean
true if the profile variant has been assayed
is_no_call
boolean
true if the assay was performed and there were no results
endpoint required scope example call and result

GET /3/profile/profile_id/variant/

parameters:

  • accession_id string
  • start integer, optional
  • end integer, optional, default start + 10000, min 0, max is the last end position of the specified accession (length + 1)
  • limit integer, optional, default 100, min 1, max 10000
  • offset integer, optional, default 0, min 0

Requires OAuth requires token Back To Top ↑
  • genomes - all genetic loci
or
  • accession:<accession_id> - all genetic loci on the specified accession. Example:
    accession:NC_000023.10
or
  • [marker_id (SNP), ...] for each marker associated with the requested variants. Example:
    rs3784780 i4000396

Additionally, the profile owner must opt into the Raw Data Tool before their genetic information can be accessed.

For the user's profile, gets a list of variants ordered by start, end.

Accepts the same request parameters as GET /variant.

curl "https://api.23andme.com/3/profile/demo_profile_id/variant/?accession_id=NC_012920.1" \
 -H "Authorization: Bearer demo_oauth_token"
# JSON response:
{
    "data": [
        {
            "accession_id": "NC_012920.1",
            "start": 1001,
            "end": 1002,
            "allele": "C",
            "dosage": null,
            "is_assayed": false,
            "is_no_call": false
        },
        {
            "accession_id": "NC_012920.1",
            "start": 1001,
            "end": 1002,
            "allele": "T",
            "dosage": null,
            "is_assayed": false,
            "is_no_call": false
        },
        ...
    ],
    "links": {
        "next": "https://api.23andme.com/3/profile/demo_profile_id/variant/?accession_id=NC_012920.1&limit=100&offset=100"
    }
}

Report Endpoints


Report Object

23andMe customers have access to a number of different genetic reports. Each report is represented by a report object containing reference data and schemata describing the data available in the corresponding profile report. While reports and profile reports both include static attributes such as the report_id and title, profile-level attributes in a profile report have values pertaining to a particular profile, whereas the corresponding attribute values in a report are data descriptors for that profile-level data. API developers can use this endpoint as a reference to inspect which reports are available, what attributes they contain, and what values the profile-level attributes may have - without having to obtain authorization to access a profile report. Each report object follows the same top-level format:

report_id
string
the unique id associated with the report. The API currently supports 7 wellness reports, the ids of which are listed below:

  • wellness.alcohol_flush
  • wellness.caffeine_consumption
  • wellness.deep_sleep
  • wellness.lactose
  • wellness.muscle_composition
  • wellness.sleep_movement
  • wellness.saturated_fat_and_weight
report_type
string
the report type (e.g. wellness)
title
string
the human-readable title of the report
about
object
background information including the report's purpose and intended use. The attributes of this object will vary depending on the report_type.
details
object
lower-level information about the report's results. The attributes of this object will vary depending on the report_type.
summary
object
a high-level summary of the report's results. The attributes of this object will vary depending on the report_type.

Data descriptors for profile-level attributes use the following schema:

type
string
The data descriptor will always include a type attribute indicating the standard JSON type of the described data:
  • integer
  • number (a decimal number)
  • boolean (true or false)
  • string
  • object (a JSON object)
  • array (a JSON array; indicates that the described data is a sequence of values)
required
boolean
Only included for non-array data types. true if the described data cannot be null.
enum
array
Only included for non-array data types whose range of values is confined to a finite set. An array consisting of those possible values.
properties
object
Only included for non-enum object data types. An object containing the attributes that comprise the described data. Attribute values may be static data, or may themselves be nested data descriptors.
items
object
Only included for array data types. A nested data descriptor describing the items in the array.
endpoint example call and result

GET /3/report/

Back To Top ↑

Gets a list of all reports available through the API. Each report object includes reference data describing the profile-level attributes in the corresponding profile report. See here for which reports are currently available.

curl "https://api.23andme.com/3/report/"
# JSON response:
{
    "data": [
        {
            "report_id": "wellness.alcohol_flush",
            "report_type": "wellness",
            "title": "Alcohol Flush Reaction",
            "about": {
                ...
            },
            "details": {
                ...
            },
            "summary": {
                ...
                "assessment": {
                    "type": "object",
                    "required": true,
                    "enum": [
                        {
                            "id": "little_flushing",
                            "message": "Unlikely to flush after drinking alcohol"
                        },
                        {
                            "id": "some_flushing_het",
                            "message": "Likely to flush after drinking alcohol"
                        },
                        {
                            "id": "some_flushing",
                            "message": "Likely to flush after drinking alcohol"
                        },
                        {
                            "id": "not_determined",
                            "message": "Variant not determined"
                        }
                    ]
                }
            }
        },
        {
            "report_id": "wellness.caffeine_consumption",
            ...
        },
        ...
    ],
    "links": {
        "next": null
    }
}

GET /3/report/report_id

Back To Top ↑

Gets the requested report, which includes reference data describing the profile-level attributes in the corresponding profile report. See here for which reports are currently available.

curl "https://api.23andme.com/3/report/wellness.muscle_composition/"
# JSON response:
{
    "report_id": "wellness.muscle_composition",
    "report_type": "wellness",
    "title": "Muscle Composition",
    "about": {
        "intended_uses": [
            "To test for the R577X variant in the ACTN3 gene."
        ],
        "limitations": [
            "Does not test for all possible variants related to muscle composition.",
            "Does not account for lifestyle or other factors that may affect muscle composition."
        ],
        "demographics": [
            "This report is relevant to people of all ethnicities."
        ]
    },
    "details": {
        "genes": [
            {
                "id": "ACTN3",
                "chromosome": "11",
                "gene_overview": "The ACTN3 gene contains instructions for making alpha-actinin-3, a protein found in certain types of fast-twitch muscle fibers. People who make this protein tend to have a greater proportion of fast-twitch muscle than people who don't make the protein. Thus, they can generate more power when their muscles contract.\n"
            }
        ],
        "markers": [
            {
                "id": "rs1815739",
                "label": "R577X",
                "alternate_ids": [],
                "gene_names": [
                    "ACTN3"
                ],
                "gene_description": "ACTN3",
                "mutation_type": "substitution",
                "biological_explanation": "The variant tested is a change from a C to a T in the DNA sequence of the ACTN3 gene. It results in no functional alpha-actinin-3 protein being made.\n",
                "accession_id": "NC_000011.9",
                "start": 66328094,
                "end": 66328095,
                "is_assayed": {
                    "type": "boolean",
                    "required": true
                },
                "is_determined": {
                    "type": "boolean",
                    "required": true
                },
                "is_genotyped": {
                    "type": "boolean",
                    "required": true
                },
                "is_no_call": {
                    "type": "boolean",
                    "required": true
                },
                "variants": [
                    {
                        "accession_id": "NC_000011.9",
                        "start": 66328094,
                        "end": 66328095,
                        "allele": "C",
                        "dosage": {
                            "type": "number",
                            "required": false
                        },
                        "is_no_call": {
                            "type": "boolean",
                            "required": true
                        },
                        "is_assayed": {
                            "type": "boolean",
                            "required": true
                        },
                        "has_effect": false
                    },
                    {
                        "accession_id": "NC_000011.9",
                        "start": 66328094,
                        "end": 66328095,
                        "allele": "T",
                        "dosage": {
                            "type": "number",
                            "required": false
                        },
                        "is_no_call": {
                            "type": "boolean",
                            "required": true
                        },
                        "is_assayed": {
                            "type": "boolean",
                            "required": true
                        },
                        "has_effect": true
                    }
                ],
                "known_mutations": [
                    {
                        "effect_allele": "T",
                        "typical_allele": "C",
                        "mutation_type": "substitution"
                    }
                ]
            }
        ]
    },
    "summary": {
        "is_determined": {
            "type": "boolean",
            "required": true
        },
        "has_effect": {
            "type": "boolean",
            "required": true
        },
        "effect_allele_count": {
            "type": "integer",
            "required": true
        },
        "no_call_marker_count": {
            "type": "integer",
            "required": true
        },
        "assessment": {
            "type": "object",
            "required": true,
            "enum": [
                {
                    "id": "functional_actn3",
                    "message": "Sprinter/power muscle type"
                },
                {
                    "id": "nonfunctional_actn3_het",
                    "message": "Sprinter/power muscle type"
                },
                {
                    "id": "nonfunctional_actn3",
                    "message": "Not sprinter/power muscle type"
                },
                {
                    "id": "not_determined",
                    "message": "Variant not determined"
                }
            ]
        }
    }
}
Profile Report Object

In place of the reference data contained in the report object, the profile report object contains actual results for a given profile and thus requires an authorized token with proper scope.

. . . (same attributes as report; instead of data descriptors, values for profile-level attributes will be actual report data for the given profile.)
endpoint required scope example call and result

GET /3/profile/profile_id/report/

Requires OAuth requires token Back To Top ↑
  • report:all - all reports
or
  • report:<report_id>, ... for each requested report. Example: report:wellness.deep_sleep report:wellness.lactose

The returned list of profile reports will be filtered by the report scopes on the token. If the token is not scoped for any reports, the response will 404.

Additionally, the profile owner must have access to their health data before their wellness reports can be accessed.

For the user's profile, gets a list of all profile reports available through the API and their results. See here for which profile reports are currently available.

curl "https://api.23andme.com/3/profile/demo_profile_id/report" \
 -H "Authorization: Bearer demo_oauth_token"
# JSON response:
{
    "data": [
        {
            "report_id": "wellness.alcohol_flush",
            "report_type": "wellness",
            "title": "Alcohol Flush Reaction",
            "about": {
                ...
            },
            "details": {
                ...
            },
            "summary": {
                ...
                "assessment": {
                    "id": "little_flushing",
                    "message": "Unlikely to flush after drinking alcohol"
                }
            }
        },
        {
            "report_id": "wellness.caffeine_consumption",
            ...
        }, ...
    ],
    "links": {
        "next": null
    {
}

GET /3/profile/profile_id/report/report_id

Requires OAuth requires token Back To Top ↑
  • report:all - all reports
or
  • report:<report_id>, ... for each requested report. Example: report:wellness.deep_sleep report:wellness.lactose
Additionally, the profile owner must have access to their health data before their wellness reports can be accessed.

For the user's profile, gets the requested profile report and its results. See here for which profile reports are currently available.

curl "https://api.23andme.com/3/profile/demo_profile_id/report/wellness.muscle_composition/" \
 -H "Authorization: Bearer demo_oauth_token"
# JSON response:
{
    "report_id": "wellness.muscle_composition",
    "report_type": "wellness",
    "title": "Muscle Composition",
    "about": {
        "intended_uses": [
            "To test for the R577X variant in the ACTN3 gene."
        ],
        "limitations": [
            "Does not test for all possible variants related to muscle composition.",
            "Does not account for lifestyle or other factors that may affect muscle composition."
        ],
        "demographics": [
            "This report is relevant to people of all ethnicities."
        ]
    },
    "details": {
        "genes": [
            {
                "id": "ACTN3",
                "chromosome": "11",
                "gene_overview": "The ACTN3 gene contains instructions for making alpha-actinin-3, a protein found in certain types of fast-twitch muscle fibers. People who make this protein tend to have a greater proportion of fast-twitch muscle than people who don't make the protein. Thus, they can generate more power when their muscles contract.\n"
            }
        ],
        "markers": [
            {
                "id": "rs1815739",
                "label": "R577X",
                "alternate_ids": [],
                "gene_names": [
                    "ACTN3"
                ],
                "gene_description": "ACTN3",
                "mutation_type": "substitution",
                "biological_explanation": "The variant tested is a change from a C to a T in the DNA sequence of the ACTN3 gene. It results in no functional alpha-actinin-3 protein being made.\n",
                "accession_id": "NC_000011.9",
                "start": 66328094,
                "end": 66328095,
                "is_assayed": true,
                "is_determined": true,
                "is_genotyped": true,
                "is_no_call": false,
                "variants": [
                    {
                        "accession_id": "NC_000011.9",
                        "start": 66328094,
                        "end": 66328095,
                        "allele": "C",
                        "dosage": 2,
                        "is_no_call": false,
                        "is_assayed": true,
                        "has_effect": false
                    },
                    {
                        "accession_id": "NC_000011.9",
                        "start": 66328094,
                        "end": 66328095,
                        "allele": "T",
                        "dosage": 0,
                        "is_no_call": false,
                        "is_assayed": true,
                        "has_effect": true
                    }
                ],
                "known_mutations": [
                    {
                        "effect_allele": "T",
                        "typical_allele": "C",
                        "mutation_type": "substitution"
                    }
                ]
            }
        ]
    },
    "summary": {
        "is_determined": true,
        "has_effect": false,
        "effect_allele_count": 0,
        "no_call_marker_count": 0,
        "assessment": {
            "id": "functional_actn3",
            "message": "Sprinter/power muscle type"
        }
    }
}