NAV
ruby shell javascript php java csharp python

Introduction

Welcome to the Medsender Developer API documentation. You can use our API to send, receive, and interact with PHI.

NOTE: Our Developer API is constantly being enhanced and updated. Somethings may not be fully documented and we apologize for that in advance. On rare occasion, breaking changes may occur and we will notify you if/when that happens. We would love to hear from you on feedback, questions, or help on using the API. Get in touch with us at api@medsender.com.

If there is functionality that you'd like to have that we currently don't have documentation for, please contact us and we'd be happy to assist you.

Note: If you'd like to request some functionality that isn't available through this existing API, please contact us. Our team is happy to work with you on a case-by-case basis.

Client SDKs

We have language bindings in Shell, PHP, Java, and JavaScript (Node.js). Code examples are in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right. Client SDKs for .NET, Ruby, and others will be getting support soon as well. If you have a language you'd like us to support, contact us at api@medsender.com and we'll keep it in mind!

Below, we've included instructions on how to install and use our SDKs.

Ruby

Gemfile

...
gem 'medsender_phi', source: 'YOUR_UNIQUE_URL'
...

# Code to add to gemfile
bundle add medsender_phi --source="YOUR_UNIQUE_URL"

We've published our Ruby SDK to a private repository which means you can use bundler to install it. You will need a unique URL to access the repository, so if you don't have one, please contact us at api@medsender.com to obtain one.

Once you've got the unique URL, simply add our gem to your bundler file along with the URL as the source. We've provided an example to show what it looks like. After you add the gem to your bundler file, simply run bundle install and you'll now have access to our Ruby SDK!

PHP

auth.json

{
  "http-basic": {
    "sdk.medsender.com": {
      "username": "your_token",
      "password": ""
    }
  }
}

We've published our PHP SDK to a repository which means you can use composer to install it. However, the repository is private, so you would need a secret token to access it. If you don't have one, please contact us at api@medsender.com to obtain a token.

Once you have the token, you will need to use it when authenticating with the SDK repository. We strongly recommend you keep the credentials in a separate file other than your composer file. This file is typically called auth.json. We've included a sample of the auth.json. Replace your_token with the token we give you. You can keep the auth.json file in your COMPOSER_HOME or in the same directory as your composer.json. Just be sure not to commit your auth.json file.

Once that's done, you can now configure composer to include our SDK. Here are the steps:

  1. Run composer config repositories.medsender composer https://sdk.medsender.com/php
  2. Run composer require medsender/medsender-php-sdk
  3. Run composer install

With that completed, you should be able to get started using our SDK!

Javascript

We've published our Javascript SDK to a repository which means you can use npm to install it. However, the repository is private, so you would need a secret token to access it. If you don't have one, please contact us at api@medsender.com and we'd be happy to give it to you.

Once you have the URL, you need to include it in your .npmrc file. Simply append //npm-proxy.fury.io/medsender/:_authToken=your_secret_token to your .npmrc file. Don't forget to replace your_secret_token with the token we give you.

Once that's done, run these commands to start using our SDK:

  1. In your project root directory, run npm config set registry https://sdk.medsender.com/npm/
  2. Once that's finished, run npm install medsender-phi --registry https://npm-proxy.fury.io/medsender/ --save

Congratulations! You're now able to use our Javascript SDK!

To keep our SDK updated, you can run npm update --registry https://npm-proxy.fury.io/medsender/ --save.

Java

settings.xml

<?xml version="1.0"?>
<settings>
    <servers>
        <server>
            <id>fury</id>
            <username>USERNAME</username>
            <password>NOPASS</password>
            <configuration>
                <httpConfiguration>
                    <all>
                        <usePreemptive>true</usePreemptive>
                    </all>
                </httpConfiguration>
            </configuration>
        </server>
    </servers>
</settings>

pom.xml

<project>
  ...
  <repositories>
      <repository>
          <id>releases</id>
          <url>https://maven.fury.io/medsender/</url>
      </repository>
  </repositories>

  <dependencies>
      <dependency>
          <groupId>com.medsender</groupId>
          <artifactId>phi</artifactId>
          <version>[1.0,2.0)</version>
          <scope>compile</scope>
      </dependency>
  </dependencies>
  ...
</project>

We've published our Java SDK to a private maven repository. In order to install it, you would need a username. If you don't have it already, please email us at api@medsender.com and we'd be happy to generate credentials for you.

Once you have the credentials, you just need to include them in your settings.xml file. This can usually be found at ${user.home}/.m2/settings.xml. We've included an example settings.xml file so you can see what it would look like. Be sure to replace USERNAME with the SDK Token we give you. Keep the password as NOPASS.

Next, in your project that you'd like to use our API with, you need to include in your pom.xml file our maven repository https://maven.fury.io/medsender and add the SDK as a dependency. We've included an example of what your pom.xml file should include. With your pom.xml updated, you can now import the SDK as a dependency and use it in your project!

.NET

