The DocuSign REST API provides you with a powerful, convenient, and simple Web services API for interacting with DocuSign.

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: 1. Redirect the provider to the authorization page. 2. The provider authorizes your application and is redirected back to your web application. 3. Your application exchanges the `authorization_code` that came with the redirect for an `access_token` and `refresh_token`. ### 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/?redirect_uri=REDIRECT_URI_ENCODED&response_type=code&client_id=CLIENT_ID_ENCODED&scope=SCOPES_ENCODED - `REDIRECT_URI_ENCODED` is the URL-encoded version of the redirect URI (as registered for your application and used in later steps). - `CLIENT_ID_ENCODED` 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 `BASE_SCOPE:[read|write]` where `BASE_SCOPE` 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'], 'grant_type': 'authorization_code', 'redirect_uri': 'http://mytestapp.com/redirect_uri', 'client_id': 'abcdefg12345', 'client_secret': 'abcdefg12345', }) response.raise_for_status() data = response.json() # Save these in your database associated with the user access_token = data['access_token'] refresh_token = data['refresh_token'] expires_timestamp = datetime.datetime.now(pytz.utc) + datetime.timedelta(seconds=data['expires_in']) 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 `grant_type` from `authorization_code` to `refresh_token`, and omit the `redirect_uri` parameter. Example in Python: ... response = requests.post('https://drchrono.com/o/token/', data={ 'refresh_token': get_refresh_token(), 'grant_type': 'refresh_token', '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 `PATIENT_PROBLEM_CREATE` | We will deliver a hook any time a patient problem is created `PATIENT_PROBLEM_MODIFY` | We will deliver a hook any time a patient problem is modified `PATIENT_ALLERGY_CREATE` | We will deliver a hook any time a patient allergy is created `PATIENT_ALLERGY_MODIFY` | We will deliver a hook any time a patient allergy is modified `PATIENT_MEDICATION_CREATE` | We will deliver a hook any time a patient medication is created `PATIENT_MEDICATION_MODIFY` | We will deliver a hook any time a patient medication is modified `CLINICAL_NOTE_LOCK` | We will deliver a hook any time a clinical note is locked `CLINICAL_NOTE_UNLOCK` | 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): secret_token = hmac.new(WEBHOOK_SECRET_TOKEN, request.GET['msg'], hashlib.sha256).hexdigest() return json_response({ 'secret_token': secret_token })

## 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: ``` ?doctor_id=&patient_id=&practice_id=&iat=&jwt= ``` 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)](http://jwt.io) 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](http://jwt.io)), and only use the parameters extracted from the JWT. Using Python and Django, this might look like: import jwt CLIENT_SECRET = MAX_TIME_DRIFT_SECONDS = 60 def validate_parameters(request): token = request.GET['jwt'] return jwt.decode(token, CLIENT_SECRET, algorithms=['HS256'], leeway=MAX_TIME_DRIFT_SECONDS) 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)](/api-docs-old/v4/documentation) (old V4 documentation) - [V3(Sunnyvale)](/api-docs-old/v3/documentation) - [V2(Mountain View)](/api-docs-old/v2/documentation) # Changelog Here's changelog for different versions - [V4 Changelog](/api-docs-old/v4/changelog) - [V3 changelog](/api-docs-old/v3/changelog)

dropX.io API provides programmatic access to the e-commerce intelligence data.

The Browse API has the following resources: item_summary: Lets shoppers search for specific items by keyword, GTIN, category, charity, product, or item aspects and refine the results by using filters, such as aspects, compatibility, and fields values.  (Experimental) search_by_image: Lets shoppers search for specific items by image. You can refine the results by using URI parameters and filters. item: Lets you retrieve the details of a specific item or all the items in an item group, which is an item with variations such as color and size and check if a product is compatible with the specified item, such as if a specific car is compatible with a specific part. Provides a bridge between the eBay legacy APIs, such as Finding, and the RESTful APIs, which use different formats for the item IDs.  (Experimental) shopping_cart: Provides the ability for eBay members to see the contents of their eBay cart, and add, remove, and change the quantity of items in their eBay cart.   Note: This resource is not available in the eBay API Explorer. The item_summary, search_by_image, and item resource calls require an Application access token. The shopping_cart resource calls require a User access token.

Note: This is a (Limited Release) API available only to select developers approved by business units.

This API allows third-party developers to search for and retrieve details about eBay deals and events, as well as the items associated with those deals and events.

Note: This is a (Limited Release) API available only to select developers approved by business units. For information on how to obtain access to this API in production, see the Buy APIs Requirements.

The Feed API provides the ability to download TSV_GZIP feed files containing eBay items and an hourly snapshot file of the items that have changed within an hour for a specific category, date and marketplace.

In addition to the API, there is an open source Feed SDK written in Java that downloads, combines files into a single file when needed, and unzips the entire feed file. It also lets you specify field filters to curate the items in the file.

The Marketing API retrieves eBay products based on a metric, such as Best Selling, as well as products that were also bought and also viewed.

