# Partner API

The GQ Partner API (aka. GQ API) allows authorized partner applications (SPs) to obtain limited access to shared customer data on GetQuorum's (GQ) platform.

# OAuth Authentication

In order to interact with the GQ API, you or your application must authenticate via OAuth. SPs must first register with GQ in order to obtain a client_id and client_secret that must then be provided in the Authentication flow.

# Authentication Flow

1. Customers are redirected from the SP to GQ to obtain permission for the SP to access the customer's data
2. Customers are redirected back to the SP site with an authorization code; the SP makes an API call to GQ to exchange the access code for access and refresh tokens
3. The SP accesses the GQ API with the access token

# 1. Request Customer's permission from GQ

Redirect customer to the OAuth endpoint on GQ's platform:

https://auth.getquorum.com/login/oauth/authorize
  ?client_id=<client_id>
  &redirect_uri=<redirect_ui>
  &response_type=code
  &scope=read

Parameters:

• client_id: Your application's client ID obtained on registration
• redirect_uri: The callback URL in your application where customers are sent after authorization. Must be in the list of URLs provided to GQ during registration. On a successful code grant, the customer will be redirected to your redirect_uri with the authorization code in the query parameter.

https://your_redirect_uri.com/?code=<AUTHORIZATION_CODE>

# 2. Exchange the code for an access token

Send a POST request to the GQ authorization endpoint with the authorization code in the request body:

POST https://api.getquorum.com/papi/v1/oauth/token
{
  "client_id": "<your_client_id>",
  "client_secret": "<your_client_secret>",
  "code": "<AUTHORIZATION_CODE>"
}

Parameters:

• client_id: Your application's client ID obtained on registration
• client_secret: Your application's client secret obtained on registration
• code: The authorization code retrived from Step 1. If the request is accepted, you will receive a response with the access and refresh tokens:

200 OK
{
  "access_token": "<ACCESS_TOKEN>",
  "scope": "meetings:read",
  "token_type": "bearer",
  "refresh_token": "<REFRESH_TOKEN>"
}

# 3. Use the access token to call GQ protected resources

The access token allows you to make requests to the GQ API on behalf of the customer. All requests made to the API must have the access token in an Authorization header as a Bearer token.

Authorization: Bearer <ACCESS_TOKEN>

# 4. Use the refresh token to obtain a new access token

When an access token expires, a new access token can be obtained with the refresh token.

POST https://api.getquorum.com/papi/v1/oauth/token?grant_type=refresh
{
  "client_id": "<your_client_id>",
  "client_secret": "<your_client_secret>",
  "refresh_token": "<REFRESH_TOKEN>"
}

200 OK
{
  "access_token": "<ACCESS_TOKEN>",
  "scope": "meetings:read",
  "token_type": "bearer",
  "refresh_token": "<REFRESH_TOKEN>"
}

# GQ API Endpoints

All GQ endpoints are served over https.

The base URL for API requests is:

https://api.getquorum.com/papi/v1/

# Authorization

All requests must include an Authorization header with an access token as a bearer token. The access token can be obtained by following the OAuth Authentication Flow described above.

Authorization: Bearer <ACCESS_TOKEN>

# List voting campaigns

Returns a list of campaigns that SP has authorization to access on behalf of the customer.

GET /campaigns

Response Body:

[
  {
    "key": "58a0ff38-5eea-41c9-a7c3-af54968c2476",
    "name": "TSCC 1234 - AGM 2018",
    "description": "For the Election of Directors",
    "meetingDate": "2018-02-12T22:25:41.440Z",
    "location": "Party Room at 10 River Street, Toronto",
    "status": "active",
    "dashboardUrl": "https://url.to.campaign.dashboard"
  }
]

Description:

# Get a Campaign's Details

Returns a specific campaign's details along with high-level stats on its performance.

GET /campaigns/:key

Response Body:

{
  "key": "58a0ff38-5eea-41c9-a7c3-af54968c2476",
  "name": "TSCC 1234 - AGM 2018",
  "description": "For the Election of Directors",
  "meetingDate": "2018-02-12T22:25:41.440Z",
  "location": "Party Room at 10 River Street, Toronto",
  "status": "active",
  "dashboardUrl": "https://url.to.campaign.dashboard",
  "stats": {
    "votesSubmitted": 201,
    "maxVoters": 342,
    "attendingCount": 45,
    "cachedAt": "2019-09-12T01:47:28.186Z"
  }
}

Description: