NAV Navbar
Sample API calls using cURL
  • Introduction
  • API Endpoints
  • Authentication
  • Prepared Forms API
  • Drafts API
  • Referrals API
  • Uploading Files
  • Webhooks
  • Error Handling
  • Updating From Earlier Versions
  • Change Log

    • Introduction

    Welcome to Dental Referrals API V2 Documentation!

    This page is a guide for software developers looking to integrate an external application with Dental Referrals Web Application.

    Each API method in this documentation comes with a sample command using cURL. You can view these code examples in the dark area to the right.

    API Endpoints

    Staging

    While in development, please use the staging API endpoint:

    https://staging.dental-referrals.org/react4r/v2/

    Production

    Production API calls should be made against the live application's endpoint:

    https://app.dental-referrals.org/react4r/v2/

    Authentication

    Header-based Authentication

    To authorize your API calls, use:

    curl -H "Authorization: Token token=<YOUR_API_KEY>" "https://staging.dental-referrals.org/react4r/v2/"

    Make sure to replace <YOUR_API_KEY> with your actual API key.

    For example, if you API key is 42a42a42a42a424a2aa4, the call becomes:

    curl -H "Authorization: Token token=42a42a42a42a424a2aa4" "https://staging.dental-referrals.org/react4r/v2/"

    Expected response:

    {"status": "success"}

    Dental Referrals API uses API keys to allow access to the API. An API key is a 10-character hexadecimal value like 42a42a42a42a424a2aa4.You may request an API key by emailing office@dental-referrals.org.

    Every request to the API must include an API key in the header of the request as follows:

    Authorization: Token token=<YOUR_API_KEY>

    One API Key Per Medical Practice

    Each end user (Medical Practice) must obtain their own API key that will be linked to their data on our system. This ensures no unauthorized access happens between the two separate medical practices.

    Authentication Errors

    If a request fails authentication for any reason, a HTTP 401 Not Authorized response is returned.

    Prepared Forms API

    A central use-case for the API is to transition patient data from an external system into medical forms inside Dental Referrals Web Application while saving the effort of copy-pasting the data between two systems.

    When used in a desktop application, a usual integration workflow consist of 2 steps:

    1. Make a request to Dental Referrals API, passing patient data in the body of the request. In response, receive a unique URL to a medical form page inside Dental Referrals Web Application - that URL when opened will have all the submitted data pre-populated into its fields.

    2. Use user's default browser or a built-in web view to open the unique medical form URL received in step 1 for user to submit the rest of the referral data.

    List Available Forms

    curl -H "Authorization: Token token=<YOUR_API_KEY>" "https://staging.dental-referrals.org/react4r/v2/available_forms"

    The above command returns a JSON array of form types:

    ["AdultRestorativeForm","ChildOralCareForm"]

    This API method lists all medical form types that are enabled for a given API key. One of these form types must be used for subsequent call to Prepare Form API method.

    HTTP Request

    GET <API_ENDPOINT>/available_forms

    Request Parameters

    Does not require any input parameters.

    Response Format

    The response is an array of medical form types. See example response in the right side pane.

    Prepare Form

    Prepare an Adult Restorative Referral form with pre-populated patient data:

    curl -H "Authorization: Token token=<YOUR_API_KEY>" --data "form_type=AdultRestorativeForm&patient_title=Mr&patient_first_name=John&patient_last_name=Doe&patient_identifier=1&patient_dob=10/10/2010" "https://staging.dental-referrals.org/react4r/v2/prepare_form"

    The above command returns JSON structured as follows:

    {
    "status":"success",
    "prepared_form_url":"https://staging.dental-referrals.org/prepared_forms/show/d090e3dd-614f-47f3-8bc7-e403c1a2936e", 
    "urn":"TST0000001", 
    "ptguid":"NDJhNDJhNTJlOTZmOTE5YTdmYTc="
}

    This API method prepares a medical form of a given type by pre-populating patient data into corresponding fields and assigning a unique URL to this pre-populated form.

    HTTP Request

    POST <API_ENDPOINT>/prepare_form

    Request Parameters

    Parameter Type Required Default Description
    system_type String No WD Identifies which system is using the API. One of: WD, WT, PD, PC, DN, DT, SE.
    form_type String Yes* Medical form type. Must be one of the types returned by Available Forms API method.

    * If you are passing system_type=SE then this parameter is optional (the system will allow the user to select the form type in the browser once the prepared form URL is opened.) For all other system types, form_type parameter is required.
    patient_title String No Patient's title. Must be one of: Mr, Mrs, Miss, Master, Dr.
    patient_first_name String No Patient's first name.
    patient_last_name String No Patient's last name.
    patient_dob String Yes Patient’s date of birth, in the following format: DD/MM/YYYY.
    patient_postcode String No Patient's postcode.
    patient_email String No Patient email.
    patient_address_line_1 String No Patient's address line 1. If provided, will be concatenated with the other address_line_x parameters into a single address field on the medical form.
    patient_address_line_2 String No Patient's address line 2. If provided, will be concatenated with the other address_line_x parameters into a single address field on the medical form.
    patient_address_line_3 String No Patient's address line 3. If provided, will be concatenated with the other address_line_x parameters into a single address field on the medical form.
    patient_town String No Patient's town or city.
    patient_mobile_tel String No Patient's mobile phone number.
    patient_home_tel String No Patient's home phone number.
    patient_work_tel String No Patient's work phone number.
    patient_phone_number String No If patient's phone number is present, but it is not clear if it's home, work, or mobile number, the phone number should go into this field.
    permission_sms Numeric No One of: 0, 1. The 1 means that we have permission to contact the patient on their mobile number via SMS.
    nhs_number Numeric No Patient's NHS Number.
    gender String No Patient’s gender. One of: M, MALE, F, FEMALE.
    patient_gp_name String No Patient's general practitioner's name.
    patient_gp_postcode String No Patient's general practitioner's postcode.
    patient_gp_street_address String No Patient's general practitioner's street address.
    patient_gp_town String No Patient's general practitioner's city or town.
    referrer_gdc String No Referrer's GDC number.
    referrer_name String No Referrer's name.
    urgent Numeric No If set to 1, the resulting medical form will have the Care Type set to Urgent, otherwise Routine.
    medical_history_drugs Text No List of patient's current medications in free text format.
    medical_history_text Text No Medical alert information or additional medical history information, in free text form.
    medical_forms_as_single_file Numeric No If set to 1, the exported PDF medical forms will be merged into one file when notifying the files_ready_webhook_url. Check out Webhooks for more.
    files_ready_webhook_url Text No A callback URL to trigger when the PDF forms become available for this referral. For payload format, please see Webhooks section.
    patient_identifier String No Internal patient identifier within your system. If provided, this will be appended to your API key, out of which a Base64 hash will be produced and stored as PTGUID (Patient GUID) within our system. This value is returned as part of the response and can later be used to query the status of submitted referral, same as the URN value.
    fileupload_id Numeric No An ID of the fileupload entity with pre-uploaded files to be tied to this referral. For more on fileuploads, refer to Uploading Files.

    Response Format

    Parameter Type Description
    status String One of: success or error.
    prepared_form_url String The URL to the web page with a prepared medical form, where patient data supplied in the request is pre-filled into corresponding fields within the form.
    urn String URN code of the referral that will be associated with this record once the prepared form is submitted by the user.
    ptguid String PTGUID (Patient GUID) value that was created as a Base64 hash of the API KEY + patient_identifier request parameter. This parameter will only be present in the response if patient_identifier was provided to the Prepare Form request.

    Drafts API

    Save Draft

    Prepare an Adult Restorative Referral form with pre-populated patient data:

    curl -H "Authorization: Token token=<YOUR_API_KEY>" --data "form_type=AdultRestorativeForm&patient_title=Mr&patient_first_name=John&patient_last_name=Doe&patient_identifier=1&patient_dob=10/10/2010" "https://staging.dental-referrals.org/react4r/v2/save_draft"

    The above command returns JSON structured as follows:

    {
    "status":"success",
    "draft_id":11047,
    "urn":"TST0000001",
    "ptguid":"NDJhNDJhNTJlOTZmOTE5YTdmYTc="
}

    This API method allows to save drafts of medical forms within Dental Referrals Web Application, linking these drafts to a user's account that is tied to the API key.

    HTTP Request

    POST <API_ENDPOINT>/save_draft

    Request Parameters

    Exactly the same request parameters are available as for the Prepare Form API method.

    Response Format

    Parameter Type Description
    status String One of: success or error.
    draft_id Numeric The unique numeric reference of the draft within Dental Referrals Web Application.
    urn String URN code of the referral that will be associated with this record once the draft is submitted by the user.
    ptguid String PTGUID (Patient GUID) value that was created as a Base64 hash of the API KEY + patient_identifier request parameter. This parameter will only be present in the response if patient_identifier was provided to the Save Draft request.

    Referrals API

    Referral Status

    Check the status of a single Referral using a URN code:

    curl -H "Authorization: Token token=<YOUR_API_KEY>" "https://staging.dental-referrals.org/react4r/v2/referral_status?urn=TST0000001"

    The above command returns JSON structured as follows:

    {
    "status":"success",
    "referral_status":"Sent to: St Clements Dental Suite - Mr E Harunani",
    "referrer_name":"Nitin Joshi",
    "referral_reason":"Minor Oral Surgery",
    "referral_files":[
        "https://staging.dental-referrals.org/documents/TST0000001.pdf",
        "https://staging.dental-referrals.org/documents/TST0000001_MH.pdf"]
}

    Use this API method to check the status of one specific referral that:

    HTTP Request

    GET <API_ENDPOINT>/referral_status

    Request Parameters

    Parameter Type Required Description
    urn String Yes URN code of the referral to return the status for.

    Response Format

    Parameter Type Description
    status String One of: success or error - indicates whether your API request is successful or not.
    referral_urn String Unique 10-symbol identifier of the referral within Dental Referrals online system.
    referral_status String The current status of this referral in Dental Referrals online system.
    referral_name String Name of the referring dentist.
    referral_reason String The reason this referral was submitted.
    referral_files Array of Strings Unique 10-symbol identifier of the referral within Dental Referrals online system.

    Batch Referral Status

    Check the status of a batch of recent referrals

    curl -H "Authorization: Token token=<YOUR_API_KEY>" "https://staging.dental-referrals.org/react4r/v2/batch_referral_status?count=2"

    The above command returns JSON structured as follows:

    {
    "status":"success",
    "referral_data": 
    [
        {
        "referral_urn":"TST0000001", 
        "referral_status":"Entered on System", 
        "referrer_name":"Jane Doe", 
        "referral_reason":"Restorative", 
        "referral_files":[
            "https://staging.dental-referrals.org/documents/TST0000001.pdf",
            "https://staging.dental-referrals.org/documents/TST0000001_MH.pdf"
            ]
        },

        {
        "referral_urn":"TST0000002",
        "referral_status":"Sent to: St Clements Dental Suite", 
        "referrer_name":"Jane Doe", 
        "referral_reason":"Restorative", 
        "referral_files":[
            "https://staging.dental-referrals.org/documents/TST0000002.pdf"
            ]
        }
    ]
}

    Use this API method to check the status of up to 100 referrals most recently submitted through the API using the given API key.

    HTTP Request

    GET <API_ENDPOINT>/batch_referral_status

    Request Parameters

    Parameter Type Required Default Value Bounds Description
    count Numeric No 100 If larger than 100, will be set to 100 anyway Maximum number of recent patient's referrals to return statuses for.

    Response Format

    Parameter Type Description
    status String One of: success or error - indicates whether your API request is successful or not.
    referral_data JSON Array A JSON array of referral statuses, each status - a JSON object with the following fields:
    referral_urn - Unique 10-symbol identifier of the referral within Dental Referrals online system.
    referral_status - The current status of this referral in Dental Referrals online system.
    referrer_name - Name of the referring dentist.
    referral_reason - The reason this referral was submitted.
    referral_files - An array of URLs to PDF files for this referral.

    Referral Status By Patient

    Check the status of all referrals that belong to a patient, using PTGUID

    curl -H "Authorization: Token token=<YOUR_API_KEY>" "https://staging.dental-referrals.org/react4r/v2/patient_referrals?count=2&ptguid=NDJhNDJhNTJlOTZmOTE5YTdmYTc="

    The above command returns JSON structured as follows:

    {
    "status":"success",
    "referral_data": 
    [
        {
        "referral_urn":"TST0000001", 
        "referral_status":"Entered on System", 
        "referrer_name":"Jane Doe", 
        "referral_reason":"Restorative", 
        "referral_files":[
            "https://staging.dental-referrals.org/documents/TST0000001.pdf",
            "https://staging.dental-referrals.org/documents/TST0000001_MH.pdf"
            ]
        },

        {
        "referral_urn":"TST0000002",
        "referral_status":"Sent to: St Clements Dental Suite", 
        "referrer_name":"Jane Doe", 
        "referral_reason":"Restorative", 
        "referral_files":[
            "https://staging.dental-referrals.org/documents/TST0000001.pdf"
        ]
        }
    ]
}

    Use this API method to check the status of most recent referrals submitted for a given PTGUID (which is created as a Base64 of an API key and patient_identifier parameter used in Prepare Form and Save Draft API calls.)

    HTTP Request

    GET <API_ENDPOINT>/patient_referrals

    Request Parameters

    Parameter Type Required Default Value Bounds Description
    ptguid String Yes PTGUID (Patient GUID) code of the referral to return the status for.
    count Numeric No 100 If larger than 100, will be set to 100 anyway Maximum number of recent patient's referrals to return statuses for.

    Response Format

    Parameter Type Description
    status String One of: success or error - indicates whether your API request is successful or not.
    referral_data JSON Array A JSON array of referral statuses, each status - a JSON object with the following fields:
    referral_urn - Unique 10-symbol identifier of the referral within Dental Referrals online system.
    referral_status - The current status of this referral in Dental Referrals online system.
    referrer_name - Name of the referring dentist.
    referral_reason - The reason this referral was submitted.
    referral_files - An array of URLs to PDF files for this referral.

    Uploading Files

    Both Prepare Form and Save Draft API methods allow an optional fileupload_id parameter that allows attaching files to the referral. In order to attach files, they must be pre-uploaded before making a call to Prepare Form or Save Draft API methods - so that when a medical form page opens, the user can see the files that were already uploaded.

    The steps needed to upload files along with referral data are:

    1. Make a call to Prepare Fileupload API method and receive an ID of newly created fileupload entity in response.

    2. Use the <FILEUPLOAD_ID> obtained in step 1 to upload actual files to the server.

    3. Supply the <FILEUPLOAD_ID> as the fileupload_id parameter to the Prepare Form and Save Draft API methods.

    Prepare Fileupload

    Create a fileupload entity, to which further uploads will be linked:

    curl -H "Authorization: Token token=<YOUR_API_KEY>" "https://staging.dental-referrals.org/react4r/v2/prepare_fileupload"

    The above command returns JSON structured as follows:

    {
    "status":"success",
    "fileupload_id":396
}

    Prepares a fileupload entity to link further uploads to. The 396 is the FILEUPLOAD_ID to be used in the call to Add File API method.

    HTTP Request

    GET|POST <API_ENDPOINT>/prepare_fileupload

    Request Parameters

    Does not require any request parameters.

    Response Format

    Parameter Type Description
    status String One of: success or error.
    fileupload_id Numeric The FILEUPLOAD_ID to be used in the call to Add File API method.

    Add File

    Upload a file and link it to a previously prepared fileupload enpoint:

    curl -H "Authorization: Token token=<YOUR_API_KEY>" -H "Upload-Content-Type:image/jpeg" -H "Upload-Filename:file.jpg" -H "Upload-Kind:radiograph" -H "Upload-Date:29/01/2016" -v -F file=@/home/user/file.jpg "https://staging.dental-referrals.org/react4r/v2/fileupload/396/add_file"

    Expected response:

    {"status": "success"}

    With the FILEUPLOAD_ID obtained from Prepare Fileupload API call, this method allows to upload files and linked them all to the same FILEUPLOAD_ID.

    HTTP Request

    POST <API_ENDPOINT>/fileupload/<FILEUPLOAD_ID>/add_file

    Allowed Headers:

    Header Required Default Description
    Upload-Content-Type Yes MIME type of the uploaded file. Supported kinds are image/jpeg, image/jpg, image/bmp, image/tiff, image/png, text/rtf, application/pdf, application/msword - for doc files, and application/vnd.openxmlformats-officedocument.wordprocessingml.document - for docx files.
    Upload-Filename Yes Name of the original file, with extension.
    Upload-Kind No other Type of the upload. At the moment, only 2 values are allowed: radiograph and other.
    Upload-Date Required if Upload-Kind set to radiograph Date when the radiograph has been taken, in DD/MM/YYYY format.

    Request Parameters

    Does not require any request parameters.

    Response Format

    Parameter Type Description
    status String One of: success or error.

    Tying Everything Together

    Now that files are uploaded to the server and tied to a single <FILEUPLOAD_ID>, simply use that <FILEUPLOAD_ID> as the value for fileupload_id parameter in Prepare Form and Save Draft API methods.

    Webhooks

    When a referral is submitted to Dental Referrals Web Application, all medical forms are exported to PDF format and attached to the referral. The export to PDF happens in background queue after the referral is submitted and so isn't immediatelly available to the user. In order to assist with collection of exported PDF forms, the Prepare Form and Save Draft API methods accept a parameter called files_ready_webhook_url - a URL to trigger when the PDF forms become available for referrals submitted through the API.

    If files_ready_webhook_url is provided during a call to Prepare Form or Save Draft API method, when the PDF files become available, the system will send a POST request to the specified URL with the following payload in JSON format:

    { "urn":"<URN_OF_REFERRAL>", "files": ["<URL_OF_THE_PDF_FORM_1>", "<URL_OF_THE_PDF_FORM_2>", ... ] }

    Retry policy

    If the webhook URL fails or returns a response code other than 200, we will retry 3 more times - in an hour, in 4 hours, and then in a day.

    Accessing PDF exports

    To fetch PDF exports, use:

    curl --header "Accept: application/json" -H "Authorization: Token token=<YOUR_API_KEY>" -O "https://staging.dental-referrals.org/documents/show/attachments/1/pdfs/original/TST0000001_AdultRestorativeForm.pdf"

    In order to fetch the attachments using URLs that are sent to the files_ready_webhook_url, include an Authorization: Token token=<YOUR_API_KEY> header along with your request.

    Error Handling

    Example of failed API request: API key not provided

    curl "https://staging.dental-referrals.org/react4r/v2/available_forms"

    Response:

    {
    "status":"error",
    "message":"Not Authorized. Check that you are providing a valid API key and that you have access to requested resource."
}

    If a request is invalid or is missing required parameters, a standard HTTP 400 or 422 response code will be returned. Additionally, a custom error message response will be returned with additional clarifications.

    Error Response Format

    In case of an error, in addition to an error status code, the response will contain the following fields:

    Field Description
    status The value will be set to "error".
    message A human-readable description of the error.

    Error Codes

    Code Meaning
    400 Bad parameter value or required parameter is missing. Check message for more details.
    401 Authorization error. Make sure you are passing your API key as part of the Authorization header. Refer to Authentication section.
    404 Entity not found. For example, you are making a call to Add File API method with an expired FILEUPLOAD_ID (these expire after the prepared form has been submitted by user in the browser.)
    422 Required patient_dob parameter is missing.
    500 An unhandled API error has occurred. Please contact API administrators to report.

    Updating From Earlier Versions

    Updating from Version 1 of the API

    API Endpoints

    We removed the /refadmin/ portion from all our application URLs and the staging endpoint is now served via HTTPS.

    So, the staging API endpoint used to be:

    http://staging.dental-referrals.org/refadmin/react4r/v1/

    and now becomes:

    https://staging.dental-referrals.org/react4r/v2/


    The production API endpoint used to be:

    https://app.dental-referrals.org/refadmin/react4r/v1/

    and now becomes:

    https://app.dental-referrals.org/react4r/v2/

    Authentication

    We are moving the authentication from URL parameter to a header-based model.

    And so the old way of authentication:

    curl http://staging.dental-referrals.org/refadmin/react4r/v1/available_forms?api_key=<YOUR_API_KEY>

    Now becomes:

    curl -H "Authorization: Token token=<YOUR_API_KEY>" https://staging.dental-referrals.org/react4r/v2/available_forms

    This way of passing the API KEY in the header of the request applies to all API V2 methods.

    API Method Changes

    Previously existing API methods are backward-compatible and should just continue to work once URLs are changed and authentication mechanism updated:

    The only other change is that Save Draft and Prepare Form methods now support an optional fileupload_id parameter.

    In addition to the existing methods, 2 new API methods have been introduced as a part of Fileupload Functionality.

    Change Log

    Date Author Description
    05 March 2024 Oleg Shevtsov Removed patient_gp_code field from prepare_form and save_draft
    12 Jun 2023 Oleg Shevtsov Added new patient_email field to prepare_form and save_draft
    25 Oct 2022 Oleg Shevtsov Added new patient_gp_code field to prepare_form and save_draft
    4 Oct 2022 Serhiy Pustovit New kinds of files that can be uploaded were added. Such as image/jpg, image/bmp, image/tiff, image/png, text/rtf, application/pdf, application/msword - for doc files, and application/vnd.openxmlformats-officedocument.wordprocessingml.document - for docx files.
    1 Sep 2020 Serhiy Pustovit patient_dob now is required field for prepare_form and save_draft endpoints. 422 error can be returned on invalid DOB. Fixed typos.
    2 Jul 2018 Irina Zayats Added new system_type - SE. For Prepare Form API method, if SE is passed as system_type then form_type parameter becomes optional and will allow the user to select the form type in the browser once the prepared form URL is opened. This does not apply to the Save Draft API method.
    9 Jan 2018 Irina Zayats Initial version of documentation.
    Sample API calls using cURL