A published version is coming soon! Currently, if you'd like access to our .NET SDK, you'd need to contact us at api@medsender.com and we'd be happy to send it to you. We would you send a DLL file that you would then reference within your current project.

Python

We've published our Python SDK to a private repository and you can install it easily via pip. You can email us at api@medsender.com and we'd be happy to send you the details.

Authentication

To authorize, use this code:

require 'medsender_phi'

MedsenderAPI.configure do |config|
  config.username = 'your_api_key'
  config.password = 'your_client_secret'
end

api_instance = MedsenderAPI::ClientsApi.new

Make sure to replace your_client_secret and your_api_key with your keys.

Medsender uses API keys to allow access to the API. They give you full access to our API, so it's important that you keep them secure. Be sure not to share them with anyone outside your organization. We also advise you don't commit them to code repositories. Everyone is welcome to use our API! If you'd like to try us out, contact us at api@medsender.com and we'll email you your test environment keys.

All requests must contain an api_key and a client_secret, which you provide via HTTP Basic Auth. For basic auth, your username is your api key; and your password is your client secret.

Note: Implementing this step is necessary before using any of the below endpoints. Always include authentication before using any of the endpoints.

Sent Faxes

The Sent Fax Object

Attributes

from_number

The number this fax was sent from. Must be a number linked to your developer account. Either this number was ported into Medsender from your previous telecom provider, or it's a number we provisioned for you. We accept any fax number format, but we will always return it in +12223334444 format where +1 is the country code.

to_number

The number this fax was sent to. We accept any fax number format, but we will always return it in +12223334444 format where +1 is the country code.

patient_name

The name of the patient this record is associated with. When provided, we will include this in the cover sheet we generate.

patient_dob

The date of birth of the patient this record is associated with. Accepted format is YYYY-MM-DD.

note

A note that is included in the cover sheet of the document.

sender_name

The name of the person sending this record. Will be included in the cover sheet of the document.

recipient_name

The name of the intended recipient of this record. Will be included in the cover sheet of the document.

record_status

Can be activated, archived, or revoked. If the status is activated, then this record can be accessed digitally, and will be listed when getting all sent faxes by default. If the status is archived, then this record can still be accessed digitally, but will no longer be listed when getting all sent faxes by default. If the status is revoked, then this record can no longer be accessed digitally (using the access code on the cover sheet), and will no longer be listed in sent faxes by default.

send_token

A unique identifier used to keep track of a sent fax. This is what you will use as the ID to get the status of a sent fax.

expiry

The date and time, in ISO-8061 format, digital access to this record expires (using access code on the cover sheet). Digital access expires 30 days after the request is made to send the fax.

view_count

The number of times this record was viewed digitally using the access code.

sent_at

The date and time, in ISO-8061 format, this record was sent at. Returned in UTC timezone.

completed_at

The date and time, in ISO-8061 format, this record transmission was completed at. Returned in UTC timezone.

sent_status

Can be queued, inprogress, success, or failure. queued means the record has been queued for transmission. inprogress means the record has started being transmitted. success means the record was successfully sent. failure means we were unable to send the record. We attempt to send a record via fax 5 times before marking it as failure.

document_type

Can accept three string values: document_only, access_code_sheet_only, or both. document_only will send just the document, access_code_sheet_only will send only the access code sheet, and both will send the access code sheet along with the document.

error_details

A json object that contains more information on why a fax failed during transmission.

is_test

Whether this transmission was conducted using test API keys. If true, then we didn't actually send a fax. Everything is simulated as if a fax was actually sent.

A link to access the record that was sent. Is valid for 5 minutes once the sent fax object is created and returned to you.

Send PHI via Fax

Code to send a fax:

api_instance = MedsenderAPI::SentFaxesApi.new
file = File.new('/path/to/file.pdf')
from_number = 'your_fax_number'
to_number = '9174732192'
opts = {
  patient_name: 'Philip J. Fry',
  patient_dob: '1974-08-14',
  note: 'This document is a patient referral',
  sender_name: 'Dr. Hubert Farnsworth',
  recipient_name: 'Dr. John Zoidberg',
  document_type: '',
  callback_url: 'https://your.callback.url'
}

begin
  result = api_instance.send_fax(file, from_number, to_number, opts)
  p result
rescue MedsenderAPI::ApiError => e
  puts "Exception when calling SentFaxesApi->send_fax: #{e}"
end

The above command will return JSON structured like this:

{
  "message": "Record has been sent, we will send a callback upon completion.",
  "faxId": "f5cfd99304f9"
}

This endpoint will queue your PHI file to be sent to any valid fax number. The response will contain the send token (noted as fax id) that you can use to keep track of the transmission. If the initial transmission fails, we keep retrying a total of 5 times before we consider the transmission a failure. Once the transmission completes or fails, we send a callback to your callback URL notifying you of the new transmission status. You can also check the status of the transmission using the Retrieve a sent fax.

