# Connections Connections allow for users of your applications to easily share data. They can be created by a user and can extend access to objects from that user to another. For example, we have User A and User B. User A has a patient file that they'd like to share with User B. However, User B doesn't have any inherent access to this file. ![](https://files.readme.io/88a49e7-usera-file.png) Here User A has the highest level of access to their patient file, Delete access (level 7) because they are the owner of the file. However, User B has no access to the file. To grant User B access to the file, User A simply needs to create a connection between the patient file and User B and specify the level of access that should be granted. ![](https://files.readme.io/ac390b7-connection-created.png) Here the connection is created and User A specifies that Read access (level 4) should be granted to User B. Once in place, User B now has access to the patient file and is able to read it.![](https://files.readme.io/7fab039-userb-file.png) Through the connection, User B is able to access the file. However, User A has control over User B's access. If User A no longer wants user B to have access, User A simply has to delete the connection. For all of the access levels, see [Access Control](https://docs.medable.com/reference-link/object-permissions-acl) in the API documentation. ## **Accepting a Connections** Retrieve Connections First find all the connections available to you ``` GET https://api.dev.medable.com/{{your_org_name}}/v2/connections ``` ``` { "_id": "552419f585b784bc204e73aa", "access": 2, "context": { "_id": "5519c01aae2fd2b02915c81f", "object": "c_example", "path": "/c_examples/5519c01aae2fd2b02915c81f" }, "created": "2015-04-07T17:55:01.000Z", "creator": { "_id": "5516ee2634d8d93428169c0e", "object": "account", "path": "/accounts/5516ee2634d8d93428169c0e" }, "expiresAt": "2015-04-14T17:55:01.032Z", "isArchived": false, "object": "connection", "state": 0, "target": { "account": { "_id": "552417e085b784bc204e737c", "object": "account", "path": "/accounts/552417e085b784bc204e737c" }, "name": { "first": "Charles", "last": "Best" } }, "token": "u0xJRTlDQD8moTuUqeQiCAaFzU1WPdtq" } ``` **Accept Connection** Once that token is retrieved, you can accept the connection with a `POST` utilizing the connection token. ``` POST https://api.dev.medable.com/example/v2/connections/u0xJRTlDQD8moTuUqeQiCAaFzU1WPdtq ``` ``` { "_id": "552427adccbc32041380264f", "access": 4, "context": { "_id": "5519c01aae2fd2b02915c81f", "object": "c_example", "path": "/c_examples/5519c01aae2fd2b02915c81f" }, "created": "2015-04-07T18:53:33.000Z", "creator": { "_id": "5516ee2634d8d93428169c0e", "object": "account", "path": "/accounts/5516ee2634d8d93428169c0e" }, "isArchived": false, "object": "connection", "state": 1, "target": { "account": { "_id": "552417e085b784bc204e737c", "object": "account", "path": "/accounts/552417e085b784bc204e737c" }, "email": "charles+best@example.org", "name": { "first": "Charles", "last": "Best" } } } ``` > ### 📘Note > > The state of the connection is now "1" or "Active"Auto-Accept ## Auto Accept Automatically Applying Connections In some scenarios, it may be necessary to create connections without the target needing to accept the connection. This is possible if the following apply: * The context object is not an Account * The context object does not require connection acceptance * The target is already a registered user and the account \_id is used in the target instead of email * `"auto":true` is sent in the connection target To configure your object to not require connection acceptance, when creating your object or editing your object settings, be sure that `Require Connection Accept` is unchecked.![](https://files.readme.io/d4ada1a-connection-settings.png) Optionally you can uncheck `Send Connection Notifications` to prevent notifications from going out when connections are created as well. Automatically applying a connection is then very much like creating a connection like above but with `"auto":true` added to the target.HTTP ``` POST https://api.dev.medable.com/example/v2/c_prescriptions/576967021d0c03a53cd79fd7/connections ``` Request Body ``` { "targets":[ { "object":"account", "_id": "552417e085b784bc204e737c", "access":4, "auto":true } ] } ``` JSON Response ``` { "data": [ { "_id": "576967441d0c03a53cd7a028", "access": 4, "context": { "_id": "576967021d0c03a53cd79fd7", "object": "c_prescription", "path": "/c_prescriptions/576967021d0c03a53cd79fd7" }, "contextSource": null, "created": "2016-06-21T16:11:48.800Z", "creator": { "_id": "575f58281d0c03a53ccc3ac6", "object": "account", "path": "/accounts/575f58281d0c03a53ccc3ac6" }, "expiresAt": "2016-06-28T16:11:48.802Z", "object": "connection", "state": 1, "target": { "account": { "_id": "552417e085b784bc204e737c", "object": "account", "path": "/accounts/552417e085b784bc204e737c" } } } ], "hasMore": false, "object": "list" } ``` > ### 📘Note > > The connection is immediately created in state "1" or "Active" without any acceptance needed. For more details on the connection object, it's properties, and available API routes, see [Apply Connection](https://docs.medable.com/reference-link/apply-connection) ## Creating a Connection To create a connection you need 1. **The context:** An object instance you'd like to share 2. **The targets:** A target user or team of users you'd like to extend access to A connection can have multiple targets, so an array of targets is sent when creating the connection. A target takes the form of:JSON ``` { "object":"account", "email":"fred.banting@example.org", "name":{ "first":"Frederick", "last":"Banting" }, "access":4 } ``` For an individual target if you have only an email address. In cases when you only have the account id, you can also pass in:JSON ``` { "object": "account", "_id": "575f58281d0c03a53ccc3fd3", "access":4 } ``` * When inviting an individual, `object` will always be "account". * Then, either `email` or `_id` of the account must be sent. `email` is useful for inviting individuals when the account \_id is either not known or if the individual does not yet have a user account. If a user with that username exists in the org, the user account will automatically be used. If using `email` you can optionally specify the `name` as illustrated above. This can be useful in connection notification templates. For example, you can send personalized emails with the recipient's name included in the message. * `access` is the level of context access you are granting to the target. Creating a connection is a matter of calling a route with the following pattern:HTTP ``` POST https://api.dev.medable.com/{{your_org_code}}/v2/{{object_name}}/{{object_id}}/connections ``` Where `your_org_code` is the org code you specified when signing up. `object_name` is the plural name of the object you are creating a connection to and `object_id` is the \_id of the object instance that you are creating a connection to. Here's an example on a c\_prescription instance:HTTP ``` POST https://api.dev.medable.com/example/v2/c_prescriptions/576967021d0c03a53cd79fd7/connections ``` Request Body ``` { "targets":[ { "object":"account", "email":"fred.banting@example.org", "name":{ "first":"Frederick", "last":"Banting" }, "access":4 } ] } ``` JSON Response ``` { "data": [ { "_id": "576967441d0c03a53cd7a028", "access": 4, "context": { "_id": "576967021d0c03a53cd79fd7", "object": "c_prescription", "path": "/c_prescriptions/576967021d0c03a53cd79fd7" }, "contextSource": null, "created": "2016-06-21T16:11:48.800Z", "creator": { "_id": "575f58281d0c03a53ccc3ac6", "object": "account", "path": "/accounts/575f58281d0c03a53ccc3ac6" }, "expiresAt": "2016-06-28T16:11:48.802Z", "object": "connection", "state": 0, "target": { "email": "fred.banting@example.org", "name": { "first": "Frederick", "last": "Banting" } } } ], "hasMore": false, "object": "list" } ``` The above created a connection with `fred.banting@example.org` to the `c_prescription` instance with \_id `5519c01aae2fd2b02915c81f`. But notice that the state of the connection is "0" of "Pending". This is because it has not yet been accepted by Mr. Banting. Mr. Banting would then receive an email notification at `fred.banting@example.org` notifying him that John Smith at NewHealthCo would like to share a Prescription file. Once Fred registers as a user, he can then accept or decline the connection. If accepted, Mr. Banting would have Read access to the c\_prescription (level 4). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.medable.com/getting-started/cortex-user-guide/connections.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.