Layer 1
GenXys API Specification v1.2.5

/api/app/AccessToken

POST /api/app/AccessToken


Description

Retrieve a client access token.


Request URL

https://us.portal.genxys.com/api/app/AccessToken

https://cdn.portal.genxys.com/api/app/AccessToken


Request headers


N/A




Request body


username

string

client user

password

string

client secret

 


                                    
    const body = new URLSearchParams({
        username: "[USERNAME]",
    	password: "[PASSWORD]"
    });

    fetch("https://us.portal.genxys.com/api/app/AccessToken", {
    		method: 'POST',
    		headers: {
    			"Content-Type": "application/x-www-form-urlencoded"
    		},
    		body: body
    	})
    	.then(response => response.text())
    	.then(result => console.log(result))
    	.catch(error => console.log('error', error));

Response


status code

http response code

200

success

body

application/json

Value access_token: OAuth 2.0 access token. 



                                    
    {
         "contentType" :  null ,
         "serializerSettings" :  null ,
         "statusCode" :  200 ,
         "value" : {
             "token_type" :  "Bearer" ,
             "expires_in" :  3599 ,
             "ext_expires_in" :  3599 ,
             "access_token" :  "eyJ0eXAiOiJKV1QiLCJhb…._Ur3_cm6A1MFQJ3cK9juuMYbuH5Q"
        }

    }



/api/ExternalLab/UploadLabOrder

PUT /api/ExternalLab/UploadLabOrder


Description

Upload lab orders. Upon upload, the order status transitions to "Awaiting QA Signoff."


Request URL

https://apim-us.azure-api.net/genxys-portal/api/ExternalLab/UploadLabOrder

https://apim-cdn.azure-api.net/genxys-portal/api/ExternalLab/UploadLabOrder


Request headers


authorization

Bearer Token

Bearer <token>
 

Authenticate using a bearer token, which can be obtained through OAuth 2.0 from the listed URLs.

https://us.portal.genxys.com/api/app/AccessToken

https://cdn.portal.genxys.com/api/app/AccessToken


Request body


orders

array

An array of lab orders. For order structure details, see: GenXys Lab Order Specification


instrumentFiles

base64 encoded

To upload lab results for the orders, set CNV and OA, or SNP and STR, or URL, or VCF. To import orders without lab results leave these values blank. 




                                    
    const raw = JSON.stringify({
        "orders": [{
            "resourceType": "patient",
            "orderedBy": "providertest",
            "clinicIdentifier": "DemoLab",
            "clinicType": "DemoLab-LAB",
            "clinicInstance": "",
            "barcode": "BC 1_B",
            "panel": "",
            "payload": {
                "identifier": "PGx 1_B",
                "firstName": "Test",
                "lastName": "One",
                "demographics": {
                    "dob": "1999-01-01",
                    "sexAtBirth": "F",
                    "email": "Test.One@genxys.com",
                    "address": {
                        "addressLine1": "100 Main Street",
                        "addressLine2": "Unit 300",
                        "city": "Anytown",
                        "region": "California",
                        "postalCode": "90210",
                        "country": "US"
                    }                   
                },
                "specimen": {
                    "sampleId": "1_B",
                    "type": "Swab",
                    "date": "2022-06-08",
                    "received": "2022-06-06"
                },
                "notes": "this is a sample note.",
                "medicalSummary": {
                    "currentMedications": [{
                            "name": "ACH-ATORVASTATIN 40 MG TABLET",
                            "dosage": "1 Tablet, QD",
                            "coding": {
                                "system": "DIN",
                                "code": "2457776"
                            },
                            "indication": {
                                "name": "Attention Deficit Hyperactivity Disorder",
                                "coding": {
                                    "system": "ICD9",
                                    "code": "314.01"
                                }
                            }
                        },
                        {
                            "name": "ACT CLOPIDOGREL 75 MG TABLET",
                            "dosage": "1 puff, Q12H",
                            "coding": {
                                "system": "DIN",
                                "code": "2303027"
                            },
                            "indication": {
                                "name": "Diabetes Mellitus Type 2",
                                "coding": {
                                    "system": "ICD9",
                                    "code": "250.00"
                                }
                            }
                        }
                    ]
                }
                
            }
        }],
        "instrumentFiles": {
            "CNV": "QW5hFD...oKCgo=",
            "OA": "IyBFeH...AwCgo=",
            "ULR": "",
            "SNP": "",
            "STR": "",
            "VCF"" ""
        }
    });

    fetch("https://apim-us.azure-api.net/genxys-portal/api/ExternalLab/UploadLabOrder", {
    		method: 'PUT',
    		headers: {
    			"Content-Type": "application/json",
    			"authorization": "Bearer eyJ0e...www"
    		},
    		body: raw
    	})
    	.then(response => response.text())
    	.then(result => console.log(result))
    	.catch(error => console.log('error', error));