We will provide a cover sheet which includes instructions for accessing the record via our platform. The cover sheet will also include metadata which you provide. The arguments sender_name, recipient_name, patient_name, and note you provide will be displayed on the cover sheet.

Arguments

file

The path to the file you'd like to send via fax. Must be a PDF or TIFF file. The file must contain less than 200 pages (199 excluding our cover sheet) and be less than 20 megabytes in size. We'll be adding other formats in the future.

from_number

The number you'd like to send the fax from. Can be provided in any phone number format. Must be a fax number linked to your developer account. To port your fax number over or provision a new fax number, please contact us at api@medsender.com.

to_number

The number you'd like to send the fax to. Can be provided in any phone number format.

patient_name

The name of the patient this record belongs to. If provided, will be listed on the cover sheet we generate.

patient_dob

The date of birth of the patient this record belongs to. Must be provided in YYYY-MM-DD format. Optional.

note

If provided, a note to include in the cover sheet of the fax. Usually a helpful description of the document to help the recipient.

sender_name

The name of the person sending this record. If provided, will be listed on the cover sheet we generate.

recipient_name

The name of the intended recipient of this record. If provided, will be listed on the cover sheet we generate.

document_type

Can accept three string values: document_only, access_code_sheet_only, or both. document_only will send just the document, access_code_sheet_only will send only the access code sheet, and both will send the access code sheet along with the document.

callback_url

The callback url to use when the fax has finished sending. If left blank, we'll use the callback url associated with the fax number you're sending from.

Response

If the arguments passed are valid, it will return the the send token (listed as fax ID) that you can then use to keep track of the transmission. If the arguments passed are invalid, we'll return an error object with more information.

Retrieve a sent fax

Code to retrieve a sent fax:

api_instance = MedsenderAPI::SentFaxesApi.new
fax_id = 'your_send_token'

begin
  result = api_instance.get_sent_fax_by_id(fax_id)
  p result
rescue MedsenderAPI::ApiError => e
  puts "Exception when calling SentFaxesApi->get_sent_fax_by_id: #{e}"
end

The above command will return JSON structured like this:

{
  "fromNumber": "+19177572947",
  "toNumber": "+19174732192",
  "recipientName": "Dr. John Zoidberg",
  "recordStatus": "activated",
  "patientName": "Philip J. Fry",
  "patientDob": "1974-08-14",
  "sendToken": "3e842d315d8f",
  "senderName": "Dr. Hubert Farnsworth",
  "expiry": "2020-03-21T23:37:01.000Z",
  "viewCount": 0,
  "note": "This document is a patient referral",
  "sentAt": "2020-02-20T23:37:01.000Z",
  "completedAt": "2020-02-20T23:37:04.000Z",
  "sentStatus": "success",
  "documentType": "both",
  "errorDetails": null,
  "isTest": true,
  "secureLink": "https://link.to.record"
}

Gets the details of a sent fax. Provide the send token of the fax that was returned when you sent it via our API.

Remember that 'your_send_token' is the fax id from the response of the previous endpoint.

Arguments

None

Response

This endpoint returns a sent fax object.

List all Sent Faxes

Code to retrieve all sent faxes:

api_instance = MedsenderAPI::SentFaxesApi.new
opts = {
  from_number: '9178473555',
  to_number: '9178473555',
  patient_name: 'John Doe',
  sender_name: 'Dr. Farnsworth',
  recipient_name: 'Dr. Recipient',
  date_start: '1994-02-22',
  date_end: '2020-01-20',
  is_test: true,
  page: 1,
  page_size: 50
}

begin
  result = api_instance.get_sent_faxes(opts)
  p result
rescue MedsenderAPI::ApiError => e
  puts "Exception when calling SentFaxesApi->get_sent_faxes: #{e}"
end

The above command will return JSON structured like this:

{
  "sentFaxes": [
    {
      "fromNumber": "+19177572947",
      "toNumber": "+19174732192",
      "recipientName": "Dr. John Zoidberg",
      "recordStatus": "activated",
      "patientName": "Philip J. Fry",
      "patientDob": "1974-08-14",
      "sendToken": "3e842d315d8f",
      "senderName": "Dr. Hubert Farnsworth",
      "expiry": "2020-03-21T23:37:01.000Z",
      "viewCount": 0,
      "note": "This document is a patient referral",
      "sentAt": "2020-02-20T23:37:01.000Z",
      "completedAt": "2020-02-20T23:37:04.000Z",
      "sentStatus": "success",
      "documentType": "both",
      "errorDetails": null,
      "isTest": true,
      "secureLink": "https://link.to.record"
    }
  ],
  "meta": {
    "totalCount": 1,
    "totalPages": 1,
    "perPage": 10,
    "page": 1
  }
}

Returns a list of all faxes you've previously sent. By default, the endpoint orders the returned sent faxes using the latest creation date. We also allow filtering via query parameters.

Arguments

from_number

The fax number you used to send the fax. Can be provided in any phone number format.

to_number

The fax number you sent the fax to. Can be provided in any phone number format.

