Create a 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:

{
    "object":"account",
    "email":"[email protected]",
    "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:

{
    "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:

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:

POST https://api.dev.medable.com/example/v2/c_prescriptions/576967021d0c03a53cd79fd7/connections

{
   "targets":[
      {
         "object":"account",
         "email":"[email protected]",
         "name":{
            "first":"Frederick",
            "last":"Banting"
         },
         "access":4
      }
   ]
}

{
    "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": "[email protected]",
                "name": {
                    "first": "Frederick",
                    "last": "Banting"
                }
            }
        }
    ],
    "hasMore": false,
    "object": "list"
}

The above created a connection with [email protected] 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 [email protected] 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).