Response


status code

http response code

200

success

body

application/json

Value The response conveys metrics on successful, failed, or invalid uploads. For specific order details, refer to the ErrorMgs attribute. 



                                    
    {
         "contentType" :  null ,
         "serializerSettings" :  null ,
         "statusCode" :  200 ,
         "value" : {
             "validCount" :  0 ,
             "invalidCount" :  0 ,
             "errorCount" :  0 ,
             "totalCount" :  0 ,
             "errorMsgs" :  ["Order: ABC-123 - The order is not valid. The order is missing a 'payload' section."]
        }
    }



/api/ExternalLab/DownloadReports

POST /api/ExternalLab/DownloadReports


Description

Retrieve available PGX Report(s).


Request URL

https://apim-us.azure-api.net/genxys-portal/api/ExternalLab/DownloadReports

https://apim-cdn.azure-api.net/genxys-portal/api/ExternalLab/DownloadReports


Request headers


authorization

Bearer Token

Bearer <token>
 

Authenticate using a bearer token, which can be obtained through OAuth 2.0 from the listed URLs.

https://us.portal.genxys.com/api/app/AccessToken

https://cdn.portal.genxys.com/api/app/AccessToken


Request body


identifier

string

A string value representing either a webhook ID or a barcode.

reportTypes (optional)



string array

Indicates the desired report types (options: Long, StyledEnglish, Short, Raw, Status and/or ULR).

Omitting this field, entering an empty array, or using 'null' will all return all reports by default. 




                                    
    const raw = JSON.stringify({
    	"identifier": "wehbook_id_or_barcode",
    	"reportTypes": ["Long", "Status"]
    });

    fetch("https://apim-us.azure-api.net/genxys-portal/api/ExternalLab/DownloadReports", {
    		method: 'POST',
    		headers: {
    			"Content-Type": "application/json",
    			"authorization": "Bearer eyJ0e...www"
    		},
    		body: raw
    	})
    	.then(response => response.text())
    	.then(result => console.log(result))
    	.catch(error => console.log('error', error));

Response


status code

http response code

200

success

body

application/json

Value labReports: A base64-encoded array of generated report(s).

reportStatus: Indicates the report's current status (Pending, AwaitingQASignoff, AwaitingLDSignoff, Completed). 



                                    
    {
        "contentType": null,
        "serializerSettings": null,
        "statusCode": 200,
        "value": {
            "errorMessages": [],
            "hasError": false,
            "identifier": "2327100168",
            "labReports": [
                {
                    "pdf": "JVBAAERi0xLjQNCiW0tba3DQoADfadasfasDfasd",
                    "reportName": "Long-FirstName-LastName.pdf",
                    "reportType": "Long"
                },
                {
                    "pdf": "JVBYYi0xLjQNCiW0tba3DQoWWAASSAsssssss",
                    "reportName": "Short-FR-FirstName-LastName.pdf",
                    "reportType": "StyledFrench"
                },
                {
                    "pdf": "JVBMMi0xLjQNCiW0tbsdasdDDDklfEEAAa",
                    "reportName": "Short-EN-FirstName-LastName.pdf",
                    "reportType": "StyledEnglish"
                },
                {
                    "pdf": "JVBXXi0xLjQNCiW0tbaasdljsdaRRR",
                    "reportName": "FAX-FirstName-LastName.pdf",
                    "reportType": "Short"
                },
                {
                    "pdf": "JVBXXi0xLjQNCiW0tbaasdljsdaRRR",
                    "reportName": "Raw-FirstName-LastName.pdf",
                    "reportType": "Raw"
                },
                {
                    "pdf": "JVBPPi0xLjQNCiW0tEdr5gyh",
                    "reportName": "Status-FirstName-LastName.pdf",
                    "reportType": "Status"
                }
            ],
            "reportStatus": "Completed"
        }
    }



/api/ExternalLab/DownloadCdssReports

POST /api/ExternalLab/DownloadCdssReports


Description