sender_name

The name of the person who sent this record.

recipient_name

The name of the intended recipient of this record.

patient_name

Filter the sent faxes by the patient name.

patient_dob

Filter the sent faxes by the patient name. Must be specified in YYYY-MM-DD format.

date_start

Inclusively filter faxes beginning by the date they were received. Must be specified in YYYY-MM-DD format.

date_end

Inclusively filter faxes ending by the date they were sent. Must be specified in YYYY-MM-DD format.

order_by_date

Order the results in either asc (ascending) or dsc (descending). Default is descending.

is_test

Filter results based on whether they were test transmission or not. Default is false, only return real transmissions.

page

We paginate our results, with 10 results per page. You can specify which page to view using this parameter.

page_size

The number of results to show per page. Default is 10. Allowed values are 1 to 100, inclusive.

Returns

An array of sentFaxes which contains SentFax objects. If you have no sent faxes, we will return an empty array. If there was an error with the request, we'll return an error object explaining why.

Emails

The Email object

Attributes

recipient_email

The email the file was sent to. This can be any valid email e.g john.doe@medsender.com

recipient_name

The name of the recipient.

sender_name

The name of the user sending the email.

reply_to_email

The email the recipient will reply to if they click on reply in their email client. We send all our emails from no-reply@medsender.com, but with the reply to email flag, when the recipient clicks on reply it'll use that email to reply to instead. Be careful though, we can't ensure the reply to email is secure if you provide your own.

patient_name

The name of the patient this record is associated with.

patient_dob

The date of birth of the patient this record is associated with. Accepted format is YYYY-MM-DD.

record_status

The status of the record to be digitally accesed through the secure-link, can be active, archived or revoked.

email_status

The status of the email sent.

subject

The subject of the email.

note

The note to be displayed on the body of the email.

email_id

A unique identifier used to keep track of a sent email. This is what you will use as the emailId to get the status of a sent email.

expiry

The date and time, in ISO-8061 format, digital access to this record expires (using the secure link in the email).

sent_at

The date and time, in ISO-8061 format, this email was sent. Returned in UTC timezone.

last_viewed_at

The date and time, in ISO-8061 format, the document was viewed. Returned in UTC timezone.

error

Contain details about the email transmission error i.e error_code, error_message

Code to send a secure email link:

The above command will return JSON structured like this:

  {
    "message": "Record has been sent, we will send a callback upon completion.",
    "emailId": "f5cfd99304f9"
  }

This endpoint will send an email to the recipient's address. The response will contain the email_id that you can use to check status of the transmitted PHI.

The developer will send an email which includes instructions for accessing the record via our platform.

Arguments

file

The path to the file you'd like to send via email. Must be a PDF file. The file must contain less than 200 pages and be less than 20 megabytes in size. We'll be adding other formats in the future. Required

recipient_email

The email address you'd like to send the email to. Required.

sender_name

The name of the person sending this record. If provided, will be listed on the cover sheet we generate. Required.

recipient_name

The name of the recipient.

reply_to_email

The email address the recipients will respond to.

patient_name

The name of the patient this record belongs to.

patient_dob

The date of birth of the patient this record belongs to. Must be provided in YYYY-MM-DD format. Optional.

subject

If provided, will appear as the subject of the email. Usually a helpful description of the document to help the recipient.

note

If provided, a note to include in the body of the email. Usually a helpful description of the document to help the recipient.

expire_after

The number of days before the secure email link expiry. It Should be an Integer between 1 and 180 days.

callback_url

The http(s) callback trigger, only happens if the callback url is supplied.

Response

If the arguments passed are valid, it will return the the email id that you can then use to get details of the transmission. If the arguments passed are invalid, we'll return an error object with more information.

Retrieve details of the sent email

Code to retrieve the details of the email sent:

The above command will return JSON structured like this:

{
  "recipientEmail": "john.doe@example.com",
  "recipientName": "John Doe",
  "secureLink": "string",
  "senderName": "Dr. Farnsworth",
  "patientName": "John Doe",
  "patientDob": {},
  "emailStatus": "string",
  "sendToken": "string",
  "recordStatus": "string",
  "sentAt": "2021-09-30T07:24:53.891Z",
  "subject": "Secure Link to View Document.",
  "note": "This is a patient referral.",
  "expiry": "2021-09-30T07:24:53.891Z",
  "lastViewedAt": "2021-09-30T07:24:53.891Z",
  "error": null
}

Gets the details of a sent email. Provide the emailId on the Send Link Via Email endpoint response.

Arguments

None

Response

It will return a response object with details about the sent email.

Received Faxes

The Received Fax Object

Attributes

from_number

The number you received this fax from. Returned in +12223334444 format where +1 is the country code.

to_number

The number this fax was sent to. Must be a number linked to your developer account. Either this number was ported into Medsender from your previous telecom provider, or it's a number we provisioned for you. We accept any fax number format, but we will always return it in +12223334444 format where +1 is the country code.

