Custom SNP Lists

Custom SNP Lists allow you to generate personalized SNP files for your profiles. Given a predefined list of SNPs (managed by SelfDecode), the system extracts each profile's genotypes for those SNPs and produces a downloadable file in your chosen format (TXT or CSV).

Prerequisites

• A profile must exist for the user.
• The profile must have a genome file. If the profile doesn't have one yet, provide the file_id (returned from the upload-file endpoint) when creating the SNP file job. Once the genome file is linked, you won't need to pass file_id for subsequent jobs on that profile.
• The SNP list you reference must be provisioned by SelfDecode — contact your account manager to request new lists.

SNP File Jobs

Each SNP file job represents the full pipeline to generate a custom SNP file for a given profile and SNP list. Creating a job automatically initiates the pipeline. You can track the job for status updates or errors as it progresses.

Job Lifecycle

SNP file jobs progress through the following statuses:

Status	Description
init	Job created, pending processing.
profile_upserted	Profile has been created or verified.
waiting_file_processing	Genome file is being uploaded/processed.
file_processed	Genome file is ready; SNP extraction pending.
waiting_report_gen	SNP file generation has been queued.
report_generated	SNP file is ready for download. Terminal success state.

Failed statuses:

Status	Description
failed_downloading_file	Could not download the genome file.
failed_uploading_file	Could not upload the genome file for processing.
failed_file_processing	Genome file processing failed.
failed_report_gen	SNP file generation failed.

Note: Once a job reaches report_generated, a webhook notification is sent (if configured) and the result_url field is populated with a presigned S3 download URL.

Creating a SNP File Job

POST https://selfdecode.com/service/b2b-integrations/snp-file-job/

Payload (profile already has a genome file):

JSON

{
  "profile_id": "1ca85f64-5717-4562-b3fc-2c963f66afa6",
  "snp_list": "my-snp-list-slug",
  "format": "txt"
}

Payload (first time — genome file not yet processed):

JSON

{
  "profile_id": "1ca85f64-5717-4562-b3fc-2c963f66afa6",
  "snp_list": "my-snp-list-slug",
  "file_id": "162357df-e111-4792-8c42-6369d43d52fd",
  "format": "csv"
}

Response (201 Created):

JSON

{
  "id": "a3b2c1d0-1234-5678-9abc-def012345678",
  "user_id": "d4e5f6a7-8901-2345-6789-abcdef012345",
  "profile_id": "1ca85f64-5717-4562-b3fc-2c963f66afa6",
  "snp_list": "my-snp-list-slug",
  "status": "file_processed",
  "handling_failed": false,
  "error": "",
  "result_url": "",
  "created_at": "2025-03-09T12:00:00Z",
  "finished_at": null
}

Field Reference

Field	Type	Description
profile_id	UUID	Required. The profile to generate the SNP file for.
snp_list	string	Required. Slug of the SNP list to use.
file_id	UUID	Optional. Genome file ID from the upload-file endpoint. Only needed if the profile doesn't have a genome file yet.
format	string	Optional. Output file format: txt (23andMe format) or csv. Default: txt.

Fetching SNP File Jobs

List

GET https://selfdecode.com/service/b2b-integrations/snp-file-job/

Supports filtering by:

Parameter	Type	Description
profile_id	UUID (comma-separated)	Filter by one or more profile IDs.
snp_list	string	Filter by SNP list slug.
status	string	Filter by job status.
created_at_gte	datetime	Jobs created on or after this timestamp.
created_at_lte	datetime	Jobs created on or before this timestamp.

Example:

GET /snp-file-job/?profile_id=1ca85f64-5717-4562-b3fc-2c963f66afa6&status=report_generated

Retrieve

Individual jobs can be retrieved by their ID:

GET https://selfdecode.com/service/b2b-integrations/snp-file-job/{id}/

Note: On retrieve, the result_url is always refreshed with a new presigned URL valid for 24 hours. This means you can call retrieve at any time to get a fresh download link, even if the original URL has expired.

Downloading the SNP File

Once a job reaches report_generated, the result_url field contains a presigned S3 URL pointing to the generated file. The URL is valid for 24 hours.

• On list: The result_url reflects the value stored at completion time (may have expired).
• On retrieve: The result_url is always regenerated with a fresh 24-hour expiry.

The downloaded file is named in the format: {snp-list-slug}-v{version}-{random}.{format}

Output Formats

TXT (default)

23andMe-compatible format. Use "format": "txt" or omit the field (default).

Warning: TXT format cannot represent indels (insertions/deletions) — they will be excluded from the output. Use CSV format if your SNP list includes indels.

CSV

Tabular format with genotype calls. Use "format": "csv".

CSV columns:

Column	Description
rsid	The SNP identifier (e.g. rs4680).
ref	Reference allele.
alt	Alternate allele.
gt1	First genotype call (0 = reference, 1 = alternate).
gt2	Second genotype call (0 = reference, 1 = alternate).

Example:

csv

"rsid","ref","alt","gt1","gt2"
"rs1799971","A","G","0","0"
"rs6265","C","T","0","0"
"rs4680","G","A","1","0"

Error Handling

If a job fails, the error field contains a human-readable error message. The handling_failed flag is set to true if the job encountered an unrecoverable infrastructure error.

To retry a failed job, create a new SNP file job with the same profile_id and snp_list.

Webhooks

SNP file jobs support webhook notifications. When a job reaches report_generated or a failed status, a webhook is dispatched if configured.

The webhook payload uses job_type: "snp_file_job". Please check our webhooks guide for detailed instructions on configuring webhooks.

Example webhook payload:

JSON

{
  "id": "a3b2c1d0-1234-5678-9abc-def012345678",
  "user_id": "d4e5f6a7-8901-2345-6789-abcdef012345",
  "profile_id": "1ca85f64-5717-4562-b3fc-2c963f66afa6",
  "snp_list": "my-snp-list-slug",
  "status": "report_generated",
  "handling_failed": false,
  "error": "",
  "result_url": "https://s3.amazonaws.com/...",
  "created_at": "2025-03-09T12:00:00Z",
  "finished_at": "2025-03-09T12:05:00Z",
  "job_type": "snp_file_job"
}