Retrieve available TreatGx and/or ReviewGx CDSS report PDFs for up to 25 patient identifiers. Identifiers must correspond to lab orders submitted by the requesting lab. Maximum of 25 identifiers per request. Only identifiers for patients whose lab orders were originally submitted by the requesting lab are accessible.


Request URL

https://apim-us.azure-api.net/genxys-portal/api/ExternalLab/DownloadCdssReports

https://apim-cdn.azure-api.net/genxys-portal/api/ExternalLab/DownloadCdssReports


Request headers


authorization

Bearer Token

Bearer <token>
 

Authenticate using a bearer token, which can be obtained through OAuth 2.0 from the listed URLs.

https://us.portal.genxys.com/api/app/AccessToken

https://cdn.portal.genxys.com/api/app/AccessToken


Request body


identifiers

string array

An array of strings, each representing either a webhook ID or a barcode. Only identifiers belonging to patients whose lab orders were originally submitted by the requesting lab are valid. Maximum 25 per request.

reportTypes (optional)



string array

Indicates the desired CDSS report types (options: TreatGx and/or ReviewGx).

Omitting this field, entering an empty array, or using null will return both TreatGx and ReviewGx reports by default. 




                                    
    const raw = JSON.stringify({
    	"identifiers": ["webhook_id_or_barcode"],
    	"reportTypes": ["TreatGx", "ReviewGx"]
    });

    fetch("https://apim-us.azure-api.net/genxys-portal/api/ExternalLab/DownloadCdssReports", {
    		method: 'POST',
    		headers: {
    			"Content-Type": "application/json",
    			"authorization": "Bearer eyJ0e...www"
    		},
    		body: raw
    	})
    	.then(response => response.text())
    	.then(result => console.log(result))
    	.catch(error => console.log('error', error));

Response


status code

http response code

200

success

body

application/json

Value reports: An array of report items per identifier, each containing a base64-encoded PDF, report type, and modification date.

reportIsRestoring: Indicates the PDF is being retrieved from cold storage. Retry the request after a short delay. 



                                    
    {
        "contentType": null,
        "serializerSettings": null,
        "statusCode": 200,
        "value": {
            "errorMessages": [],
            "hasError": false,
            "reports": [
                {
                    "identifier": "2327100168",
                    "reportType": "TreatGx",
                    "report": "JVBAAERi0xLjQNCiW0tba3DQoADfadasfasDfasd",
                    "modified": "2024-01-15T10:30:00Z",
                    "hasError": false,
                    "errorMessages": [],
                    "reportIsRestoring": false,
                    "reportRestoreDetail": null,
                    "reportRestoreMessage": null
                },
                {
                    "identifier": "2327100168",
                    "reportType": "ReviewGx",
                    "report": "JVBYYi0xLjQNCiW0tba3DQoWWAASSAsssssss",
                    "modified": "2024-01-15T10:30:00Z",
                    "hasError": false,
                    "errorMessages": [],
                    "reportIsRestoring": false,
                    "reportRestoreDetail": null,
                    "reportRestoreMessage": null
                }
            ]
        }
    }



/api/ExternalLab/QaSignoff

PUT /api/ExternalLab/QaSignoff


Description

Update the report status to 'AwaitingLDSignoff'.


Request URL

https://apim-us.azure-api.net/genxys-portal/api/ExternalLab/QaSignoff

https://apim-cdn.azure-api.net/genxys-portal/api/ExternalLab/QaSignoff


Request headers


authorization

Bearer Token

Bearer <token>
 

Authenticate using a bearer token, which can be obtained through OAuth 2.0 from the listed URLs.

https://us.portal.genxys.com/api/app/AccessToken

https://cdn.portal.genxys.com/api/app/AccessToken


Request body


identifier

string

A string, representing either a webhook ID or a barcode.

 



                                    
    const raw = JSON.stringify({
        "identifier": "wehbook_id_or_barcode"
    });

    fetch("https://apim-us.azure-api.net/genxys-portal/api/ExternalLab/QaSignoff", {
            method: 'PUT',
            headers: {
                "Content-Type": "application/json",
                "authorization": "Bearer eyJ0e...www"
            },
            body: raw
        })
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));

Response


status code

http response code

200

success

body

application/json

Value A boolean value indicating the success (true) or failure (false) of the operation. 



                                    
    {
        "contentType": null,
        "serializerSettings": null,
        "statusCode": 200,
        "value": {
            "errorMessages": [],
            "success": true
        }
    }