file

The file received via fax. Only returned during the callback request we make when you receive fax to your number.

send_token

A unique identifier used to keep track of a received fax. This is what you will use as the ID to get the status of a sent fax.

sent_at

The date and time, in ISO-8061 format, this record was sent at. Returned in UTC timezone.

completed_at

The date and time, in ISO-8061 format, this record transmission was completed at. Returned in UTC timezone.

num_pages

The number of pages this fax contains.

fax_status

Can be success or failure. success means the record was successfully sent. failure means we were unable to send the record. We attempt to send a record via fax 5 times before marking it as failure.

caller_name

The caller ID associated with the fax number of the sender. Sometimes, this isn't provided by the sender.

error_details

A json object that contains more information on why a fax failed during transmission.

is_test

Whether this transmission was conducted using test API keys. If true, then we didn't actually receive a fax. Everything is simulated as if a fax was actually received.

A link to access the record that was sent. Is valid for 5 minutes once the sent fax object is created and returned to you. Only returned if getting an individual received fax.

client

The client ID associated with this received fax. Developers can create clients to better organize faxes. You can assign fax numbers to clients. Whenever you receive a fax, we assign it to the client associated with the fax number.

Receive PHI via Fax

Whenever Medsender receives a fax to a number linked to your developer account, we send a callback request to your specified callback URL. The request contains a Received Fax object. You can verify the request came from Medsender by hashing the send_token, completed_at, and your API key and comparing the result with the X-Medsender-Signature header we include with the request.

Retrieve a Received Fax

Code to retrieve a received fax:

api_instance = MedsenderAPI::ReceivedFaxesApi.new
fax_id = 'your_send_token'

begin
  result = api_instance.get_received_fax_by_id(fax_id)
  p result
rescue MedsenderAPI::ApiError => e
  puts "Exception when calling ReceivedFaxesApi->get_received_fax_by_id: #{e}"
end

The above command will return JSON structured like this:

{
  "fromNumber": "+9135758385",
  "toNumber": "+12076077796",
  "sendToken": "887183cc2a5f",
  "callerName": "TEST HOSPITAL",
  "sentAt": "2020-02-18T00:00:00.000Z",
  "completedAt": "2020-02-18T23:59:59.000Z",
  "numPages": 3,
  "isTest": true,
  "faxStatus": "success",
  "errorDetails": null,
  "client": "42486f1b-9297-401e-a3f4-869ce409c927",
  "secureLink": "https://link.to.record"
}

Gets the details of a received fax. Provide the send token of the fax that was returned when you received it.

Remember that 'your_send_token' here is the fax id for received faxes; not sent faxes.

Arguments

None

Response

This endpoint returns a received fax object.

Forward a Received Fax

This endpoint will queue a received PHI file to be forwarded to any valid fax number. The response will contain the send token (noted as fax id) that you can use to keep track of the transmission. If the initial transmission fails, we keep retrying a total of 5 times before we consider the transmission a failure. Once the transmission completes or fails, we send a callback to your callback URL notifying you of the new transmission status. You can also check the status of the transmission using the Retrieve a sent fax.

We will provide a cover sheet which includes instructions for accessing the record via our platform. The cover sheet will also include metadata which you provide. The arguments sender_name, recipient_name, patient_name, and note you provide will be displayed on the cover sheet.

Code to forward a received fax:

api_instance = MedsenderAPI::ReceivedFaxesApi.new
fax_id = 'c5ac4dd675d1' # String | The send token associated with the received fax.
to_number = '9174732192'
opts = {
  from_number: 'your_fax_number',
  patient_name: 'Philip J. Fry',
  patient_dob: '1974-08-14',
  note: 'This document is a patient referral',
  sender_name: 'Dr. Hubert Farnsworth',
  recipient_name: 'Dr. John Zoidberg',
  document_type: '',
  callback_url: 'https://your.callback.url'
}

begin
  #Forward received PHI via fax.
  result = api_instance.forward_received_fax(fax_id, to_number, opts)
  p result
rescue MedsenderAPI::ApiError => e
  puts "Exception when calling ReceivedFaxesApi->forward_received_fax: #{e}"
end

The above command will return JSON structured like this:

{
  "message": "Record has been sent, we will send a callback upon completion.",
  "faxId": "f5cfd99304f9"
}

Arguments

from_number

The number you'd like to send the fax from. Can be provided in any phone number format. Must be a fax number linked to your developer account. To port your fax number over or provision a new fax number, please contact us at api@medsender.com.

to_number

The number you'd like to send the fax to. Can be provided in any phone number format.

patient_name

The name of the patient this record belongs to. If provided, will be listed on the cover sheet we generate.

patient_dob

The date of birth of the patient this record belongs to. Must be provided in YYYY-MM-DD format. Optional.

note

If provided, a note to include in the cover sheet of the fax. Usually a helpful description of the document to help the recipient.

sender_name

The name of the person sending this record. If provided, will be listed on the cover sheet we generate.

