Mock sample for your project: journy.io API docs

Introduction
The journy.io API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
The API is hosted on api.journy.io.
Official SDKs
Our SDKs are designed to help you interact with our APIs with less friction. They are written in several different languages and help bridge the gap between your application and journy.io APIs. They take away the need to know the exact URL and HTTP method to use for each API call among other things leaving you more time to focus on making your application.
| Language | Package | Source code |
|------------|--------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| 💚 Node.js | npm install @journyio/sdk | github.com/journy-io/js-sdk |
| 🐘 PHP | composer require journy-io/sdk | github.com/journy-io/php-sdk |
| 🐍 Python | pip install journyio-sdk | github.com/journy-io/python-sdk |
| 💎 Ruby | Coming soon | Coming soon |
Your favourite programming language not included? Let us know!
In the meanwhile, you can use OpenAPI Generator to generate a client for your programming language.
Authentication
The journy.io API uses API keys to authenticate requests. You can view and manage your API keys in the connections screen.
Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
For every request send to the API we expect a header X-Api-Key to be set with the API Key.
Permissions
When creating an API Key in the application you will have the choice to give permissions to an API Key (which you can change later on). These permissions restrict the API Key from different actions. When an API Key tries to perform a certain action it doesn't have the permissions for, you will receive a 401: Unauthorized response.
Rate limiting
To prevent abuse of the API there is a maximum throughput of 100 requests per minute. If you need a higher throughput, please contact us.
To keep our platform healthy and stable, we'll block API keys that consistently hit our rate limits. Therefore, please consider taking this throughput into account.
In every response the headers X-RateLimit-Limit and X-RateLimit-Remaining will be set. The X-RateLimit-Limit-header will always contain the current limit of requests per minute. The X-RateLimit-Remaining-header will always contain the amount of requests you have left in the current sliding window.
Errors
journy.io uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g. a required parameter was omitted). Codes in the 5xx range indicate an error with journy.io's servers (these are rare).
When performing a POST- or PUT-request with a requestBody, or when including parameters, these parameters and fields will automatically be checked and validated against the API Spec. When any error occurs, you will get a response with an errors-field, structured as follows:
Support
Looking for a specific endpoint? Documentation not clear? We would love to help!

Please see the complete Orbit API documentation at https://docs.orbit.love/reference.

Provides a way for apps to subscribe to certain change events in HubSpot. Once configured, apps will receive event payloads containing details about the changes at a specified target URL. There can only be one target URL for receiving event notifications per app.