/api/ExternalLab/LdSignoff

PUT /api/ExternalLab/LdSignoff


Description

Update the report status to 'Completed'.


Request URL

https://apim-us.azure-api.net/genxys-portal/api/ExternalLab/LdSignoff

https://apim-cdn.azure-api.net/genxys-portal/api/ExternalLab/LdSignoff


Request headers


authorization

Bearer Token

Bearer <token>
 

Authenticate using a bearer token, which can be obtained through OAuth 2.0 from the listed URLs.

https://us.portal.genxys.com/api/app/AccessToken

https://cdn.portal.genxys.com/api/app/AccessToken


Request body


identifier

string

A string, representing either a webhook ID or a barcode.

 



                                    
    const raw = JSON.stringify({
    	"identifier": "wehbook_id_or_barcode"
    });

    fetch("https://apim-us.azure-api.net/genxys-portal/api/ExternalLab/LdSignoff", {
    		method: 'PUT',
    		headers: {
    			"Content-Type": "application/json",
    			"authorization": "Bearer eyJ0e...www"
    		},
    		body: raw
    	})
    	.then(response => response.text())
    	.then(result => console.log(result))
    	.catch(error => console.log('error', error));

Response


status code

http response code

200

success

body

application/json

Value A boolean value indicating the success (true) or failure (false) of the operation. 



                                    
    {
        "contentType": null,
        "serializerSettings": null,
        "statusCode": 200,
        "value": {
            "errorMessages": [],
            "success": true
        }
    }



/api/ExternalLab/LabOrderDetails

POST /api/ExternalLab/LabOrderDetails


Description

Retrieve the labOrder.json and details for the given identifier.


Request URL

https://apim-us.azure-api.net/genxys-portal/api/ExternalLab/LabOrderDetails

https://apim-cdn.azure-api.net/genxys-portal/api/ExternalLab/LabOrderDetails


Request headers


authorization

Bearer Token

Bearer <token>
 

Authenticate using a bearer token, which can be obtained through OAuth 2.0 from the listed URLs.

https://us.portal.genxys.com/api/app/AccessToken

https://cdn.portal.genxys.com/api/app/AccessToken


Request body


identifier

string

A string, representing either a webhook ID or a barcode.

 



                                    
    const raw = JSON.stringify({
    	"identifier": "wehbook_id_or_barcode"
    });

    fetch("https://apim-us.azure-api.net/genxys-portal/api/ExternalLab/LabOrderDetails", {
    		method: 'PUT',
    		headers: {
    			"Content-Type": "application/json",
    			"authorization": "Bearer eyJ0e...www"
    		},
    		body: raw
    	})
    	.then(response => response.text())
    	.then(result => console.log(result))
    	.catch(error => console.log('error', error));

Response


status code

http response code

200

success

body

application/json

Value Details associated with the order such as patient name, barcode, labOrder.json and report status. 



                                    
    {
        "contentType": null,
        "serializerSettings": null,
        "statusCode": 200,
        "value": {
            "barcodes": [
                "BC888-888-888"
            ],
            "dob": "1946-09-23",
            "errorMessages": [],
            "patientFirstName": "FirstName",
            "patientLastName": "LastName",
            "labOrder": {
                "resourceType": "patient",
                "orderedBy": "provider name",
                "clinicIdentifier": "GenXys",
                "clinicType": "GenXys-LAB",
                "clinicInstance": "",
                "barcode": "BC 1_C",
                "panel": null,
                "payload": {
                    "identifier": "ABC123Feb13",
                    "firstName": "Test",
                    "lastName": "One",
                    "demographics": {
                        "dob": "1999-01-01",
                        "sexAtBirth": "F",
                        "email": "Test.One@genxys.com",
                        "address": {
                            "addressLine1": "100 Main Street",
                            "addressLine2": "Unit 300",
                            "city": "Anytown",
                            "region": "California",
                            "postalCode": "90210",
                            "country": "US"
                        }
                    },
                    "specimen": {
                        "sampleId": "1_B",
                        "type": "Swab",
                        "date": "2022-06-08",
                        "received": "2022-06-06"
                    },
                    "notes": "this is a sample note.",
                    "medicalSummary": {
                        "currentMedications": [{
                                "name": "ACH-ATORVASTATIN 40 MG TABLET",
                                "dosage": "1 Tablet, QD",
                                "coding": {
                                    "system": "DIN",
                                    "code": "2457776"
                                },
                                "indication": {
                                    "name": "Attention Deficit Hyperactivity Disorder",
                                    "coding": {
                                        "system": "ICD9",
                                        "code": "314.01"
                                    }
                                }
                            },
                            {
                                "name": "ACT CLOPIDOGREL 75 MG TABLET",
                                "dosage": "1 puff, Q12H",
                                "coding": {
                                    "system": "DIN",
                                    "code": "2303027"
                                },
                                "indication": {
                                    "name": "Diabetes Mellitus Type 2",
                                    "coding": {
                                        "system": "ICD9",
                                        "code": "250.00"
                                    }
                                }
                            }
                        ]
                    }
                }
            }
            "reportStatus": "Completed",
            "success": true
        }
    }



