API Access

Consultation Manager has an open API allowing customers to build their own integrations to automatically add data to the database or pull data out into other applications or data warehouses.

Common integrations might be with products such as Customer Relationship Management systems, GIS systems and Document Management systems.

Our API documentation explains how you access your API along with how to query the database to perform different actions.

To find your specific API documentation, you need to replace the <tenant> portion of the URL below with your actual Consultation Manager tenant.

The API URL will take you to your Consultation Manager Rest API Page.

Australia & New Zealand

https://<tenant>.api.consultationmanager-preview.com/redoc

US & Canada

https://<tenant>.api.consultationmanager.com/redoc

Authentication

A valid User in CM is required for any API request.

The User permission for API access parallels the User permissions required for the various tasks in CM. Your API access User will need to have the correct access otherwise you will return an error if you attempt a task that your User does not have permission to carry out.

Australia & New Zealand

OAuth2 client_id:

  • consultationmanager:australia-east:<tenant>:consultationmanager-preview-com:ropc
Grant type: password
Token URL: https://auth.mysite.com.au/connect/token
Scope:
  • openid - 

    Open Id (required)

  • profile - 

    Retrieve user profile (required)

  • mysite.consultationmanager.api - 

    Request API access (required)

    US 

    OAuth2 client_id:

    • consultationmanager:west-us-2:<tenant>:consultationmanager-com:ropc
    Grant type: password
      Token URL: https://auth.consultationmanager.com/connect/token
       
      Scope:
      • openid - 

        Open Id (required)

      • profile - 

        Retrieve user profile (required)

      • mysite.consultationmanager.api - 

        Request API access (required)

      Canada

      OAuth2 client_id:

      • consultationmanager:canada-central:<tenant>:consultationmanager-ca:ropc
      Grant type: password
      Token URL: https://auth.consultationmanager.ca/connect/token
      Scope:
      • openid - 

        Open Id (required)

      • profile - 

        Retrieve user profile (required)

      • mysite.consultationmanager.api - 

        Request API access (required)

      Query for Token

      You will need to construct a POST request to the below URL.

      Australia & New Zealand

      Posthttps://auth.mysite-preview.com.au/connect/token

      US & Canada

      Post: https://auth.mysite.com/connect/token

      Required Headers:

      Content-Type = application/x-www-form-urlencoded

      Body:

      grant_type: 'password'
      client_id: <OAuth2 client_id from above>
      scope: openid profile mysite.consultationmanager.api
      username: <your Username for CM>
      password: <your Password for CM>

      Entities

      • Wherever an ID is being provided it will be either the ID of an Entity (Project, Stakeholder, etc…) or the ID of a Classification Value.

      • To get more information about a field, look up the Entity Definition.

      • From there you can figure out the type of the field and infer the expected input format.

      • Notable Types:

        • datetime

          • format: YYYY-MM-DDThh:mm:ss.fffffff

          • This is in UTC.

        • classification

          • format: integer

          • This is the id of the classification value.

          • Can get the range of values from: classifications/<classificationId>/children

        • classificationgroup

          • format:

          •         "classificationGroup": {
                        "assign": [2],
                        "unassign": []
                    }
          • The IDs in the arrays are the ID of the classification value.

          • Can get the range of values from: classifications/<classificationId>/children.

          • The ‘assign’ will add to the list on the entity, ‘unassign’ will remove from the list.

      Full example

      {
          "data": {
              "Id": 1,
              "DatabaseId": "8fd5bd5d-6f1d-4999-b6c7-fdef51293bd5",
              "Visibility": 2,
              "Deleted": false,
              "Created": "2020-02-04T20:29:16.9077372",
              "CreatedBy": {
                  "Enabled": true,
                  "IdentityType": "user",
                  "Identifier": 9223372036854775807,
                  "DisplayName": "Special user"
              },
              "ModifiedBy": {
                  "Enabled": true,
                  "IdentityType": "user",
                  "Identifier": 9223372036854775807,
                  "DisplayName": "Special user"
              },
              "propertyNumber": "unde",
              "propertyName": "",
              "reference": "porro",
              "address": {
                  "address": "",
                  "autoGeocode": false,
                  "country": "AUSTRALIA",
                  "dateGeocoded": "2017-04-03T12:47:00",
                  "geoLocation": {
                      "latitude": -27.5387462,
                      "longitude": 153.013372
                  },
                  "location": {
                      "latitude": -27.5387462,
                      "longitude": 153.013372,
                      "type": "Point",
                      "value": "POINT (153.013372 -27.5387462)"
                  },
                  "postCode": "",
                  "state": "",
                  "suburb": ""
              },
              "propertyGroups": [],
              "distributionLists": [],
              "descriptor": "",
              "relatedProjects": [
                  {
                      "id": 3,
                      "value": "Ivy"
                  }
              ],
              "Modified": "2023-06-27T03:22:57.4631601",
              "ModifiedEndTime": "9999-12-31T23:59:59.9999999",
              "relatedStakeholder": [
                  {
                      "id": 6,
                      "value": "Jack"
                  }
              ],
              "classificationGroup": {
                  "assign": [2],
                  "unassign": []
              }
          }
      }

      Definitions

      URL: definition/entity/<alias>

      URL Example: definition/entity/stakeholder

       

      Stakeholder

       

      Create

      URL: entities/stakeholder

      Request:

      POST
      {
          "ProjectOperations": {
              "Relate": [556]
          },
          "Values": {
              "Visibility": 2,
              "title": "Master",
              "firstName": "Test",
              "lastName": "John",
              "suffix": "Test",
              "salutation": "Test",
              "role": "Test",
              "organisation": "Test",
              "bhPhone": "1",
              "ahPhone": "1",
              "mobile": "1",
              "fax": "1",
              "email": "Test",
              "webaddress": "Test",
              "notes": "Test",
              "address.address": "Test",
              "address.country": "Test",
              "address.postCode": "2307",
              "address.state": "Test",
              "address.suburb": "Test",
              "stakeholderGroups": {
                  "assign": [1597],
                  "unassign": []
              },
              "distributionLists": {
                  "assign": [791],
                  "unassign": []
              },
              "privacyOption": 12
          }
      }

       

      Event

      Create

      URL: entities/event

      Request:

      POST
      {
          "ProjectOperations": {
              "Relate": [556]
          },
          "Values": {
              "startDate": "2021-08-19T09:48:16",
              "endDate": "2021-08-19T09:48:16",
              "name": "Test",
              "location": "Test",
              "address.suburb": "Test",
              "address.address": "Test",
              "address.country": "Test",
              "address.state": "Test",
              "address.postCode": "Test",
              "issues": {
                  "assign": [4037],
                  "unassign": []
              },
              "eventSentimentType": 1421,
              "eventType": 324,
              "comments": "Test",
              "summary": "Test",
              "teamResponse": "Test"
              // Note: These would be set through the Relationships
              // "relatedStakeholder": {
              //     "assign": [137168],
              //     "unassign": []
              // },
              // "relatedProperty": {
              //     "assign": [23815],
              //     "unassign": []
              // },
              // "relatedProjects": {
              //     "assign": [555],
              //     "unassign": []
              // }
              // "relatedUser": {
              //     "assign": [1946],
              //     "unassign": []
              // }
          }
      }

       

      Documents

      Get the Document ID

      URL: entities/document/<id>

      URL Example: entities/document/10

      Request:

      GET

      Response:

      {
          "data": {
              "Id": 1,
              "name": "Hello I am a document and you should upload me please",
              "fileName": "Hello I am a document and you should upload me.docx",
              "attachment": {
                  "associatedInstanceId": 1,
                  "contentType": "Attachment",
                  "deleted": false,
                  "identifier": "5f9783c36400492894dcb11dd8363d90",
                  "name": "Hello I am a document and you should upload me.docx",
                  "size": 0,
                  "storageUri": "REDACTED"
              },
              "documentFolders": [],
              "DatabaseId": "c740b2cb-0187-4621-91d2-0aaa9108298f",
              "Visibility": 1,
              "Deleted": false,
              "Created": "2019-05-27T23:10:34.7261652",
              "CreatedBy": {
                  "Enabled": true,
                  "IdentityType": "user",
                  "Identifier": 9223372036854775807,
                  "DisplayName": "Special user"
              },
              "ModifiedBy": {
                  "Enabled": true,
                  "IdentityType": "user",
                  "Identifier": 97,
                  "DisplayName": "Zorba CW"
              },
              "Modified": "2020-02-17T10:57:15.8721779",
              "ModifiedEndTime": "9999-12-31T23:59:59.9999999",
              "attachmenttwo": null,
              "description": null,
              "relatedProjects": [
                  {
                      "id": 1,
                      "value": "New Farm Playground"
                  },
                  {
                      "id": 6,
                      "value": "TEST 001"
                  }
              ],
              "descriptor": "Hello I am a document and you should upload me please"
          }
      }

      Get the Document Download URI

      To get a link to the actual document, you will need the following information from the Document Entity (see above):

      • Content Type

        • Full Path: data.attachment.contentType

      • Identifier

        • Full Path: data.attachment.identifier

      Then you can grab the ‘uri’ from the response below and download the entire file.

      URL: storage/request/download/<Content Type>/<Identifier>

      URL Example: storage/request/download/Attachment/5f9783c36400492894dcb11dd8363d90

      Request:

      GET

      Response:

      {
          "fileName": "Hello I am a document and you should upload me.docx",
          "uri": "https://REDACTED"
      }

      Upload a Document

      Get Upload Token

      URL: storage/request/upload/attachment/<filename>/<file size in bytes>

      URL Example: storage/request/upload/attachment/Brookvale-Emoji.jpg/201249

      Request:

      GET

      Response

      {
          "directory": "attachments_staging",
          "resourceIdentifier": "362916c94baa41d587f47c295f7599b6",
          "shareName": "rmsootest",
          "token": "?sv=2018-03-28&sig=ZrB4mBNtn56jWjhLCQImYAxSB%2BUreg%2FphcvlZv%2BI77E%3D&st=2021-08-21T02%3A13%3A46Z&se=2021-08-21T04%3A28%3A46Z&srt=sco&ss=f&sp=cw",
          "uri": "https://cmpreviewauseast.file.core.windows.net/"
      }

      Upload a Document

      In order to Upload a document you have to send two PUT requests. They are based on a URL constructed from the information retrieved from the Upload Token Response.

      URL: uri + sharename + / + directory + / + resourceIdentifier + token

      PUT #1

      • Empty Body.

      • Headers:

        • Content-Length: 0

        • x-ms-type: file

        • x-ms-content-length: <file size in bytes>

      PUT #2

      • Add an extra query parameter:

        • comp=range

      • Body is the binary file.

      • Headers:

        • Content-Length: <file size in bytes>

        • x-ms-write: update

        • Range: bytes=0-<file size in bytes - 1>

      Create Document Entity

      URL: storage/request/upload/attachment/<filename>/<file size in bytes>

      URL Example: storage/request/upload/attachment/Brookvale-Emoji.jpg/201249

      Request:

      POST
      {
          "ProjectOperations": {
              "Relate": [556]
          },
          "Values": {
              "name": "John Test",
              "description": "Test Update from John",
              "fileName": "JohnTest.jpg",
              "attachment": {
                  "ContentType": 1,
                  "Value": "<resourceIdentifier from Upload Token Response>",
                  "FileName": "JohnTest.jpg"
              },
              "documentFolders": {
                  "assign": [1790],
                  "unassign": []
              }
          }
      }

      Relationships

      Stakeholder / Event

      Create

      URL: relationships/ser

      Request:

      POST
      {
          "Values": {
              // This is the Stakeholder Id
              "LeftHandId": 137168,
              // This is the Event Id
              "RightHandId": 229226
          }
      }

      Event / Document

      Create

      URL: relationships/EventDocument

      Request:

      POST
      {
          "Values": {
              // This is the Event Id
              "LeftHandId": 229226,
              // This is the Document Id
              "RightHandId": 59131
          }
      }

      Search

      URL: search

      Request:

      POST
      {
          "ambientProjects": [1,2,3,4,5,6,7],
          "dsl": "[document: deleted = false && created > '2021-01-01T01:02:03']",
          "page": 1,
          "pageSize": 1000
      }