Connections

Connection enable access to objects. Once connected, each Object has a number of feeds that can be read and posted to, depending on configured access. Each object property has a minimum required CRUD access level. These are listed in the property table for each object.

Those with Share access to an object can invite others to connect. The level of access you can grant to those you invite depends on the type of object and the level of access you have. We call this the Share Chain.

To disconnect from an object, simply call the Delete route. To remove others from a context, the caller must have Share access to the context for which the connection was created and have more access than the user you are removing. These basic rules apply across all objects.

For more details on using connections, see Using Connections

_id String

The connection identifier

access Number

The access level granted by the connection. In the case of an ownership transfer, the access level is the object’s default owner access. An objects share chain or share ACL defines what access levels can be granted and by whom.

roles ObjectId Array

The instance roles granted by the connection. An objects share ACL defines what roles can be granted and by whom.

context Reference

The connection context. When expanded, imparts the connection’s access level to the caller.

contextSource String

A dot syntax property path context in the invitation context. For example, when the account property of the Patient File is set, the resulting Connection “contextSource” is set to “account”. This enables clients to discern the nature of the Connection. In the case of Patient File, “account” means the target is being asked to act as the patient.

created Date

The date the connection was initiated.

creator Reference

The account id of the connection creator. Expansion paths are fixed at name an image; The caller can only retrieve the connection creator’s name and profile image.

expiresAt Date

For pending connections. the time at which the connection request will expire.

object String

The context’s object name.

state Number

The connection state (Pending: 0, Active: 1).

target Document

The connection target recipient. The email property will only be present if the connection was created using an email address. Conversely, the account property will only be present if the connection was created using an account id. The name property will only be present if the connection creator added one.

account Reference

Optional account identifier. A connection can be created using the account identifier is it is known.

token String

The connection token, only visible to the target.

usesRemaining Number

Defaults to null. The number of times the connection can be loaded before it expires.

"_id": "5524165d65a7158820f4c022",
"access": 4,
"context": {
  "_id": "5519c01aae2fd2b02915c81f",
  "object": "c_example",
  "path": "/c_examples/5519c01aae2fd2b02915c81f"
},
"created": "2015-04-07T17:39:41.000Z",
"creator": {
  "_id": "5516ee2634d8d93428169c0e",
  "object": "account",
  "path": "/accounts/5516ee2634d8d93428169c0e"
},
"expiresAt": "2015-04-14T17:39:41.246Z",
"object": "connection",
"state": 0,
"target": {
  "email": "fred.banting@example.org",
  "name": {
    "first": "Frederick",
    "last": "Banting"
  }

List

GET https://api.dev.medable.com/your_org_name/v2/connections

Path Parameters

Name
Type
Description

your_org_name

string

{
    "data": [
        {
            "_id": "590a1d064966420100589cb3",
            "access": 4,
            "context": {
                "_id": "5784858f46b0104165713b93",
                "object": "c_prescription",
                "path": "/c_prescriptions/5784858f46b0104165713b93"
            },
            "contextSource": null,
            "created": "2017-05-03T18:10:14.812Z",
            "creator": {
                "_id": "5771495a1d0c03a53ce83f1a",
                "object": "account",
                "path": "/accounts/5771495a1d0c03a53ce83f1a"
            },
            "expiresAt": "2017-05-10T18:10:14.813Z",
            "object": "connection",
            "state": 0,
            "target": {
                "email": "john.smith@example.org",
                "name": {
                    "first": "John",
                    "last": "Smith"
                }
            }
        }
    ],
    "hasMore": false,
    "object": "list"
}

State

Meaning

0

Connection has not yet been accepted by invitee

1

Connection has been accepted by invitee

$.ajax({
    url: "https://api.dev.medable.com/example/v2/connections?paths[]=state&paths[]=context",
    method: "GET",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    }
}).done(function(data) {
    // ...
});

Read

GET https://api.dev.medable.com/your_org_name/v2/connections/connection_id

Path Parameters

Name
Type
Description

your_org_name

string

connection_id

string

{
    "_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"
}
$.ajax({
    url: "https://api.dev.medable.com/example/v2/connections/552419f585b784bc204e73aa",
    method: "GET",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    }
}).done(function(data) {
    // ...
});

Read (Token)

GET https://api.dev.medable.com/your_org_name/v2/connections/token

Path Parameters

Name
Type
Description

your_org_name

string

token

string

{
    "_id": "552419f585b784bc204e73aa",
    "access": 2,
    "context": {
        "_id": "5519c01aae2fd2b02915c81f",
        "access": 2,
        "creator": {
            "_id": "5516ee2634d8d93428169c0e",
            "object": "account",
            "path": "/accounts/5516ee2634d8d93428169c0e"
        },
        "favorite": false,
        "object": "c_example",
        "owner": {
            "_id": "5516ee2634d8d93428169c0e",
            "object": "account",
            "path": "/accounts/5516ee2634d8d93428169c0e"
        },
        "shared": true
    },
    "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"
}
$.ajax({
    url: "https://api.dev.medable.com/example/v2/connections/u0xJRTlDQD8moTuUqeQiCAaFzU1WPdtq?expand[]=context",
    method: "GET",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    }
}).done(function(data) {
    // ...
});

Create

POST https://api.dev.medable.com/your_org_name/v2/object_name/object_id/connections

Path Parameters

Name
Type
Description

your_org_name

string

object_name

string

object_id

string

Request Body

Name
Type
Description

targets

object

An array of connection targets. The caller must have connected access any team targets. For teams, a role array will limit the connections to those members having the specified role(s).

_id

string

Connection target account identifier, if known.

email

string

Connection target email

object

string

The target object type

access

integer

The access level to impart to the target on the connection's context.

roles

string

A set of roles to impart to the target on the connection's context.

$.ajax({
    url: "https://api.dev.medable.com/example/v2/c_examples/5519c01aae2fd2b02915c81f/connections",
    method: "POST",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    },
    data: {
    "targets": [
        {
            "object": "account",
            "email": "fred.banting@example.org",
            "access": 4
        }
    ]
}
}).done(function(data) {
    // ...
});

Apply Connection

POST https://api.dev.medable.com/your_org_name/v2/connections/token

Accepting a connecting request

Path Parameters

Name
Type
Description

your_org_name

string

token

string

{
    "_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"
        }
    }
}
$.ajax({
    url: "https://api.dev.medable.com/example/v2/connections/GGrc5KoMMpMsEbDxh2iEsn1dcRmxnNY8",
    method: "POST",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    }
}).done(function(data) {
    // ...
});

Delete

PATCH https://api.dev.medable.com/your_org_name/v2/connections/connection_id

Path Parameters

Name
Type
Description

your_org_name

string

connection_id

string

{
    "object": "result",
    "data": true
}
$.ajax({
    url: "https://api.dev.medable.com/example/v2/connections/5524191c85b784bc204e739f",
    method: "DELETE",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    }
}).done(function(data) {
    // ...
});

Reject Connection

PATCH https://api.dev.medable.com/your_org_name/v2/connections/token

Path Parameters

Name
Type
Description

your_org_name

string

token

string

{
    "object": "result",
    "data": true
}
$.ajax({
    url: "https://api.dev.medable.com/example/v2/connections/u0xJRTlDQD8moTuUqeQiCAaFzU1WPdtq",
    method: "DELETE",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    }
}).done(function(data) {
    // ...
});
PreviousAccountNextNotifications

Last updated