/api/ExternalLab/UploadMedications

PUT /api/ExternalLab/UploadMedications


Description

This endpoint allows for the uploading of patient medications for review.


Request URL

https://apim-us.azure-api.net/genxys-portal/api/ExternalLab/UploadMedications

https://apim-cdn.azure-api.net/genxys-portal/api/ExternalLab/UploadMedications


Request headers


authorization

Bearer Token

Bearer <token>
 

Authenticate using a bearer token, which can be obtained through OAuth 2.0 from the listed URLs.

https://us.portal.genxys.com/api/app/AccessToken

https://cdn.portal.genxys.com/api/app/AccessToken


Request body


orders

array

An array of lab orders. For order structure details, see: GenXys Lab Order Specification 



                                    
    const raw = JSON.stringify({
        "Orders": [{
            "resourceType": "patient",
            "orderedBy": "provider name",
            "clinicIdentifier": "GenXys",
            "clinicType": "GenXys-LAB",
            "clinicInstance": "",
            "barcode": "BC 1_C",
            "panel": "",
            "payload": {
                "identifier": "ABC123Feb13",
    		"firstName": "Test",
    		"lastName": "One",
                "demographics": {
                    "dob": "1999-01-01",
                    "sexAtBirth": "F",
                    "email": "Test.One@genxys.com",
                    "address": {
                        "addressLine1": "100 Main Street",
                        "addressLine2": "Unit 300",
                        "city": "Anytown",
                        "region": "California",
                        "postalCode": "90210",
                        "country": "US"
                    }
                },
                "specimen": {
                    "sampleId": "1_B",
                    "type": "Swab",
                    "date": "2022-06-08",
                    "received": "2022-06-06"
                },
                "notes": "this is a sample note.",
                "medicalSummary": {
                    "currentMedications": [{
                            "name": "ACH-ATORVASTATIN 40 MG TABLET",
                            "dosage": "1 Tablet, QD",
                            "coding": {
                                "system": "DIN",
                                "code": "2457776"
                            },
                            "indication": {
                                "name": "Attention Deficit Hyperactivity Disorder",
                                "coding": {
                                    "system": "ICD9",
                                    "code": "314.01"
                                }
                            }
                        },
                        {
                            "name": "ACT CLOPIDOGREL 75 MG TABLET",
                            "dosage": "1 puff, Q12H",
                            "coding": {
                                "system": "DIN",
                                "code": "2303027"
                            },
                            "indication": {
                                "name": "Diabetes Mellitus Type 2",
                                "coding": {
                                    "system": "ICD9",
                                    "code": "250.00"
                                }
                            }
                        }
                    ]
                }
            }
        }]
    });

    fetch("https://apim-us.azure-api.net/genxys-portal/api/ExternalLab/UploadMedications", {
    		method: 'PUT',
    		headers: {
    			"Content-Type": "application/json",
    			"authorization": "Bearer eyJ0eXA...vM4A"
    		},
    		body: raw
    	})
    	.then(response => response.text())
    	.then(result => console.log(result))
    	.catch(error => console.log('error', error));

Response


status code

http response code

200

success

body

application/json

Value The response conveys metrics on successful, failed, or invalid uploads. For specific order details, refer to the ErrorMgs attribute. 



                                    
    {

         "contentType" :  null ,
         "serializerSettings" :  null ,
         "statusCode" :  200 ,
         "value" : {
             "validCount" :  0 ,
             "invalidCount" :  0 ,
             "errorCount" :  0 ,
             "totalCount" :  0 ,
             "errorMsgs" :  ["Order: ABC-123 - The order is not valid. The order is missing a 'payload' section."]
        }
    }