Service call specifications

The following web services calls have been implemented in The Ark.

  1. Get all subjects of a study
  2. Get single subject from a study
  3. Update subject within a study
  4. Add subject to study
  5. Get all twins from a study
  6. Delete twin relationship
  7. Add twin relationship
  8. Get all subjects who have siblings
  9. Get all siblings of a subject
  10. Get all parental relationships
  11. Delete parental relationship
  12. Add parental relationship
  13. Get BloodLine of a subject
  14. Visualise pedigree of proband
  15. Get pedigree configuration
  16. Update pedigree configuration
  17. Get yes/no subject custom fields
  18. Get visualisation of a pedigree sent

Authentication is performed with respect to The Ark's user accounts and their role-based access permissions. For a web service call to succeed, the authenticated user must have adequate access permissions to perform the task. See The Ark user documentation for more information.

Get all subjects of a study

Retrieve core data (subject UID, first and last name, etc.) for all members of a study.

 URL /study/{studyID}/subject
 Method GET
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137
 Authentication Basic Authentication
 Success Response

Status: 200

Content:

subjects: [
    {
        subjectUID: "A000231",
        genderTypeName: "Male",
        firstName: "Mark",
        lastName: "Cruise",
        subjectStatusName: "Subject",
        consentStatusName: "Consented",
        vitalStatusName: "Alive",
        dateOfBirth: "2016-06-05"
    },
    {...},
    {...}
]
 Error Response

Code: 401 UNAUTHORIZED

Content:{error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}

OR

Code: 404 NOT FOUND

Content:{error:"Subject not specified."}
 Example Call
$.ajax({
    url: "https://examplehost.com/study/137/subject",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa(username + ":" + password)
    },
    success : function(r) {
        console.log(r);
    }
});

 Back to top

 Get single subject from a study

Retrieve core data (subject UID, first and last name, etc.) for a single member of a study.

 URL /study/{studyID}/subject/{subjectUID}
 Method GET
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137

subjectUID as [String], e.g. subjectUID = "A000231"
 Authentication Basic Authentication
 Success Response

Example:

Status: 200

subject: {
    subjectUID: "A000231",
    genderTypeName: "Male",
    firstName: "Mark",
    lastName: "Cruise",
    subjectStatusName: "Subject",
    consentStatusName: "Consented",
    vitalStatusName: "Alive",
    dateOfBirth: "2016-06-05"
} 
 Error Response

Example:

Code: 401 UNAUTHORIZED

Content:{error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}

OR

Code: 404 NOT FOUND

Content:{error:”A subject with this UID does not exist."}
 Example Call
$.ajax({
    url: "https://examplehost.com/study/137/subject/A000231",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa(username + ":" + password)
    },
    success : function(r) {
        console.log(r);
    }
});

 Back to top

Update subject within a study

Update core data (subject UID, first and last name, etc.) for a single member of a study.

 URL /study/{studyID}/subject/{subjectID}
 Method POST
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137

subjectID as [number], e.g. subjectID = 1056
Data Parameters
{
    subject: {
        subjectUID: [string],
        genderTypeName: [string],
        firstName: [string],
        lastName: [string],
        subjectStatusName: [string],
        consentStatusName: [string],
        vitalStatusName: [string],
        dateOfBirth: [string]
    }
}

Valid selections:

subjectStatusName: ["Subject", "Prospect", "Withdrawn Subject", "Archive", "Inactive"]
genderTypeName: ["Male", "Female", "Unknown"]
vitalStatusName: ["Alive", "Deceased", "Unknown"]
consentStatusName: ["Consented", "Not Consented", "Ineligible Refused", "Withdrawn", "Pending"]

Example:

{
    subject: {
        subjectUID: "A000231",
        genderTypeName: "Male",
        firstName: "Mark",
        lastName: "Cruise",
        subjectStatusName: "Subject",
        consentStatusName: "Consented",
        vitalStatusName: "Alive",
        dateOfBirth: "2016-06-05"
    }
}
Authentication Basic Authentication
 Success Response

Example:

Status: 200

Message: "Subject updated successfully"
 Error Response

Code: 401 UNAUTHORIZED