recipient_name

The name of the intended recipient of this record. If provided, will be listed on the cover sheet we generate.

document_type

Can accept three string values: document_only, access_code_sheet_only, or both. document_only will send just the document, access_code_sheet_only will send only the access code sheet, and both will send the access code sheet along with the document.

callback_url

The callback url to use when the fax has finished sending. If left blank, we'll use the callback url associated with the fax number you're sending from.

Response

If the arguments passed are valid, it will return the send token (listed as fax ID) that you can then use to keep track of the transmission. If the arguments passed are invalid, we'll return an error object with more information.

List all Received Faxes

Code to retrieve all received faxes:

api_instance = MedsenderAPI::ReceivedFaxesApi.new
opts = {
  from_number: '',
  to_number: '',
  caller_name: '',
  fax_status: '',
  date_start: '',
  date_end: '',
  order_by_date: '',
  is_test: false,
  client: '',
  callback_status: 'success',
  page: 1,
  page_size: 50
}

begin
  result = api_instance.get_received_faxes(opts)
  p result
rescue MedsenderAPI::ApiError => e
  puts "Exception when calling ReceivedFaxesApi->get_received_faxes: #{e}"
end

The above command will return JSON structured like this:

{
  "receivedFaxes": [
    {
      "fromNumber": "+9135758385",
      "toNumber": "+12076077796",
      "sendToken": "887183cc2a5f",
      "callerName": "TEST HOSPITAL",
      "sentAt": "2020-02-18T00:00:00.000Z",
      "completedAt": "2020-02-18T23:59:59.000Z",
      "numPages": 3,
      "isTest": false,
      "faxStatus": "success",
      "callbackStatus": "success",
      "errorDetails": null,
      "client": "42486f1b-9297-401e-a3f4-869ce409c927"
    }
  ],
  "meta": {
    "totalCount": 1,
    "totalPages": 1,
    "perPage": 10,
    "page": 1
  }
}

Returns a list of all faxes you've previously received. By default, the endpoint returns all received faxes with the latest faxes received first. We also allow filtering via query parameters.

Arguments

from_number

The fax number you received the fax from. Can be provided in any phone number format.

to_number

The fax number you received the fax to. Can be provided in any phone number format. Must be a number linked to your developer account.

caller_name

The caller ID associated with the fax number of the sender. Sometimes, this isn't provided by the sender.

fax_status

Only return faxes that were either success or failure.

date_start

Inclusively filter faxes beginning by the date they were received. Must be specified in YYYY-MM-DD format.

date_end

Inclusively filter faxes ending by the date they were received. Must be specified in YYYY-MM-DD format.

order_by_date

Order the results in either asc (ascending) or dsc (descending). Default is descending.

is_test

Filter results based on whether they were test transmission or not. Default is false, only return real transmissions.

client

The client ID to filter for. Will only return faxes belonging to fax numbers linked to this client.

callback_status

The status of the callback sent when receiving a fax. Can be either pending, success, or failed.

page

We paginate our results, with 10 results per page. You can specify which page to view using this parameter.

page_size

The number of results to show per page. Default is 10. Allowed values are 1 to 100, inclusive.

Returns

An array of receivedFaxes which contains ReceivedFax objects. If you have no received faxes, we will return an empty array. If there was an error with the request, we'll return an error object explaining why.

Fax Numbers

The Fax Number Object

Attributes

id

A unique ID used to identify the fax number.

number

The fax number linked to your developer account.

client

An object representing a client linked to this fax number. Contains the client_id and name of the client.

callback_url

The callback URL to be used when sending or receiving from this fax number.

uri

The link to the view this fax number.

Retrieve a fax number

Code to retrieve a fax number:

api_instance = MedsenderAPI::FaxNumberApi.new
fax_number_id = 'your_fax_number_id'

begin
  result = api_instance.get_fax_number_by_id(fax_number_id)
  p result
rescue MedsenderAPI::ApiError => e
  puts "Exception when calling FaxNumberApi->get_fax_number_by_id: #{e}"
end

The above command will return JSON structured like this:

{
  "faxNumber": {
    "id": "4110ad4e-b5a9-438f-a3eb-a81a75c3400b",
    "number": "+12076077796",
    "client": {
      "clientId": "42486f1b-9297-401e-a3f4-869ce409c927",
      "name": "Client clinic"
    },
    "callbackUrl": "https://your.callback.url",
    "uri": "https://api.medsender.com/api/v2/fax_numbers/4110ad4e-b5a9-438f-a3eb-a81a75c3400b"
  }
}

Retrieve a specific fax number linked to your developer account using it's ID.

Arguments

None

Returns

A FaxNumber object. If you have no fax numbers, we will return an empty object. If there was an error with the request, we'll return an error object explaining why.

Retrieve all fax numbers

Code to retrieve all fax numbers:

api_instance = MedsenderAPI::FaxNumberApi.new

begin
  result = api_instance.get_all_fax_numbers
  p result