The Catalog API allows users to search for and locate an eBay catalog product that is a direct match for the product that they wish to sell. Listing against an eBay catalog product helps insure that all listings (based off of that catalog product) have complete and accurate information. In addition to helping to create high-quality listings, another benefit to the seller of using catalog information to create listings is that much of the details of the listing will be prefilled, including the listing title, the listing description, the item specifics, and a stock image for the product (if available). Sellers will not have to enter item specifics themselves, and the overall listing process is a lot faster and easier.

The Charity API allows third-party developers to search for and access details on supported charitable organizations.

Use the Taxonomy API to discover the most appropriate eBay categories under which sellers can offer inventory items for sale, and the most likely categories under which buyers can browse or search for items to purchase. In addition, the Taxonomy API provides metadata about the required and recommended category aspects to include in listings, and also has two operations to retrieve parts compatibility information.

This API allows 3rd party developers to translate item title, description, search query.

The Analytics API retrieves call-limit data and the quotas that are set for the RESTful APIs and the legacy Trading API.

Responses from calls made to getRateLimits and getUerRateLimits include a list of the applicable resources and the "call limit", or quota, that is set for each resource. In addition to quota information, the response also includes the number of remaining calls available before the limit is reached, the time remaining before the quota resets, and the length of the "time window" to which the quota applies.

The getRateLimits and getUserRateLimits methods retrieve call-limit information for either an application or user, respectively, and each method must be called with an appropriate OAuth token. That is, getRateLimites requires an access token generated with a client credentials grant and getUserRateLimites requires an access token generated with an authorization code grant. For more information, see OAuth tokens.

Users can analyze the response data to see whether or not a limit might be reached, and from that determine if any action needs to be taken (such as programmatically throttling their request rate). For more on call limits, see Compatible Application Check.

The Account API gives sellers the ability to configure their eBay seller accounts, including the seller's policies (eBay business policies and seller-defined custom policies), opt in and out of eBay seller programs, configure sales tax tables, and get account information.

For details on the availability of the methods in this API, see Account API requirements and restrictions.

The Analytics API provides data and information about a seller and their eBay business.

The resources and methods in this API let sellers review information on their listing performance, metrics on their customer service performance, and details on their eBay seller performance rating.

The three resources in the Analytics API provide the following data and information:

• Customer Service Metric – Returns data on a seller's customer service performance as compared to other seller's in the same peer group.
• Traffic Report – Returns data that shows how buyers are engaging with a seller's listings.
• Seller Standards Profile – Returns data pertaining to a seller's performance rating.

Sellers can use the data and information returned by the various Analytics API methods to determine where they can make improvements to increase sales and how they might improve their seller status as viewed by eBay buyers.

For details on using this API, see Analyzing seller performance.

Service for providing information to sellers about their listings being non-compliant, or at risk for becoming non-compliant, against eBay listing policies.

The Feed API lets sellers upload input files, download reports and files including their status, filter reports using URI parameters, and retrieve customer service metrics task details.

Use the Fulfillment API to complete the process of packaging, addressing, handling, and shipping each order on behalf of the seller, in accordance with the payment method and timing specified at checkout.

Note: This is a (Limited Release) API available only to select developers approved by business units.

Enables a seller adding an ad or item on a Partner's site to automatically create an eBay listing draft using the item details from the Partner's site.

Note: This is a (Limited Release) API available only to select developers approved by business units.

The Logistics API resources offer the following capabilities:

• shipping_quote – Consolidates into a list a set of live shipping rates, or quotes, from which you can select a rate to ship a package.
• shipment – Creates a "shipment" for the selected shipping rate.

Call createShippingQuote to get a list of live shipping rates. The rates returned are all valid for a specific time window and all quoted prices are at eBay-negotiated rates.

Select one of the live rates and using its associated rateId, create a "shipment" for the package by calling createFromShippingQuote. Creating a shipment completes an agreement, and the cost of the base service and any added shipping options are summed into the returned totalShippingCost value. This action also generates a shipping label that you can use to ship the package. The total cost of the shipment is incurred when the package is shipped using the supplied shipping label.

Important! Sellers must set up a payment method via their eBay account before they can use the methods in this API to create a shipment and the associated shipping label.

The Marketing API offers two platforms that sellers can use to promote and advertise their products:

• Promoted Listings is an eBay ad service that lets sellers set up ad campaigns for the products they want to promote. eBay displays the ads in search results and in other marketing modules as SPONSORED listings. If an item in a Promoted Listings campaign sells, the seller is assessed a Promoted Listings fee, which is a seller-specified percentage applied to the sales price. For complete details, refer to the Promoted Listings playbook.
• Promotions Manager gives sellers a way to offer discounts on specific items as a way to attract buyers to their inventory. Sellers can set up discounts (such as "20% off" and other types of offers) on specific items or on an entire customer order. To further attract buyers, eBay prominently displays promotion teasers throughout buyer flows. For complete details, see Promotions Manager.

Marketing reports, on both the Promoted Listings and Promotions Manager platforms, give sellers information that shows the effectiveness of their marketing strategies. The data gives sellers the ability to review and fine tune their marketing efforts.

Important! Sellers must have an active eBay Store subscription, and they must accept the Terms and Conditions before they can make requests to these APIs in the Production environment. There are also site-specific listings requirements and restrictions associated with these marketing tools, as listed in the "requirements and restrictions" sections for Promoted Listings and Promotions Manager.

The table below lists all the Marketing API calls grouped by resource.