Content:{error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}

OR

Code: 404 NOT FOUND

Content:{error:"A subject with this UID does not exist."}

OR

Code: 409 CONFLICT

Content:{error:"The given Subject UID and Subject ID do not match."}

OR

Code: 404 NOT FOUND

Content:{error:"Gender not specified."}

OR

Code: 404 NOT FOUND

Content:{error:""Gender must be “male“ or “female“."}

OR

Code: 404 NOT FOUND

Content:{error:"Vital Status not specified."}

OR

Code: 404 NOT FOUND

Content:{error:"Vital Status must be “Alive”, “Deceased”, or “Unknown”."}

OR

Code: 404 NOT FOUND

Content:{error:"Subject Status not specified."}

OR

Code: 404 NOT FOUND

Content:{error:"Subject Status must be “Subject”, “Prospect”, “Withdrawn Subject”, “Archive”, or “Inactive”."}
 Example Call
$.ajax({
     url: "https://examplehost.com/study/137/subject/1056",
     dataType: "json",
     headers: {
         "Authorization": "Basic " + btoa(username + ":" + password)
    },
    data: {subjectUID: "A000231",
           genderTypeName: "Male",
           firstName: "Mark",
           lastName: "Cruise",
           subjectStatusName: "Subject",
           consentStatusName: "Consented",
           vitalStatusName: "Alive",
           dateOfBirth: "2016-06-05"
     },
     type: "POST",
     success: function (res) {}
});

 Back to top

Add subject to study

Add a subject to a study.

 URL /study/{studyID}/subject
 Method PUT
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137
Data Parameters
{
    subject: {
        subjectUID: [string],
        genderTypeName: [string],
        firstName: [string],
        lastName: [string],
        subjectStatusName: [string],
        consentStatusName: [string],
        vitalStatusName: [string],
        dateOfBirth: [string]
   }
}

Valid selections:

subjectStatusName: ["Subject", "Prospect", "Withdrawn Subject", "Archive", "Inactive"]
genderTypeName: ["Male", "Female", "Unknown"]
vitalStatusName: ["Alive", "Deceased", "Unknown"]
consentStatusName: ["Consented", "Not Consented", "Ineligible Refused", "Withdrawn", "Pending"]

Example:

{
    subject: {
        subjectUID: "A000232",
        genderTypeName: "Male",
        firstName: "John",
        lastName: "Smith",
        subjectStatusName: "Subject",
        consentStatusName: "Consented",
        vitalStatusName: "Alive",
        dateOfBirth: "2016-06-05"
    }
}
Authentication Basic Authentication
 Success Response

Example:

Status: 200

Message: "Subject created successfully"
 Error Response

Code: 401 UNAUTHORIZED

Content: {error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}

OR

Code: 409 CONFLICT

Content:{error:"A subject with this UID already exists."}

OR

Code: 404 NOT FOUND

Content:{error:"Gender not specified."}

OR

Code: 404 NOT FOUND

Content:{error:"Gender must be “male“ or “female“."}

OR

Code: 404 NOT FOUND

Content:{error:"Vital Status not specified."}

OR

Code: 404 NOT FOUND

Content:{error:"Vital Status must be “Alive”, “Deceased”, or “Unknown”."}

OR

Code: 404 NOT FOUND

Content:{error:"Subject Status not specified."}

OR

Code: 404 NOT FOUND

Content:{error:"Subject Status must be "Subject", "Prospect", "Withdrawn Subject", "Archive", or "Inactive"."}
 Example Call
$.ajax({
     url: "https://examplehost.com/study/137/subject",
     dataType: "json",
     headers: {
         "Authorization": "Basic " + btoa(username + ":" + password)
     },
     data: {
         subjectUID: "A000232",
         genderTypeName: "Male",
         firstName: "John",
         lastName: "Smith",
         subjectStatusName: "Subject",
         consentStatusName: "Consented",
         vitalStatusName: "Alive",
         dateOfBirth: "2016-06-05"
     },
     type: "PUT",
     success: function (res) {}
});

 Back to top

Get all twins from a study

Retrieve a list of all twins in a study.

 URL /study/{studyID}/twintype 
 Method GET
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137 
 Authentication Basic Authentication
 Success Response

Example:

Status: 200

Content:

twins: [
    {
        id: 123,
        subjectUID: "A000231",
        relativeUID: "A000233",
        twinType: "MZ"
    },
    {...},
    {...}
]
 Error Response

Code: 401 UNAUTHORIZED

Content: {error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}

OR

Code: 404 NOT FOUND

Content:{error:"No twin relationship exists."}
 Example Call
$.ajax({
    url: "https://examplehost.com/study/137/twintype",
    dataType: "json",
    type: "GET",
    success : function(r) {
        console.log(r);
    }
});

 Back to top

Delete twin relationship

Delete a specific twin relationship within a study.

 URL /study/{studyID}/twintype/{relationshipID}
 Method DELETE
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137

relationshipID as [String], e.g. relationshipID = 123
 Authentication Basic Authentication
 Success Response

Example:

Status: 200
 Error Response

Code: 401 UNAUTHORIZED

Content:{error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid twin relationship."} 
 Example Call
$.ajax({
    url: "https://examplehost.com/study/137/twintype/123",
    dataType: "json",
    type: "DELETE",
    headers: {
        "Authorization": "Basic " + btoa(username + ":" + password)
    },
    success : function(r) {
        console.log(r);
    }
});

 Back to top

Add twin relationship

Add a twin relationship between members of a study.

 URL /study/{studyID}/twintype
 Method PUT
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137
Data Parameters
{
    twin: {
        subjectUID: [string],
        relativeUID: [string],
        twinType: [string]
    }
}

Valid selections:

twinType: ["MZ", "DZ"]

Example:

{
    twin: {
        subjectUID: "A000231",
        relativeUID: "A000233",
        twinType: "MZ"
    }
}
Authentication Basic Authentication
 Success Response

Example:

Status: 200

Message: "Twin relationship created successfully"
 Error Response

Code: 401 UNAUTHORIZED

Content:{error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}

OR

Code: 404 NOT FOUND

Content:{error:"A subject with this UID does not exist."}

OR

Code: 404 NOT FOUND

Content:{error:"A relative with this subject UID does not exist."}

OR

Code: 403 FORBIDDEN

Content:{error:"Cannot create a relationship for a subject with this Subject Status."}

OR

Code: 403 FORBIDDEN

Content:{error:"Cannot create a relationship for a relative with this Subject Status."}

OR

Code: 404 NOT FOUND

Content:{error:"Twin Type must be "MZ" or "DZ"."}

OR

Code: 404 NOT FOUND

Content:{error:"Twin Type not specified."}

OR

Code: 409 CONFLICT

Content:{error:"Twin relationship indicated for a subject that is not a sibling."}
 Example Call
$.ajax({
    url: "https://examplehost.com/study/137/twintype",
    dataType: "json",
    headers: {
        "Authorization": "Basic " + btoa(username + ":" + password)
    },
    data: {
        subjectUID: "A000231",
        relativeUID: "A000233",
        twinType: "MZ"
    },
    type: "PUT",
    success: function (res) {}
});

 Back to top

 Get all subjects who have siblings

Retrieve a list of subjects who each have one or more siblings.

 URL /study/{studyID}/commonparentsubjects
 Method GET
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137
 Authentication Basic Authentication
 Success Response

Example:

Status: 200

Content:

subjectUIDs: ["A00021", "A00042", "A00089"]
 Error Response

Code: 401 UNAUTHORIZED

Content:{error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}
 Example Call
$.ajax({
    url: "https://examplehost.com/study/137/commonparentsubjects",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa(username + ":" + password)
    },
    success : function(r) {
        console.log(r);
    }
});

 Back to top

Get all siblings of a subject

Retrieve a list of siblings for a specific subject.

 URL /study/{studyID}/siblings/{subjectUID}
 Method GET
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137

subjectUID as [string], e.g. subjectUID = "A1234"
 Authentication Basic Authentication
 Success Response

Example:

Status: 200

subjectUIDs: ["A00021", "A00031"]
 Error Response

Code: 401 UNAUTHORIZED

Content:{error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}
 Example Call
$.ajax({
    url: "https://examplehost.com/study/137/siblings/A1234",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa(username + ":" + password)
    },
    success : function(r) {
       console.log(r);
   }
});

 Back to top