rescue MedsenderAPI::ApiError => e
  puts "Exception when calling FaxNumberApi->get_all_fax_numbers: #{e}"
end

The above command will return JSON structured like this:

{
  "faxNumbers": [
    {
      "id": "4110ad4e-b5a9-438f-a3eb-a81a75c3400b",
      "number": "+12076077796",
      "client": {
        "clientId": "42486f1b-9297-401e-a3f4-869ce409c927",
        "name": "Client clinic"
      },
      "callbackUrl": "https://your.callback.url",
      "uri": "https://api.medsender.com/api/v2/fax_numbers/4110ad4e-b5a9-438f-a3eb-a81a75c3400b"
    },
    {...},
    {...}
  ]
}

Retrieve all fax numbers linked to your developer account.

Arguments

None

Returns

An array of FaxNumber objects. If you have no fax numbers, we will return an empty array. If there was an error with the request, we'll return an error object explaining why.

Provision a new fax number

Code to provision a fax number:

The above command will return JSON structured like this:

{
  "faxNumber": {
    "id": "4110ad4e-b5a9-438f-a3eb-a81a75c3400b",
    "number": "+12076077796",
    "client": {
      "clientId": "42486f1b-9297-401e-a3f4-869ce409c927",
      "name": "Client clinic"
    },
    "callbackUrl": "https://your.callback.url",
    "uri": "https://api.medsender.com/api/v2/fax_numbers/4110ad4e-b5a9-438f-a3eb-a81a75c3400b"
  }
}

Provision a new fax number. You can provide a client ID to link this fax number to that client. The new number is active as soon as it's created. If you'd like to port an existing number, please fill out the form at https://medsender.com/port/

Arguments

area_code

The desired area code you'd like for the new fax number.

callback_url

The desired callback URL we would use to send/receive faxes from.

client_id

The ID of the client you'd like to associate this fax number to. Optional.

Returns

A FaxNumber object. If there was an error with the request, we'll return an error object explaining why.

Updating the client ID and callback url

Code to update the callback url and/or client id:

api_instance = MedsenderAPI::FaxNumberApi.new
fax_number_id = 'your_fax_number_id'
opts = {
  callback_url: 'https://your.callback.url',
  client_id: 'your_client_id'
}

begin
  result = api_instance.update_callback_url(fax_number_id, opts)
  p result
rescue MedsenderAPI::ApiError => e
  puts "Exception when calling FaxNumberApi->update_callback_url: #{e}"
end

The above command will return JSON structured like this:

{
  "faxNumber": {
    "id": "4110ad4e-b5a9-438f-a3eb-a81a75c3400b",
    "number": "+12076077796",
    "client": {
      "clientId": "42486f1b-9297-401e-a3f4-869ce409c927",
      "name": "Client clinic"
    },
    "callbackUrl": "https://your.callback.url",
    "uri": "https://api.medsender.com/api/v2/fax_numbers/4110ad4e-b5a9-438f-a3eb-a81a75c3400b"
  }
}

Update the callback url and or client ID associated to a specific fax number. Number must be linked to your developer account and client ID must belong to a client that exists and belongs to your developer account.

Arguments

None

Returns

A FaxNumber object containing the updated callback url. If there was an error with the request, we'll return an error object explaining why.

Clients

The Client Object

Attributes

client_id

A unique ID used to identify the client.

name

The name of the client.

fax_numbers

An array of objects. Each object contains a fax number object linked to this client.

Retrieve a client

Code to retrieve a client:

api_instance = MedsenderAPI::ClientsApi.new
client_id = 'your_client_id'

begin
  result = api_instance.get_client_by_id(client_id)
  p result
rescue MedsenderAPI::ApiError => e
  puts "Exception when calling ClientsApi->get_client_by_id: #{e}"
end

The above command will return JSON structured like this:

{
  "client": {
    "clientId": "32b08347-6001-4e16-877b-7228975af105",
    "name": "name_example",
    "faxNumbers": [
      {
        "id": "cc5d524c-dcae-4253-8a40-27dd765ddf47",
        "number": "+12076077796",
        "callbackUrl": "https://your.callback.url",
        "uri": "https://api.medsender.com/api/v2/fax_numbers/cc5d524c-dcae-4253-8a40-27dd765ddf47"
      }
    ]
  }
}

Retrieve a specific client linked to a fax number belonging to your developer account using it's ID.

Arguments

None

Returns

A Client object. If you have no clients, we will return an empty object. If there was an error with the request, we'll return an error object explaining why.

Create a client

Code to create a client:

api_instance = MedsenderAPI::ClientsApi.new
name = 'hospital_client'
opts = {
  fax_number_id: ''
}

begin
  result = api_instance.create_client(name, opts)
  p result
rescue MedsenderAPI::ApiError => e
  puts "Exception when calling ClientsApi->create_client: #{e}"
end

The above command will return JSON structured like this:

