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": "[e-mail]",
  "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

200

{
    "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": "[e-mail]",
                "name": {
                    "first": "John",
                    "last": "Smith"
                }
            }
        }
    ],
    "hasMore": false,
    "object": "list"
}

400

{}

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

200

{
    "_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"
}

400

{}

$.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

200

{
    "_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"
}

400

{}

$.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.

200

$.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": "[e-mail]",
            "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

200

{
    "_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": "[e-mail]",
        "name": {
            "first": "Charles",
            "last": "Best"
        }
    }
}

400

{}

$.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

200

{
    "object": "result",
    "data": true
}

400

{}

$.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

200

{
    "object": "result",
    "data": true
}

400

{}

$.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) {
    // ...
});