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
passwordhttps://auth.mysite.com.au/connect/tokenopenid-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
passwordhttps://auth.consultationmanager.com/connect/tokenopenid-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
passwordhttps://auth.consultationmanager.ca/connect/tokenopenid-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
Post: https://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
}