API Documentation
A submission API has been developed to allow programmatic submissions to the IPD-IMGT/HLA Database. This is suitable for high-throughput organisations that can submit dozens or hundreds of sequences per month. Use of the API requires prior approval from IPD-IMGT/HLA.
Become and approved API submitter
To become an approved API submitter you must first complete a small number of submissions using the standard HLA Submission Tool to a high standard. Once you have completed these submissions, please contact ipdsubs@anthonynolanorg to request approval.
Once approved you will be provided with a API pass key which is unique for each submitter. This key must be included in all API requests to authenticate the submitter.
API Documentation
Submitting via the API involes sending a POST request to the API endpoint containing all the required fields. The API will then process the request, perform validation and return a response containing the status of the submission. The API is designed to be simple and easy to use, with clear error messages and documentation to help you understand how to use it.
The API has two endpoints (see below), a submit endpoint to complete submissions and a validate endpoint to validate submission data before they are made. Validation is performed regardless of the endpoint, however we strongly recommend that you validate your submission before using the submit endpoint.
API endpoints
The API has two endpoints, one for submitting data and one for validating data. The endpoints are as follows:
| Endpoint | URL |
|---|---|
| Validate Endpoint | https://www.ebi.ac.uk/cgi-bin/ipd/py/submission/run.cgi/api/validate/ |
| Submit Endpoint | https://www.ebi.ac.uk/cgi-bin/ipd/py/submission/run.cgi/api/submit/ |
Responses:
The API will return a JSON response containing the status of the submission. The response will contain a status code, a message and any additional data. The possible responses are as follows
| JSON in body was found to be empty | |
|---|---|
| End points: | validate, submit |
| No data was submitted with the post request | |
{
"code": 400,
"errors": [
"JSON in body was found to be empty"
],
"message": "Bad Request",
"success": false,
"warnings": []
}
| |
| Validation Failed | |
| End points: | validate, submit |
| Validation of submission data failed, this can be for a variety of reasons. Informative descriptions of the errors needing to be resolved are provided in the 'errors' list, while descriptions of potential issues to consider, but will not prevent submission are included in the 'warnings' list. | |
{
'code': 422,
'success': False,
'message': "validation failed",
'errors': [
"error1",
"error2",
"..."
],
'warnings': [
"warning1",
"warning2",
"..."
]
}
| |
| Validation Successful | |
| End points: | validate |
| Validation of submission data was successful. Potential issues to consider, but will not prevent submission are included in the 'warnings' list. | |
{
'code': 200,
'success': True,
'message': "validation successfull",
'errors': [],
'warnings': [
"warning1",
"warning2",
"..."
],
'flatfile': "contents of the submission flatfile"
}
| |
| Unauthorised | |
| End points: | submit |
| The submitter ID and API key are not approved for this endpoint | |
{
'code': 401,
'success': False,
'message': "Unauthorized",
'errors': ["Invalid credentials"],
'warnings': []
}
| |
| Submission complete | |
| End points: | submit |
| The submission has successfully been made to the database | |
{
'code': 201,
'success': True,
'message': "submission completed",
'errors': [],
'warnings': [
"warning1",
"warning2",
"..."
],
'subid': "10100000"
'submitted': "01/01/2025",
'cell_info': [
{'cell_id': "cell_id1"},
{'cell_id': "cell_id2"},
{'cell_id': "..."}
],
'local_name': "Local name included in submission",
'flatfile': "contents of the submission flatfile",
'insdc_entries': [
"accession1",
"accession2",
"...",
<May be empty if no INSDC entries were included in the submission>
],
'ena_study_accession': "PRJEB00000" <May be empty if no ENA study accession was included in the submission>
}
| |
Example submission:
The API expects a JSON object containing all the required fields for a submission. For complete information on the API schema, please see the HLA Submission Schema.
{
"submission_metadata": {
"ena_study_accession": "PRJEB00000",
"broker_submission": true,
"submitter": {
"submitter_id": "10000A00",
"emails": [
"ipdsubs@anthonynolan.org"
],
"api_pass": "00000a00-00a0-00a0-00a0-00000000000a"
},
"local_name": "A*01:01:01:01CONFIRMATION",
},
"sequence_info": {
"level": "GEN",
"contiguous": true,
"sequence": "CAGGAGCAGAGGGGTCAGGGCGAAGTCCCAGGGCCCCAGGCGTGGCTCTCAGGGTCTCAGGCCCCGAAGGCGGTGTATGGATTGGGGAGTCCCAGCCTTGGGGATTCCCCAACTCCGCAGTTTCTTTTCTCCCTCTCCCAACCTACGTAGGGTCCTTCATCCTGGATACTCACGACGCGGACCCAGTTCTCACTCCCATTGGGTGTCGGGTTTCCAGAGAAGCCAATCAGTGTCGTCGCGGTCGCTGTTCTAAAGTCCGCACGCACCCACCGGGACTCAGATTCTCCCCAGACGCCGAGGATGGCCGTCATGGCGCCCCGAACCCTCCTCCTGCTACTCTCGGGGGCCCTGGCCCTGACCCAGACCTGGGCGGGTGAGTGCGGGGTCGGGAGGGAAACCGCCTCTGCGGGGAGAAGCAAGGGGCCCTCCTGGCGGGGGCGCAGGACCGGGGGAGCCGCGCCGGGAGGAGGGTCGGGCAGGTCTCAGCCACTGCTCGCCCCCAGGCTCCCACTCCATGAGGTATTTCTTCACATCCGTGTCCCGGCCCGGCCGCGGGGAGCCCCGCTTCATCGCCGTGGGCTACGTGGACGACACGCAGTTCGTGCGGTTCGACAGCGACGCCGCGAGCCAGAAGATGGAGCCGCGGGCGCCGTGGATAGAGCAGGAGGGGCCGGAGTATTGGGACCAGGAGACACGGAATATGAAGGCCCACTCACAGACTGACCGAGCGAACCTGGGGACCCTGCGCGGCTACTACAACCAGAGCGAGGACGGTGAGTGACCCCGGCCCGGGGCGCAGGTCACGACCCCTCATCCCCCACGGACGGGCCAGGTCGCCCACAGTCTCCGGGTCCGAGATCCACCCCGAAGCCGCGGGACTCCGAGACCCTTGTCCCGGGAGAGGCCCAGGCGCCTTTACCCGGTTTCATTTTCAGTTTAGGCCAAAAATCCCCCCGGGTTGGTCGGGGCGGGGCGGGGCTCGGGGGACTGGGCTGACCGCGGGGTCGGGGCCAGGTTCTCACACCATCCAGATAATGTATGGCTGCGACGTGGGGCCGGACGGGCGCTTCCTCCGCGGGTACCGGCAGGACGCCTACGACGGCAAGGATTACATCGCCCTGAACGAGGACCTGCGCTCTTGGACCGCGGCGGACATGGCAGCTCAGATCACCAAGCGCAAGTGGGAGGCGGTCCATGCGGCGGAGCAGCGGAGAGTCTACCTGGAGGGCCGGTGCGTGGACGGGCTCCGCAGATACCTGGAGAACGGGAAGGAGACGCTGCAGCGCACGGGTACCAGGGGCCACGGGGCGCCTCCCTGATCGCCTATAGATCTCCCGGGCTGGCCTCCCACAAGGAGGGGAGACAATTGGGACCAACACTAGAATATCACCCTCCCTCTGGTCCTGAGGGAGAGGAATCCTCCTGGGTTTCCAGATCCTGTACCAGAGAGTGACTCTGAGGTTCCGCCCTGCTCTCTGACACAATTAAGGGATAAAATCTCTGAAGGAGTGACGGGAAGACGATCCCTCGAATACTGATGAGTGGTTCCCTTTGACACCGGCAGCAGCCTTGGGCCCGTGACTTTTCCTCTCAGGCCTTGTTCTCTGCTTCACACTCAATGTGTGTGGGGGTCTGAGTCCAGCACTTCTGAGTCTCTCAGCCTCCACTCAGGTCAGGACCAGAAGTCGCTGTTCCCTTCTCAGGGAATAGAAGATTATCCCAGGTGCCTGTGTCCAGGCTGGTGTCTGGGTTCTGTGCTCTCTTCCCCATCCCGGGTGTCCTGTCCATTCTCAAGATGGCCACATGCGTGCTGGTGGAGTGTCCCATGACAGATGCAAAATGCCTGAATTTTCTGACTCTTCCCGTCAGACCCCCCCAAGACACATATGACCCACCACCCCATCTCTGACCATGAGGCCACCCTGAGGTGCTGGGCCCTGGGCTTCTACCCTGCGGAGATCACACTGACCTGGCAGCGGGATGGGGAGGACCAGACCCAGGACACGGAGCTCGTGGAGACCAGGCCTGCAGGGGATGGAACCTTCCAGAAGTGGGCGGCTGTGGTGGTGCCTTCTGGAGAGGAGCAGAGATACACCTGCCATGTGCAGCATGAGGGTCTGCCCAAGCCCCTCACCCTGAGATGGGGTAAGGAGGGAGATGGGGGTGTCATGTCTCTTAGGGAAAGCAGGAGCCTCTCTGGAGACCTTTAGCAGGGTCAGGGCCCCTCACCTTCCCCTCTTTTCCCAGAGCTGTCTTCCCAGCCCACCATCCCCATCGTGGGCATCATTGCTGGCCTGGTTCTCCTTGGAGCTGTGATCACTGGAGCTGTGGTCGCTGCCGTGATGTGGAGGAGGAAGAGCTCAGGTGGAGAAGGGGTGAAGGGTGGGGTCTGAGATTTCTTGTCTCACTGAGGGTTCCAAGCCCCAGCTAGAAATGTGCCCTGTCTCATTACTGGGAAGCACCTTCCACAATCATGGGCCGACCCAGCCTGGGCCCTGTGTGCCAGCACTTACTCTTTTGTAAAGCACCTGTTAAAATGAAGGACAGATTTATCACCTTGATTACGGCGGTGATGGGACCTGATCCCAGCAGTCACAAGTCACAGGGGAAGGTCCCTGAGGACAGACCTCAGGAGGGCTATTGGTCCAGGACCCACACCTGCTTTCTTCATGTTTCCTGATCCCGCCCTGGGTCTGCAGTCACACATTTCTGGAAACTTCTCTGGGGTCCAAGACTAGGAGGTTCCTCTAGGACCTTAAGGCCCTGGCTCCTTTCTGGTATCTCACAGGACATTTTCTTCCCACAGATAGAAAAGGAGGGAGTTACACTCAGGCTGCAAGTAAGTATGAAGGAGGCTGATGCCTGAGGTCCTTGGGATATTGTGTTTGGGAGCCCATGGGGGAGCTCACCCACCCCACAATTCCTCCTCTAGCCACATCTTCTGTGGGATCTGACCAGGTTCTGTTTTTGTTCTACCCCAGGCAGTGACAGTGCCCAGGGCTCTGATGTGTCTCTCACAGCTTGTAAAGGTGAGAGCTTGGAGGGCCTGATGTGTGTTGGGTGTTGGGTGGAACAGTGGACACAGCTGTGCTATGGGGTTTCTTTGCGTTGGATGTATTGAGCATGCGATGGGCTGTTTAAGGTGTGACCCCTCACTGTGATGGATATGAATTTGTTCATGAATATTTTTTTCTATAGTGTGAGACAGCTGCCTTGTGTGGGACTGAGAGGCAAGAGTTGTTCCTGCCCTTCCCTTTGTGACTTGAAGAACCCTGACTTTGTTTCTGCAAAGGCACCTGCATGTGTCTGTGTTCGTGTAGGCATAATGTGAGGAGGTGGGGAGAGCACCCCACCCCCATGTCCACCATGACCCTCTTCCCACGCTGACCTGTGCTCCCTCTCCAATCATCTTTCCTGTTCCAGAGAGGTGGGGCTGAGGTGTCTCCATCTCTGTCTCAACTTCATGGTGCACTGAGCTGTAACTTCTTCCTTCCCTATTAAAA",
"locus": "A",
"comparative_allele": "A*01:01:01:01",
"description": "Confirmation of A*01:01:01:01",
"sequence_coordinates": {
"cds_coords": [
{'start': 1, 'length': 73},
{'start': 74, 'length': 270},
{'start': 344, 'length': 276},
{'start': 620, 'length': 276},
{'start': 896, 'length': 117},
{'start': 1013, 'length': 33},
{'start': 1046, 'length': 48},
{'start': 1094, 'length': 5}
],
"feature_coords": [
{"length": 300, "number": "5", "start": 1, "type": "utr" },
{"length": 73, "number": "1", "start": 301, "type": "exon"},
{"length": 130, "number": "1", "start": 374, "type": "intron"},
{"length": 270, "number": "2", "start": 504, "type": "exon"},
{"length": 241, "number": "2", "start": 774, "type": "intron"},
{"length": 276, "number": "3", "start": 1015, "type": "exon"},
{"length": 579, "number": "3", "start": 1291, "type": "intron"},
{"length": 276, "number": "4", "start": 1870, "type": "exon"},
{"length": 102, "number": "4", "start": 2146, "type": "intron"},
{"length": 117, "number": "5", "start": 2248, "type": "exon"},
{"length": 442, "number": "5", "start": 2365, "type": "intron"},
{"length": 33, "number": "6", "start": 2807, "type": "exon"},
{"length": 142, "number": "6", "start": 2840, "type": "intron"},
{"length": 48, "number": "7", "start": 2982, "type": "exon"},
{"length": 169, "number": "7", "start": 3030, "type": "intron"},
{"length": 5, "number": "8", "start": 3199, "type": "exon"},
{"length": 300, "number": "3", "start": 3204, "type": "utr"}
]
},
"cell_info": {
"cells": [
{
"cell_id": "APD",
"ancestry": {
"broad": "European",
"region": "Western Europe",
"country": "Netherlands",
"local_designation": null
},
"sex": "Unknown",
"consanguineous": "Yes",
"homozygous": "Yes",
"lab_of_origin": "Anthony Nolan Research Institute",
"lab_contact": "IPD-IMGT/HLA Database Team",
"material_available": "Cell Line - B Lymphoblastoid Cell Line",
"cell_bank": "ECACC",
"ihw": true,
"hla_typing": [
{"locus": "A", "typing": "01:01:01:01SUBMITTED", "described": true},
{"locus": "B", "typing": "40:01:02:01", "described": false},
{"locus": "C", "typing": "06:02:01:01", "described": false},
{"locus": "E", "typing": "01:01:01:01", "described": false},
{"locus": "F", "typing": "01:01:03:01", "described": false},
{"locus": "G", "typing": "01:06:01:01", "described": false},
{"locus": "DRA", "typing": "01:01:01:07", "described": false},
{"locus": "DRB1", "typing": "13:01:01:02", "described": false},
{"locus": "DRB3", "typing": "02:02:01:02", "described": false},
{"locus": "DQA1", "typing": "01:03:01:02", "described": false},
{"locus": "DQB1", "typing": "06:03:01:01", "described": false},
{"locus": "DPA1", "typing": "01:03:01:05", "described": false},
{"locus": "DPB1", "typing": "04:02:01:01", "described": false}
],
"hla_serology": [
{"locus": "A", "serology": "1"},
{"locus": "B", "serology": "60"},
{"locus": "DR", "serology": "13"},
{"locus": "DR52", "serology": "52"},
{"locus": "DP", "serology": "4"},
{"locus": "DQ", "serology": "1"}
]
}
]
},
"methodology_info": {
"sequencing_methods": [
{
"method": "NGS Long Read (PacBio)",
"target_enrichment": "PCR (Allele specific)",
"minimum_requirements": True
}
],
"confirmation_methods": []
}
}
}