This document is intended as a detailed reference for the precise behavior of
the drchrono API. If this is your first time using the API, start with our tutorial. If you are upgrading from a previous version, take a look at the changelog section.
Authorization
Initial authorization
There are three main steps in the OAuth 2.0 authentication workflow:
Redirect the provider to the authorization page.
The provider authorizes your application and is redirected back to
your web application.
Your application exchanges the authorization_code that came with
the redirect for an accesstoken and refreshtoken.
Step 1: Redirect to drchrono
The first step is redirecting your user to drchrono, typically with a button
labeled "Connect to drchrono" or "Login with drchrono". This is just a link that
takes your user to the following URL:
https://drchrono.com/o/authorize/?redirecturi=REDIRECTURIENCODED&responsetype=code&clientid=CLIENTIDENCODED&scope=SCOPESENCODED
REDIRECTURIENCODED is the URL-encoded version of the redirect URI (as registered for your application and used in later steps).
CLIENTIDENCODED is the URL-encoded version of your application's client ID.
SCOPES_ENCODED is a URL-encoded version of a space-separated list of scopes, which can be found in each endpoint or omitted to default to all scopes.
The scope parameter consists of an optional, space-separated list of scopes your application is requesting.
If omitted, all scopes will be requested.
Scopes are of the form BASESCOPE:[read|write] where BASESCOPE is any of user, calendar, patients, patients:summary, billing, clinical and labs.
You should request only the scopes you need.
For instance, an application which sends "Happy Birthday!" emails to a doctor's patients on their birthdays would use the scope parameter "patients:summary:read",
while one that allows patients to schedule appointments online would need at least
"patients:summary:read patients:summary:write calendar:read calendar:write clinical:read clinical:write".
Step 2: Provider authorization
After logging in (if necessary), the provider will be presented with a screen
with your application's name and the list of permissions you requested (via the
scope parameter).
When they click the "Authorize" button, they will be redirected to your redirect
URI with a code query parameter appended, which contains an authorization code to be
used in step 3. If they click the "Cancel" button, they will be redirected to
your redirect URI with error=access_denied instead.
Note: This authorization code expires extremely quickly, so you must perform
step 3 immediately, ideally before rendering the resulting page for the end
user.
Step 3: Token exchange
The code obtained from step 2 is usable exactly once to obtain an access token
and refresh token. Here is an example token exchange in Python:
import datetime, pytz, requests
if 'error' in get_params:
raise ValueError('Error authorizing application: %s' % get_params[error])
response = requests.post('https://drchrono.com/o/token/', data={
'code': get_params['code'],
'granttype': 'authorizationcode',
'redirecturi': 'http://mytestapp.com/redirecturi',
'client_id': 'abcdefg12345',
'client_secret': 'abcdefg12345',
})
response.raiseforstatus()
data = response.json()
Save these in your database associated with the user
accesstoken = data['accesstoken']
refreshtoken = data['refreshtoken']
expirestimestamp = datetime.datetime.now(pytz.utc) + datetime.timedelta(seconds=data['expiresin'])
You now have all you need to make API requests authenticated as that provider.
When using this access token, you'll only be able to access the data that the
user has access to and that you have been granted permissions for.
Refreshing an access token
Access tokens only last 48 hours (given in seconds in the 'expires_in' key in
the token exchange step above), so they occasionally need to be refreshed. It
would be inconvenient to ask the user to re-authorize every time, so instead you
can use the refresh token like the original authorization to obtain a new access
token. Replace the code parameter with refresh_token, change the value
granttype from authorizationcode to refresh_token, and omit the
redirect_uri parameter.
Example in Python:
...
response = requests.post('https://drchrono.com/o/token/', data={
'refreshtoken': getrefresh_token(),
'granttype': 'refreshtoken',
'client_id': 'abcdefg12345',
'client_secret': 'abcdefg12345',
})
...
Webhooks
In order to use drchrono API webhooks, you first need to have an API application on file
(even if it is in Test Model).
Each API webhook is associated with one API application, go to
here to set up both API applications and webhooks!
Once you registered an API application, you will see webhook section in each saved API applications.
Create a webhook and register some events there and save all the changes, then you are good to go!
Webhooks setup
All fields under webhooks section are required.
Callback URL
Callback URl is used to receive all hooks when subscribed events are triggered. This should be an URL under your control.
Secret token
Secret token is used to verify webhooks, this is very important, please set something with high entropy. Also we will
talk more about this later.
Events
Events is used to register events you want to receiver notification when they happen. Currently we support following events.
Event name | Event description
---------- | -----------------
APPOINTMENT_CREATE | We will deliver a hook any time an appointment is created
APPOINTMENT_MODIFY | We will deliver a hook any time an appointment is modified
PATIENT_CREATE | We will deliver a hook any time a patient is created
PATIENT_MODIFY | We will deliver a hook any time a patient is modified
PATIENTPROBLEMCREATE | We will deliver a hook any time a patient problem is created
PATIENTPROBLEMMODIFY | We will deliver a hook any time a patient problem is modified
PATIENTALLERGYCREATE | We will deliver a hook any time a patient allergy is created
PATIENTALLERGYMODIFY | We will deliver a hook any time a patient allergy is modified
PATIENTMEDICATIONCREATE | We will deliver a hook any time a patient medication is created
PATIENTMEDICATIONMODIFY | We will deliver a hook any time a patient medication is modified
CLINICALNOTELOCK | We will deliver a hook any time a clinical note is locked
CLINICALNOTEUNLOCK | We will deliver a hook any time a clinical note is unlocked
TASK_CREATE | We will deliver a hook any time a task is created
TASK_MODIFY | We will deliver a hook any time a task is modified and any time creation, modification and deletion of task notes, associated task item
TASK_DELETE | We will deliver a hook any time a task is deleted
Webhooks verification
In order to make sure the callback URL in webhook is under your control, we added a verification
step before we send any hooks out to you.
Verification can be done by clicking "Verify webhook" button in webhooks setup page. After you click
the button, we will send a GET request to the callback URL, along with a parameter called msg.
Please use your webhook's secret token as hash key and SHA-256 as digest constructor, hash the msg value with
HMAC algorithm.
And we expect a 200 JSON response, in JSON response body, there should be a key called secret_token existing, and its value should be
equal to the hashed msg. Otherwise, verification will fail.
Here is an example webhook verification in Python:
import hashlib, hmac
def webhook_verify(request):
secrettoken = hmac.new(WEBHOOKSECRET_TOKEN, request.GET['msg'], hashlib.sha256).hexdigest()
return json_response({
'secrettoken': secrettoken
})
Note: Verification will be needed when webhook is first created and anytime callback URl is changed.
Webhooks header and body
Header
Key | Value
--- | -----
X-drchrono-event | Event that triggered this hook, could be any one event above or PING
X-drchrono-signature | Secret token associated with this webhook
X-drchrono-delivery | ID of this delivery
Body
Key | Value
--- | -----
receiver | This will be an JSON representation of the webhook
object | This will be an JSON representation of the object related to the triggered event, this would share same serializer as drchrono API
Webhooks ping and deliveries
Webhooks ping and deliveries will be sent as POST requests.
PING:
You can always ping your webhook to check things, by clicking the "Ping webhook" button in webhook setup page. And a hook with header X-drchrono-event: PING would be sent to the callback URL.
Deliveries:
You can check recent deliveries by clicking the "deliveries" link in webhook setup page. And you can resend a hook by clicking "redeliver" button after select a specific delivery.
Webhooks delivery mechanism
We will delivery a hook the moment a subscribed event is triggered. We will not record any response header or body you send back after you receive the hook.
However we only consider the response status code. We will consider any 2xx responses as successfully delivered.
Any other responses, like 302 would be considered failing.
And we will try to redeliver unsuccessfully delivered hooks 3 times, first redeliver happens at 1 hour after the initial event,
second receliver happens 3 hours after the initial event, and the third redeliver happens 7 hours after the initial event.
After these redeliveries, if the delivery is still unsuccessful, you have to redeliver it by hand.
Webhooks security
You may want to secure your webhooks to only consider requests send out from drchrono. And this is where secret_token is needed in
request header.
Try to set the secret_token to something with high entropy, a good example could be taking the output of
ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'.
After this, you might want to verify all request headers you received on your server with this token.
iframe integration
Some API apps provide additional functionality for interacting with patient data
not offered by drchrono, and can benefit by being incorporated into drchrono's
patient information page via iframe. We have created a simple API to make this
possible.
To make an existing API application accessible via an iframe on the patient
page, you need to update either "Patient iframe" or "Clinical note iframe" section in API management page,
to make the iframe to appear on (either the patient page or the clinical note page),
with the URL that the iframe will use for each page, and the height it should
have. The application will be reviewed before it is approved to ensure that it
is functional and secure.
Register a Doctor
iframe applications will appear as choices on the left-hand menu of the patient
page for doctors registered with your application. To register a doctor with
your application, make a POST request to the /api/iframe_integration
endpoint using the access token for the corresponding doctor. This endpoint does not
expect any payload.
To disable your iframe application for a doctor, make a DELETE request to the
same endpoint.
Populating the iframe
There are two places where the iframe can be displayed, either within the
patient detail page or the clinical note page, shown below respectively:
When requesting approval for your iframe app, you must specify a URL for one or
both of these pages which will serve as the base URL for your IFrame
contents. When a doctor views your iframe, the source URL will have various
query parameters appended to it, for example for the patient page the src
parameter of the IFrame will be:
The jwt parameter is crucial if your application transfers any sort of PHI and
does not implement its own login system. It encapsulates the other parameters
in a JSON web token (JWT) and signs them using SHA-256 HMAC
with your client_secret as the key. This verifies that the iframe is being
loaded within one of drchrono's pages by an authorized user. In production, you
should validate the JWT using an approved library (which are listed on the
official site), and only use the parameters extracted from the
JWT. Using Python and Django, this might look like:
import jwt
CLIENT_SECRET =
MAXTIMEDRIFT_SECONDS = 60
def validate_parameters(request):
token = request.GET['jwt']
return jwt.decode(token, CLIENTSECRET, algorithms=['HS256'], leeway=MAXTIMEDRIFTSECONDS)
Modern browsers' same-origin policy means that data cannot be passed between
your application and drchrono's page through the iframe. Therefore, interaction
must happen through the API, using information provided in JWT.
Versions and deprecation
Stability Policy
Changes to this API version will be limited to adding endpoints, or adding fields to existing
endpoints, or adding optional query parameters. Any new fields which are not read-only will be optional.
Deprecation Policy
The drchrono API is versioned. Versions can be in the following states:
Active: This is our latest and greatest version of the API. It is actively supported by
our API team and is improved upon with new features, bug fixes and optimizations that do
not break backwards compatibility.
Deprecated: A deprecated API version is considered second best--having been
surpassed by our active API version. An API version remains in this state for one year,
after which time it falls to the not supported state. A deprecated API version is passively supported;
while it won't be removed until becoming unsupported, it may not receive new features but will likely
be subject to security updates and performance improvements.
Unsupported: An API version in the not supported state may be deactivated at any
time. An application using an unsupported API version should migrate to an active API version.
Version Map
| Version Name | Previous Name | Start Date | Deprecation Date |
|--------------|---------------|------------|------------------|
| v2 | v2015_08 | 08/2015 | TBA |
| v3 | v2016_06 | 06/2016 | |
| v4 | N/A | 09/2018 | |
If you are looking for documentation for an older version
V4(Hunt Valley) (old V4 documentation)
V3(Sunnyvale)
V2(Mountain View)
Changelog
Here's changelog for different versions
V4 Changelog
V3 changelog

SalesLoft helps transform sales teams into modern sales organizations - converting more target accounts into customer accounts

Our API documentation has been moved to https://docs.zenoti.com.