Managing Connections

Sharing data requires setting up a Connection with your partner organization. The “Source Organization” creates the Connection by indicating which “Destination Organization” they would like to share data with, and what types of data they would like to share. The Destination Organization activates the Connection, after which the Source and Destination Organizations are ready to share data.

The Source Organization creates the Connection to the Destination Organization only once. Organizations with multiple data sharing partners will have multiple Connections (one Connection per data sharing partner). Connections are one-directional – data sharing pairs that would like to share data in both directions will use two Connections.

The Source Organization creates the Connection, and the Destination Organization activates it. Destination Organizations cannot create the Connection, and Source Organizations cannot activate it.

Step 1: Create the Connection

The Source Organization can create the Connection via Dashboard or API. The Source Organization uses the Destination Organization’s Organization ID (available in the Destination Organization’s Dashboard under Organization > Information) to create the Connection.

Creating Connections via Dashboard

Source Organizations can use the Dashboard’s Connect > Connections page to create Connections.

Creating Connections via API

Alternatively, Source Organizations can create Connections with the Connect API.

$
curl -X POST https://api.withpersona.com/api/v1/connect/connections \
>
  -H "Authorization: Bearer <token>" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "data": {
>
      "attributes": {
>
        "destination-organization-id": "org_XYZ789"
>
      }
>
    }
>
  }'

1
{
2
  "data": {
3
    "type": "connect/connection",
4
    "id": "cxn_ABC123",
5
    "attributes": {
6
      "status": "pending",
7
      "destination-organization-id": "org_XYZ789",
8
      "source-organization-id": "org_ABC123",
9
      "created-at": "2018-06-01T00:00:00.000Z",
10
      "updated-at": "2018-06-01T00:00:00.000Z"
11
    }
12
  }
13
}

Step 2: Activate the Connection

A newly created Connection starts in Pending status. The Destination Organization activates it from the Dashboard’s Connect > Connections page, moving it to Active. The Connection must be Active for the Source and Destination Organizations to share data — Share Tokens cannot be issued while the Connection is Pending or Inactive.

Deactivation and Reactivation

Either the Source Organization or the Destination Organization can deactivate a Connection from Pending or Active, moving it to Inactive.

Only the Source Organization can reactivate an Inactive Connection. Reactivation returns the Connection to Pending — the Destination Organization must then activate it again to move it back to Active. This ensures the Destination Organization re-consents before data sharing resumes.