{
  "client": {
    "clientId": "32b08347-6001-4e16-877b-7228975af105",
    "name": "name_example",
    "faxNumbers": [
      {
        "id": "cc5d524c-dcae-4253-8a40-27dd765ddf47",
        "number": "+12076077796",
        "callbackUrl": "https://your.callback.url",
        "uri": "https://api.medsender.com/api/v2/fax_numbers/cc5d524c-dcae-4253-8a40-27dd765ddf47"
      }
    ]
  }
}

Create a new client. You can specify a fax number ID to link this client to a fax number.

Arguments

name

The name of the client you'd like to create.

fax_number_id

You can provide a fax number ID to link this client to a fax number upon creation. Optional.

Returns

A Client object. If there was an error with the request, we'll return an error object explaining why.

Retrieve all clients

Code to retrieve all clients:

api_instance = MedsenderAPI::ClientsApi.new

begin
  result = api_instance.get_all_clients
  p result
rescue MedsenderAPI::ApiError => e
  puts "Exception when calling ClientsApi->get_all_clients: #{e}"
end

The above command will return JSON structured like this:

{
  "clients": [
    {
      "clientId": "32b08347-6001-4e16-877b-7228975af105",
      "name": "name_example",
      "faxNumbers": [
        {
          "id": "cc5d524c-dcae-4253-8a40-27dd765ddf47",
          "number": "+12076077796",
          "callbackUrl": "https://medsender.com/bc74913d-2226-4797-83fd-00f410a7f8f0",
          "uri": "http://localhost:5000/api/v2/fax_numbers/cc5d524c-dcae-4253-8a40-27dd765ddf47"
        }
      ],
      [...]
    }
  ],
  [...]
}

Retrieve all clients associated with your developer account.

Arguments

None

Returns

An array of Client objects. If you have no clients, we will return an empty array. If there was an error with the request, we'll return an error object explaining why.

Updating the name of the client

Code to update the client name:

api_instance = MedsenderAPI::ClientsApi.new
client_id = 'your_client_id'
opts = {
  name: 'name_example'
}

begin
  result = api_instance.update_client(client_id, opts)
  p result
rescue MedsenderAPI::ApiError => e
  puts "Exception when calling ClientsApi->update_client: #{e}"
end

The above command will return JSON structured like this:

{
  "client": {
    "clientId": "32b08347-6001-4e16-877b-7228975af105",
    "name": "name_example",
    "faxNumbers": [
      {
        "id": "cc5d524c-dcae-4253-8a40-27dd765ddf47",
        "number": "+12076077796",
        "callbackUrl": "https://your.callback.url",
        "uri": "https://api.medsender.com/api/v2/fax_numbers/cc5d524c-dcae-4253-8a40-27dd765ddf47"
      }
    ]
  }
}

Update the name of the client.

Arguments

None

Returns

A Client object containing the new name. If there was an error with the request, we'll return an error object explaining why.

Medsender AI

Medsender AI allows you to parse healthcare documents and medical records programmatically, without any training needed. Use our AI to categorize, summarize, and extract data from documents to automate routing and data entry. Listed below are entities our AI can extract, but we are continuously adding new entities, so if you do not see one listed, it may already be in development. We are also able to quickly tune our models, so if there's something specific you need extracted, our AI models can be adapted to meet your needs.

We're constantly improving and training our AI for new features so keep on the lookout for new updates! If you have any questions, email us at api@medsender.com.

Run AI on a document

If you have a document that you'd like to run our AI on, simply use this endpoint. We'll return back field extraction and document category, and our AI can also summarize the document for you (feature available upon request). See below for supported entities:

Code to run AI on a file:

api_instance = MedsenderAPI::AIApi.new
file = '/path/to/file.pdf'
callback_url = 'https://your.callback.url'

begin
  result = api_instance.run_ai(file, callback_url)
  p result
rescue MedsenderAPI::ApiError => e
  puts "Exception when calling ClientsApi->run_ai: #{e}"
end

The above command will return JSON structured like this:

{
  "ai_result": {
    "ai_token": "32b08347-6001-4e16-877b-7228975af105",
    "patient_name": "name_example",
    "patient_dob": "01/01/2000",
    "document_classification": "Lab Result",
    "gender": "male",
    "phone_number": "111-222-3333",
    "summary": "Positive covid test result"
  }
}

Arguments

file

The path to the file you'd like to run our AI on. Must be a PDF, TIFF, PNG, or JPG.

callback_url

Response

If the arguments passed are valid, it will return the AI token that you can use to keep track of the AI job. Once the job is completed we will send a callback with the patient name and DOB, and document classification.

Errors

The Medsender API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key or client key isn't right.
403 Forbidden -- You don't have access to that PHI.
404 Not Found -- The specified PHI could not be found.
405 Method Not Allowed -- You tried to access a PHI with an invalid method.
406 Not Acceptable -- You requested a format that isn't supported.
410 Gone -- The PHI requested has been removed from our servers.
429 Too Many Requests -- You've hit the API rate limit.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
ruby shell javascript php java csharp python