Get all parental relationships

Retrieve a list of all parental relationships within a study.

 URL /study/{studyID}/relationship
 Method GET
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137
 Authentication Basic Authentication
 Success Response

Example:

Status: 200

Content:

relationships: [
    {
        id: 123,
        subjectUID: "A000231",
        relativeUID: "A000233",
        parentType: "Mother"
    },
    {...},
    {...}
]
 Error Response

Code: 401 UNAUTHORIZED

Content:{error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}

OR

Code: 404 NOT FOUND

Content:{error:"No parent relationship exists."}
 Example Call
$.ajax({
    url: "https://examplehost.com/study/137/relationship",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa(username + ":" + password)
    },
    success : function(r) {
        console.log(r);
    }
});

 Back to top

Delete parental relationship

Delete a parental relationship between two members of a study.

 URL /study/{studyID}/relationship/{relationshipID}
 Method DELETE
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137

relationshipID as [Integer], e.g. relationshipID = 123
 Authentication Basic Authentication
 Success Response

Example:

Status: 200
 Error Response

Code: 401 UNAUTHORIZED

Content:{error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid parental relationship."}
 Example Call
$.ajax({
    url: "https://examplehost.com/study/137/relationship/123",
    dataType: "json",
    headers: {
        "Authorization": "Basic " + btoa(username + ":" + password)
    },
    type: "DELETE",
    success : function(r) {
        console.log(r);
    }
});

 Back to top

Add parental relationship

Add a parental relationship between two members of a study.

 URL /study/{studyID}/relationship
 Method PUT
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137
Data Parameters
{
    relationship: {
        subjectUID : [string],
        relativeUID: [string],
        parentType: [string]
    }
}

Valid selections:

parentType: ["Mother", "Father"]

Example:

{
    relationship: {
        subjectUID: "A000231",
        relativeUID: "A000233",
        parentType: "Mother"
    }
}
 Authentication Basic Authentication
 Success Response

Example:

Status: 200

Message: "Relationship created successfully"
 Error Response

Code: 401 UNAUTHORIZED

Content: {error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}

OR

Code: 404 NOT FOUND

Content:{error:"A subject with this UID does not exist."}

OR

Code: 404 NOT FOUND

Content:{error:"A relative with this subject UID does not exist."}

OR

Code: 403 FORBIDDEN

Content:{error:"Cannot create a relationship for a subject with this Subject Status."}

OR

Code: 403 FORBIDDEN

Content:{error:"Cannot create a relationship for a relative with this Subject Status."}

OR

Code: 404 NOT FOUND

Content:{error:"Parent Type must be "Mother" or "Father"."}

OR

Code: 404 NOT FOUND

Content:{error:"Parent Type not specified."}

OR

Code: 403 FORBIDDEN

Content:{error:"Consanguineous relationship detected in a study not configured to permit it."}
 Example Call
$.ajax({
     url: "https://examplehost.com/study/137/relationship",
     dataType: "json",
     headers: {
        "Authorization": "Basic " + btoa(username + ":" + password)
    },
    data: {
        subjectUID: "A000231",
        relativeUID: "A000233",
        parentType: "Mother"
    },
    type: "PUT",
    success: function (res) {}
});

 Back to top

Get BloodLine of a subject

Retrieve a list of blood relatives for a specific subject, annotated with relationship type (mother, grandfather, daughter, grandson, etc.).

 URL /study/{studyID}/membership/{subjectUID}
 Method GET
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137

subjectUID as [String], e.g. subjectUID = "A012345"
 Authentication Basic Authentication
 Success Response

Example:

Status: 200

Content:

bloodline: [
       {
           subjectUID: "A000231",
           firstName: "Fred",
           lastName": "Barrymore",
           relation: "Father",
           twin": " ",
           dateOfBirth": "1976-06-05"
       },
       {...},
       {...}
   ]
 Error Response

Code: 401 UNAUTHORIZED

Content:{error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}

OR

Code: 404 NOT FOUND

Content:{error:"A subject with this UID does not exist."}

OR

Code: 404 NOT FOUND

Content:{error:"No Pedigree members exists."}
 Example Call
$.ajax({
    url: "https://examplehost.com/study/137/membership/A012345",
    dataType: "json",
    headers: {
        "Authorization": "Basic " + btoa(username + ":" + password)
    },
    type: "GET",
    success : function(r) {
        console.log(r);
    }
});

 Back to top

Visualise pedigree of proband

Retrieve a pedigree visualisation (in Scalable Vector Graphics format) with respect to a specific proband.

 URL /study/{studyID}/pedigree/{subjectUID}
 Method GET
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137

subjectUID as [string], e.g. subjectUID= "A000231"
 Authentication Basic Authentication
 Success Response

Example:

Status: 200

Content:

{ svg : "<svg> ... </svg>" }
 Error Response

Code: 401 UNAUTHORIZED

Content: {error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}

OR

Code: 404 NOT FOUND

Content:{error:"A subject with this UID does not exist."}

OR

Code: 404 NOT FOUND

Content:{error:”Pedigree view does not exists."}
 Example Call
$.ajax({
    url: "https://examplehost.com/study/137/pedigree/A000231",
    dataType: "json",
    headers: {
        "Authorization": "Basic " + btoa(username + ":" + password)
    },
    type: "GET",
    success : function(r) {
        console.log(r);
    }
});

 Back to top

Get pedigree configuration

Retrieve the current pedigree module configuration for a study.

 URL /study/{studyID}/configuration
 Method GET
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137
 Authentication Basic Authentication
 Success Response

Example:

Status: 200

Content:

{
    configuration: {
        statusAllowed: true,
        customFieldName: "BreastCancerAffected",
        dobAllowed: true,
        ageAllowed: true,
        inbreedAllowed: true
    }
}
 Error Response

Code: 401 UNAUTHORIZED

Content: {error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}

OR

Code: 404 NOT FOUND

Content:{error:"Pedigree configuration does not exist."}
 Example Call
$.ajax({
    url: "https://examplehost.com/study/137/configuration",
    dataType: "json",
    headers: {
        "Authorization": "Basic " + btoa(username + ":" + password)
    },
    type: "GET",
    success : function(r) {
        console.log(r);
    }
});

 Back to top

Update pedigree configuration

Update the pedigree module configuration for a study.

 URL /study/{studyID}/configuration
 Method POST
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137
 Data Parameters
{
    configuration: {
        statusAllowed: [boolean],
        customFieldName: [string],
        dobAllowed: [boolean]
        ageAllowed: [boolean],
        inbreedAllowed: [boolean]
    }
}

Example:

{
    configuration: {
        statusAllowed: true,
        customFieldName: "BreastCancerAffected",
        dobAllowed: true,
        ageAllowed: true,
        inbreedAllowed: true
    }
}
 Authentication Basic Authentication
 Success Response

Example:

Status: 200

Message: "Configuration updated successfully"
 Error Response

Code: 401 UNAUTHORIZED

Content:{error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}

OR

Code: 409 CONFLICT

Content:{error:"Cannot update a pedigree configuration when no configuration has been set previously."}
 Example Call
$.ajax({
    url: "https://examplehost.com/study/137/configuration",
    dataType: "json",
    headers: {
        "Authorization": "Basic " + btoa(username + ":" + password)
    },
    data: {
        statusAllowed: true,
        customFieldName: "BreastCancerAffected",
        dobAllowed: true,
        ageAllowed: true,
        inbreedAllowed: true
    },
    type: "POST",
    success: function (res) {}
});

 Back to top

Get yes/no subject custom fields

Retrieve a list of subject custom fields which have yes/no encoded values. This is a supporting function that is useful when setting the "Affected status field" of the pedigree module configuration.

 URL /study/{studyID}/binarycustomfields
 Method GET
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137
 Authentication Basic Authentication
 Success Response

Example:

Status: 200

customFieldNames: ["BreastCancerAffected", "ColonCancerAffected"]
 Error Response

Code: 401 UNAUTHORIZED

Content:{error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}
 Example Call
$.ajax({
    url: "https://examplehost.com/study/137/binarycustomfields",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa(username + ":" + password)
    },
    success : function(r) {
        console.log(r);
    }
});

 Back to top

Get visualisation of a pedigree sent (but not persisted)

Retrieve a visualisation (in Scalable Vector Graphics format) of pedgree data that are sent to The Ark for processing but not persisted (saved) as subjects of a study.

 URL /study/{studyID}/visualisation
 Method POST
 URL Parameters

Required:

studyID as [number], e.g. studyID = 137
Data Parameters

{

    subjects: [
        { individualId: [string],
          father: [string],
          mother: [string],
          gender: [string],
          zygosity: [string],
          proband: [string],
          deceased: [string],
          affected: [string],
          dOB: [string]
        },
        { },
        { }
    ]

}
Valid Selections :

zygosity: ["MZ Twin", "DZ Twin", "Unknown"]
gender: ["Male", "Female", "Unknown"]
deceased: ["Yes", "No"]
proband: ["Yes", "No"]
affected: ["Affected", "Unaffected", "Missing"]

Example:
{

    subjects: [
        { individualId: "A12345",
          father: "A12346",
          mother: "A12347",
          gender: "Male",
          zygosity: "MZTwin",
          proband: "Yes",
          deceased: "No",
          affected: "Affected",
          dOB: "2010-01-03"
        },
        { individualId: "A12346",
          father: "A12355",
          mother: "A12356",
          gender: "Male",
          zygosity: "Unknown",
          proband: "No",
          deceased: "No",
          affected: "Affected",
          dOB: "1985-04-02"
        },
        { },
        { }
    ]

}
 Authentication Basic Authentication
 Success Response

Example:

Status: 200

Content:

{ svg : "<svg> ... </svg>" }
 Error Response

Code: 401 UNAUTHORIZED

Content:{error:"The authenticated user account does not have sufficient privileges to perform this action."}

OR

Code: 404 NOT FOUND

Content:{error:"Invalid Study ID."}

OR

Code: 404 NOT FOUND

Content:{error:"A study with this ID does not exist."}

OR

Code: 406 NOT ACCEPTABLE

Content:{error:"The mandatory field "Gender" can only take values "Male", "Female" or "Unknown"."}

OR

Code: 406 NOT ACCEPTABLE

Content:{error:"The field "Affected" can only take values "Affected" or "Unaffected"."}

OR

Code: 406 NOT ACCEPTABLE

Content:{error:"The field "Zygosity" can only take values "MZTwin", "DZTwin" or "Unknown"."}

OR

Code: 406 NOT ACCEPTABLE

Content:{error:"The field “Deceased“ can only take values "Yes", "No" or "Missing"."}

OR

Code: 406 NOT ACCEPTABLE

Content:{error:"The field "Proband" can only take values "Yes", "No" or "Missing"."}

OR

Code: 204 NO CONTENT

Content:{error:"The mandatory field “IndividualId“ can not be empty."}

OR

Code: 204 NO CONTENT

Content:{error:"The mandatory field "FamilyId" can not be empty."}

OR

Code: 404 NOT FOUND

Content:{error:"Specified mother ID is not present in the list."}

OR

Code: 404 NOT FOUND

Content:{error:"Specified father ID is not present in the list."}
 Example Call
$.ajax({
    url: "https://examplehost.com/study/137/visualisation",
    dataType: "json",
    headers: {
        "Authorization": "Basic " + btoa(username + ":" + password)
    },
    data: [
        { individualId: "A12345",
          father: "A12346",
          mother: "A12347",
          gender: "Male",
          zygosity: "MZTwin",
          proband: "Yes",
          deceased: "No",
          affected: "Affected",
          dOB": "2010-01-03"
        },
        { individualId: "A12346",
          father: "A12355",
          mother: "A12356",
          gender: "Male",
          zygosity: "Unknown",
          proband: "No",
          deceased: "No",
          affected: "Affected",
          dOB: "1985-04-02"
        },
        { },
        { }
    ];
    type: "POST",
    success: function (res) {}
});