Documentation

Below, you’ll find detailed information about all the features available in Compass. Many of these features are available at multiple element endpoints. Our documentation uses the contact or company endpoints in the examples. A complete list of endpoints and an OpenAPI (Swagger) specification is available.

Authentication

Compass accepts a username and password using basic access authentication to identify and authenticate a Cosential user. Compass also requires an API key and a firm access code. The API key and firm access code are sent as HTTP headers. The API key identifies your integration solution and the firm access code identifies the Cosential client. If you need an API key and/or a sandbox account, please sign up.

Request

    CURL -X GET -u johndoe:P@ssw0rd! \
    -H Content-Type:application/json \
    -H x-compass-firm-id:9999 \
    -H x-compass-api-key:aa94e735-c5f1-4387-af43-c4effe3436e8 \
    https://compass.cosential.com/api/user

Response

   [{
        "Title": null
        "FirstName": "John"
        "MI": null
        "LastName": "Doe"
        "NickName": null
        "FirmName": "Cosential Demo Account"
        "Gender": null
        "UserId": 99999
        "UserToken": "b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd"
    }]

Compass supports searching on almost all primary elements and uses Lucene query language, an easy to learn, highly dynamic, and powerful search syntax. For simple searches, entering a keyword will search all indexed fields.

Simple Search

Simple searches are performed by appending a query string to an http get request.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/contacts/search?q=Austin

Response

   [{
        FirstName: "Austin",
        LastName: "Jones",
        ...
    },{
        FirstName: "John",
        LastName: "Smith",
        BusinessEmailAddress: "jsmith@myaustinemail.co",
        ...
    },{
        FirstName: "Jane",
        LastName: "Doe",
        Addresses: [{
            type: "Business",
            Line1: "123 Anystreet",
            Line2: null,
            City: "Austin",
            State: "TX",
            PostalCode: "78701"
        }],
        ...
    },...]

Searching for Deleted Items

Including deleted items in the search result can be acomplished by passing the includeDeleted parameter with the value of true.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/contacts/search?includeDeleted=true&q=Austin

Response

   [{
        FirstName: "Austin",
        LastName: "Kuykendahl",
        DeleteRecord: true,
        ...
    },{
        FirstName: "George",
        LastName: "Smith",
        DeleteRecord: true,
        BusinessEmailAddress: "gsmith@myaustinemail.co",
        ...
    },...]

Exact Match

To search for a value in a specific property, use the property name followed by a : (colon) followed by the query. To search property data inside complex types use a . (period) as a path delimiter.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/contacts/search?q=Addresses.City:Austin

Response

   [{
        FirstName: "Jane",
        LastName: "Doe",
        Addresses: [{
            type: "Business",
            Line1: "123 Anystreet",
            Line2: null,
            City: "Austin",
            State: "TX",
            PostalCode: "78701"
        }],
        ...
    },{
        FirstName: "John",
        LastName: "Smith",
        Addresses: [{
            type: "Home",
            Line1: "456 Anystreet",
            Line2: null,
            City: "Austin",
            State: "TX",
            PostalCode: "78701"
        }],
        ...
    }]

Phrases

Use " (double quote) to search for a phrase.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/contacts/search?q=CompanyName:"Acme, Inc."

Response

   [{
        FirstName: "Jane",
        LastName: "Doe",
        CompanyName: "Acme, Inc.",
        ...
    },{
        FirstName: "John",
        LastName: "Smith",
        CompanyName: "Acme, Inc.",
        ...
    }]

Wildcards

Standard wildcard characters ? and * are also supported. Use ? to match any single character and * to match 0 or more characters.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/contacts/search?q=CompanyName:"Austin*T?x?s"

Response

   [{
        FirstName: "Jane",
        LastName: "Doe",
        CompanyName: "Austin Imports of Texas",
        ...
    },{
        FirstName: "John",
        LastName: "Smith",
        CompanyName: "Austin Taxes",
        ...
    }]

Fuzzy Match

Fuzzy searching can be performed by using ~ (tilda) at the end of the query string. This can be useful when searching for common phonetic mistakes and typos.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/contacts/search?q=FirstName:Filup~

Response

   [{
        FirstName: "Phillup",
        LastName: "Doe",
        ...
    },{
        FirstName: "Fillup",
        LastName: "Smith",
        ...
    }]

Word Proximity

Word proximity searches also use ~ (tilda). To search for two words within 5 words of each other, append ~ and then 5 to the phase query.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/contacts/search?q=Description:"Austin Texas"~5

Response

   [{
        FirstName: "John",
        LastName: "Doe",
        Description: "He lives in Austin Texas"
        ...
    },{
        FirstName: "Jane",
        LastName: "Smith",
        Description: "She works at Austin Fine Antiques of Texas"
        ...
    }]

Ranges

To search for a range of items, use [] or {} and the TO operator to specify a set of values. Use [] for inclusive ranges, and {} for exclusive ranges.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/contacts/search?q=CreateDate:[2014-01-01 TO 2014-12-31]

Response

   [{
        FirstName: "Jane",
        LastName: "Doe",
        CompanyName: "Acme, Inc.",
        CreateDate: "2014-08-23T13:56:23"
        ...
    },{
        FirstName: "John",
        LastName: "Smith",
        CompanyName: "Acme, Inc.",
        CreateDate: "2014-10-14T19:43:29"
        ...
    }]

Operators

Predicates can be joined using operators AND, OR, and NOT.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/contacts/search?q=CompanyName:Acme AND NOT FirstName:John

Response

   [{
        FirstName: "Jane",
        LastName: "Doe",
        CompanyName: "Acme, Inc.",
        ...
    },{
        FirstName: "Jack",
        LastName: "Smith",
        CompanyName: "Acme, Inc.",
        ...
    }]

POST

Queries can also be sent via POST object.

Request

     curl -X POST \
        https://compass.cosential.com/api/contacts/search \
        -H 'Content-Type: application/json' \
        -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
        -d '{
        "QueryString": "CompanyName:Acme AND NOT FirstName:John",
        "Size": 50,
        "From": 0,
        "Fields": null,
        "IncludeDeleted": false
        }'
    

Response

   [{
        FirstName: "Jane",
        LastName: "Doe",
        CompanyName: "Acme, Inc.",
        ...
    },{
        FirstName: "Jack",
        LastName: "Smith",
        CompanyName: "Acme, Inc.",
        ...
    }]



Find By

In addition to search, Compass offers Find By operators for looking up enitities. These endpoints do not depend on the search engine and can be used for long term integration support.

Project Find By Project Name

findByOperator: values can be ExactMatch, StartsWith, or Contains. The value will default to exact match when not present.
projectName: This is a string representation of the external project name contained in the Unanet CRM.

Request


        curl --location --request GET 'https://compass.cosential.com/api/projects/find-by/project-name?projectName=Facility&findByOperator=contains' \
        --header 'accept: application/json' \
        --header 'Content-Type: application/json' \
        --header 'x-compass-firm-id: 9999' \
        --header 'x-compass-api-key: aa94e735-c5f1-4387-af43-c4effe3436e8' \
        --header 'Authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXXXXX==' \
    

Response


        {
            "Response": [
                {
                    "Id": 4168837
                },
                {
                    "Id": 4168838
                },
                {
                    "Id": 4168863
                }
            ],
            "Success": true,
            "ValidationErrors": []
        }
    

Project Find By Project Number

findByOperator: values can be ExactMatch, StartsWith, or Contains. The value will default to exact match when not present.
projectNumber: This is a string representation of the external project number contained in the Unanet CRM.

Request


        curl --location --request GET 'https://compass.cosential.com/api/projects/find-by/project-number?projectNumber=9903&findByOperator=contains' \
        --header 'accept: application/json' \
        --header 'Content-Type: application/json' \
        --header 'x-compass-firm-id: 9999' \
        --header 'x-compass-api-key: aa94e735-c5f1-4387-af43-c4effe3436e8' \
        --header 'Authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXXXXX==' \
    

Response


        {
            "Response": [
                {
                    "Id": 4168836
                },
                {
                    "Id": 4168837
                },
                {
                    "Id": 4168838
                },
                {
                    "Id": 4168863
                }
            ],
            "Success": true,
            "ValidationErrors": []
        }
    

Create

Sending the entire element schema is not necessary. It is possible to "underpost" data. When creating a new element, default values will be used for properties that are not sent. Data is sent to an element endpoint as a JSON encoded array of objects using an HTTP POST method.

Note: Cosential users can specify whether or not a property is required for an element. It is up to you to enforce this requirement in your solution. To discover if a property is required for the authenticated user, use the Schema Discovery interface.

Primary Objects

Request

    curl -X POST -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    -d '[{
            "CompanyId":12345,
            "FirstName":"John",
            "LastName":"Doe"
        },{
            "CompanyId":12345,
            "FirstName":"Jane",
            "LastName":"Smith"
    }]' https://compass.cosential.com/api/contacts

Response

    [{
        "ContactId":54321,
        "CompanyId":12345,
        "CompanyName":"Acme, Inc",
        "FirstName":"John",
        "MiddleName":null,
        "LastName":"Doe",
        ...
    },{
        "ContactId":54322,
        "CompanyId":12345,
        "CompanyName":"Acme, Inc",
        "FirstName":"Jane",
        "MiddleName":null,
        "LastName":"Smith",
        ...
    }]

Sub Items

Sub items are created in the same manner as primary objects. They are associated to a primary object, so the top level element needs to exist before you can create a subitem. The id of the primary object is used in the URL when creating a sub item.

Request

   curl -X POST -H " x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd" 
    -H "Content-Type: application/json"
    -d '[{
    "AddressType": "Office",
    "DefaultInd": true,
    "Address1": "123 Street Park Way",
    "Address2":"Ste 100",
    "City": "Any Town",
    "PostalCode": "78701",
    "State": "TX",
    "Country": "United States",
    "Phone": "512 555-1212",
    "County": "Travis",
 },
{
    "AddressType": "Home",
    "DefaultInd": true,
    "Address1": "1 Mockingbird Lane",
    "Address2":"PO Box 42",
    "City": "Any Town",
    "PostalCode": "78701",
    "State": "TX",
    "Country": "United States",
    "Phone": "512 555-1212",
    "County": "Travis",
 }
]' ' https://compass.cosential.com/api/contacts/54321/addresses'

Response

[
  {
    "AddressID": 123456,
    "ContactId": 54321,
    "AddressType": "Office",
    "DefaultInd": true,
    "CreateDate": "0001-01-01T00:00:00",
    "Address1": "123 Street Park Way",
    "Address2": "Ste 100",
    "Address3": null,
    "City": "Any Town",
    "PostalCode": "78701",
    "State": "TX",
    "Country": "United States",
    ...
  },
  {
    "AddressID": 123457,
    "ContactId": 54321,
    "AddressType": "Home",
    "DefaultInd": true,
    "CreateDate": "0001-01-01T00:00:00",
    "Address1": "1 Mockingbird Lane",
    "Address2": "PO Box 42",
    "Address3": null,
    "City": "Any Town",
    "PostalCode": "78701",
    "State": "TX",
    "Country": "United States",
    ...
  }
]

Reading data

Compass enables you to get lists of elements as well as a single element by id. Paging data is available for any endpoint returning multiple elements.

Details

Getting details for an element by id is done using an HTTP GET request. Append the element id to the element endpoint.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/contacts/54321

Response

    {
        "ContactId":54321,
        "CompanyId":12345,
        "CompanyName":"Acme, Inc",
        "FirstName":"John",
        "MiddleName":null,
        "LastName":"Doe",
        ...
    }

Lists

Getting a list of all elements can be done with an HTTP GET request to the element endpoint. In general, elements will return a summary version, a subset of common properties. To have list endpoints return full elements instead of the summary version, use the FULL parameter.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/contacts?full=true

Response

    [{
        "ContactId":54321,
        "CompanyId":12345,
        "CompanyName":"Acme, Inc",
        "FirstName":"John",
        "MiddleName":null,
        "LastName":"Doe",
        ...
    },{
        "ContactId":54322,
        "CompanyId":12345,
        "CompanyName":"Acme, Inc",
        "FirstName":"Jane",
        "MiddleName":null,
        "LastName":"Smith",
        ...
    }]

Associations

Endpoints exist for getting lists of related data. See Element Endpoints for a complete list of endpoints. For example, to return all contacts for a given company the endpoint /companies/<id>/contacts is used. More information about element associations can be found in Schema Discovery.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/companies/12345/contacts

Response

    [{
        "ContactId":54321,
        "CompanyId":12345,
        "CompanyName":"Acme, Inc",
        "FirstName":"John",
        "MiddleName":null,
        "LastName":"Doe",
        ...
    },{
        "ContactId":54322,
        "CompanyId":12345,
        "CompanyName":"Acme, Inc",
        "FirstName":"Jane",
        "MiddleName":null,
        "LastName":"Smith",
        ...
    }]

Paging

Any endpoint returning multiple elements such as search results or lists can be paged. Paging is accomplished using the SIZE and FROM parameters. SIZE specifies the number of elements you would like to receive. SIZE has a maximum value of 500. FROM specifies the number of elements you would like to skip. SIZE has a default value of 50 and FROM has a default value of 0. As such, if paging parameters are not used, the API will return the first 50 elements.

Example

If there are 754 records to pull, 2 API calls would be needed to return all the records. The first call would use parameter values of SIZE = 500 and FROM = 0. If the number of records is unknown then the second call would use SIZE = 500 and FROM = 501 to fetch the remaining 254 records. If the number of records is actually known in advance, then parameter values of SIZE = 254 and FROM = 501 could be used. If the number of records is not known in advance, then subsequent calls to the API should be made until the number of returned records is less than 500.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/contacts?size=2&from=10

Response

    [{
        "ContactId":54321,
        "CompanyId":12345,
        "CompanyName":"Acme, Inc",
        "FirstName":"John",
        "MiddleName":null,
        "LastName":"Doe",
        ...
    },{
        "ContactId":54322,
        "CompanyId":12345,
        "CompanyName":"Acme, Inc",
        "FirstName":"Jane",
        "MiddleName":null,
        "LastName":"Smith",
        ...
    }]

Update

Updates are done by sending a JSON encoded element using an HTTP PUT method to the element endpoint with the id of the element appended. It is possible to "underpost". Values for missing element properties will not be updated.

Primary Objects

Request

    curl -X PUT -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    -d '{
            "CompanyId":12345,
            "FirstName":"John",
            "LastName":"Smith"
        }' https://compass.cosential.com/api/contacts/54321

Response

   {
        "ContactId":54321,
        "CompanyId":12345,
        "CompanyName":"Acme, Inc",
        "FirstName":"John",
        "MiddleName":null,
        "LastName":"Smith",
        ...
    }

Sub Items

Subitems can be updated by addressing them in the URL. Values for missing element properties will not be updated.

Request

    curl -X PUT -H Content-Type:application/json 
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd 
    -d '{
            "Address1":"2 Mockingbird Way",
        }' https://compass.cosential.com/api/contacts/54321/addresses/123456

Response

 {
    "AddressID": 123456,
    "ContactId": 54321,
    "AddressType": "Office",
    "DefaultInd": true,
    "CreateDate": "0001-01-01T00:00:00",
    "Address1": "2 Mockingbird Way",
    "Address2": "Ste 100",
    "Address3": null,
    "City": "Any Town",
    "PostalCode": "78701",
    "State": "TX",
    "Country": "United States",
    ...
  }

Delete

To delete an element, issue an HTTP DELETE request to the element endpoint with the id of the element appended.

Primary Objects

Request

    curl -X DELETE -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/contacts/54321

Response

   {
        success: true,    
        message: "Contact 54321 has been deleted."
    }

Sub Items

Subitems can be deleted by adding the subitem name to the end of a primary objects url and then adding the unique id of the subitem.

Note: Not all subitems can be deleted. To discover if a subitem can be removed, use the Schema Discovery interface to check if an object is Read Only and can be removed.

Request

    curl -X DELETE -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/contacts/54321/addresses/123456

Response

   {
        success: true,    
        message: "Address 123456 has been deleted."
    }

It is also possible to delete all subitems on an object be leaving the unique id off of the URL.

Request

    curl -X DELETE -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/contacts/54321/addresses

Response

   {
        success: true,    
        message: "All addressed have been deleted."
    }

Change Detection

An HTTP GET to an entity's /changes endpoint will give you an array of all entity record change events. The change event properties are:

  • Deleted - Indicates if the change was a delete
  • Id - The primary id for the entity that was changed
  • Version - Version key useful in detecting changes over time
Requests to the /changes endpoints can take an optional includeDeleted parameter to include delete change events. Delete change events are not included by default. Requests to the /changes endpoints can take an optional reverse parameter to get results in reverse order.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/personnel/changes?includeDeleted=true&reverse=true

Response

   [{
    "Deleted": false,
    "Id": 12345,
    "Version": "AAAAABbE/Rc="
  },
  {
    "Deleted": true,
    "Id": 12346,
    "Version": "AAAAABbE/Rg="
   },...]

Using the Entity Version Key to Query for Changes

You can query the API for just the changes that have occurred after a specific change event by using the change event's version key. Change event results are always ordered chronologically, so the last change event in the result set is always the last change that has occurred. It's possible to detect changes that have occurred since a previous call by storing the last change event's version key, and then using that version key at a later time in an API query. The query will return only change events that have occurred since your last query.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/personnel/changes?version=AAAAABbE%2FRg%3D&includeDeleted=true&reverse=true

Response

   [{
    "Deleted": false,
    "Id": 12347,
    "Version": "AAAAABbE/Rk="
  },
  {
    "Deleted": false,
    "Id": 12345,
    "Version": "AAAAABbE/Ro="
  },...]

Email

Email Attachments

Writing Attachments

Email attachments in compass works very similar to the way it does in Project Images. Email attachments are created with two or more API calls. The first call is to create one or more email attachment objects using the endpoint /api/emails/<emailId>/attachments with an HTTP POST request. Once the attachment object is created you can use the endpoint /api/emails/<emailId>/attachmentfile/<attachmentId> to read/write the attachment data.

    
        curl -X POST \
        https://compass.cosential.com/api/emails/37/attachments \
        -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
        -H 'Content-Type: application/json' \
        -d '[{
        "FileName": "testDoc.doc"
        }]'
    

Response


    [
        {
        "Id": 58,
        "FileName": "testDoc.doc",
        "DeleteRecord": false,
        "AttachmentEndpoint": "/api/emails/37/attachmentfile/58"
        }
    ]
    

The FileName object in this object will specify the file extension and filename that is received when reading from the attachmentfile endpoint

With the attachment objects created we can now send file data using an HTTP POST or HTTP PUT call to the AttachmentEndpoint found in the object

Sending a HTTP POST or HTTP PUT request to an attachment with file data will overwrite that data

There are four different ways to upload file data

  • Specify a url parameter in the query string
  • Specify the Content-Type header of application/json to send the data as a base64 encoded string in a JSON object
  • Specify the file data using Multipart form data

Example request using a URL parameter

    
        curl -X POST \
        'https://compass.cosential.com/api/emails/37/attachmentfile/58?url=https://www.someurl.org/test.doc' \
        -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    

Example request sending a JSON object with base64 encoded data

    
        curl -X POST \
        https://compass.cosential.com/api/emails/37/attachmentfile/58 \
        -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
        -H 'Content-Type: application/json' \
        -d '{
        "Data": "VGhpcyBpcyBhIHRlc3QgdG8gc2VlIGlmIGJhc2U2NCB3b3Jrcw=="
        }'
    

Example request using multipart form data

    
        curl -X POST \
        https://compass.cosential.com/api/emails/37/attachmentfile/58 \
        -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
        -H 'Content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
        -F '= C:\Users\user\documents\testDoc.doc'
    

Reading Attachments

Attachments are read using the same endpoint with a HTTP GET request

Attachments can be read in two different formats

  • Binary Data
  • Specify the HTTP Accept Header as application/json to get the data as a JSON object in base64 encoded

Example request for binary data

    
        curl -X GET \
        https://compass.cosential.com/api/emails/37/attachmentfile/58 \
        -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    

Example request for JSON object with base64

    
        curl -X GET \
        https://compass.cosential.com/api/emails/37/attachmentfile/58 \
        -H 'Accept: application/json' \
        -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    

Example Response


    {
        "Data": "VGhpcyBpcyBhIHRlc3QgdG8gc2VlIGlmIGJhc2U2NCB3b3Jrcw=="
    }
    

Deleting Attachments

Deleting attachments can be done by deleting the attachment object through the endpoint /api/emails/<emailId>/attachmentfile/<attachmentId> with an HTTP DELETE request

Example request to delete attachment

    
        curl -X DELETE \
        https://compass.cosential.com/api/emails/37/attachments/58 \
        -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd
    

Goals

Compass provides a read only access to Revenue Projection data from the Goals module.

Data

Get a specific record of revenue data for an opportunity using an HTTP GET request by appending the revenue id after /revenue in the route, which still must include an opportunity id. Note that for us to return the item, the value must be greater than $0, otherwise you will receive a return of null with a 200 OK status.

Request


        curl -X GET -H Content-Type:application/json \
        -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
        https://compass.cosential.com/api/goals/opportunities/5555666/revenue/888
    

Response


        {
            "RevenueId": 888,
            "OpportunityId": 5555666,
            "Year": 2021,
            "Month": 12,
            "Value": 11,
            "ROW_VERSION": "AAAAAL9QIgw="
        }
    

Lists

Getting a list of revenue projection data for an opportunity can be done using HTTP GET request to the element endpoint. Resource URI should contain an opportunity id. Note that the response would only include a revenue if the value is > $0.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/goals/opportunities/5555666/revenue

Response


        [
            {
                "RevenueId": 888,
                "OpportunityId": 5555666,
                "Year": 2021,
                "Month": 12,
                "Value": 11,
                "ROW_VERSION": "AAAAAL9QIgw="
            },
            {
                "RevenueId": 777,
                "OpportunityId": 5555666,
                "Year": 2021,
                "Month": 9,
                "Value": 4444,
                "ROW_VERSION": "AAAAAL9QIgY="
            }
        ]
    

Changes

Getting a list of opportunity change events can be done using HTTP GET request to the /changes endpoint. ParentId indicates the associated opportunity. Use parameter version to filter the results. Note that the parameter includeDeleted is not currently supported for goals.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/goals/opportunities/revenue/changes

Response


        [
            {
                "Deleted": false,
                "Id": 888,
                "Version": "AAAAAL9QIeg=",
                "ParentId": 5555666
            },
            {
                "Deleted": false,
                "Id": 444,
                "Version": "AAAAAL9QIek=",
                "ParentId": 3333222
                },
            {
                "Deleted": false,
                "Id": 666,
                "Version": "AAAAAL9QIeo=",
                "ParentId": 8888999
            }
        ]
    

Notes

Fiscal Year Settings are not currently supported by Compass.

Schema Discovery

Property metadata is available using an HTTP GET request appending /schema to the element endpoint. The schema endpoints will return user level field customizations such as required, enabled, custom labels, etc.

The IsIncludedInResponse property indicates if something is available in the main call payload or if an additional API call is needed to get the data.

Objects

The ObjectEndpoint property is the API endpoint where the data for the property can be retrieved. The SchemaEndpoint property is the API endpoint where the schema of the property can be retrieved.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    https://compass.cosential.com/api/companies/schema

Response

   [{
            PropertyName: "CompanyId"
            Group: "Internal"
            Label: "Company Id"
            Description: "CompanyId"
            Enabled: true
            ReadOnly: true
            Required: false
            DefaultValue: null
            DataType: "Integer"
            MaxLength: null
            UnicodeSupported: true
            Searchable: true
            ArrayType: null
            IsPrimaryKey: true
            IsExternalId: false
            ObjectEndpoint: null
            IsIncludedInResponse: true
            SchemaEndpoint: null
    },{
            PropertyName: "Contacts"
            Group: "Contacts"
            Label: "Contacts"
            Description: ""
            Enabled: true
            ReadOnly: false
            Required: false
            DefaultValue: null
            DataType: "Array"
            MaxLength: null
            UnicodeSupported: false
            Searchable: false
            ArrayType: "ValueList"
            IsPrimaryKey: false
            IsExternalId: false
            ObjectEndpoint: "api/contacts"
            IsIncludedInResponse: null
            SchemaEndpoint: "api/contacts/schema"
            IsHidden: false
    },...]

User Customizations

Users with administrative access to Cosential can customize element properties to enforce their own data constraints and improve the user experience. Users can customize the following:

  • Labels
  • Required (yes/no)
  • Enabled (yes/no)
  • Default Values
  • Max Length
  • Group
The schema interface should be used to discover these customizations.

Discovering Associations

The schema interface can be used to discover associations between elements. If a property has a DataType of Array or Object, then associated elements can be accessed using the endpoint for the element, the id for the element, and the property name <endpoint>/<id>/<propertyname>. Using the results above, we can infer an HTTP GET request to /api/companies/12345/contacts will list all contacts associated to the company with an id of 12345.

Because the ObjectEndpoint value for the property Contacts is api/contacts we can:

  • Create using an HTTP POST request to api/contacts
  • List using an HTTP GET request to api/contacts
  • Read using an HTTP GET request to api/contacts/<id>
  • Update using an HTTP PUT request to api/contacts/<id>
  • Delete using an HTTP PUT request to api/contacts/<id>
  • Search using an HTTP GET request to api/contacts/search?q=myquery
  • Get schema metadata with an HTTP GET request to api/contacts/schema

Endpoints

The following top level endpoints are currently available in the API. The list below is available by making an HTTP GET request to api/entities. Click on an endpoint to view properties for the element.

Element Endpoint Search Schema
Company api/companies api/companies/search api/companies/schema
Contact api/contacts api/contacts/search api/contacts/schema
Project api/projects api/projects/search api/projects/schema
Opportunity api/opportunities api/opportunities/search api/opportunities/schema
Personnel api/personnel api/personnel/search api/personnel/schema
CallLog api/calllogs api/calllogs/search api/calllogs/schema
Currency api/currency api/currency/schema
Lead api/leads api/leads/search api/leads/schema
FirmOrg api/firmorgs api/firmorgs/schema
Email api/Emails api/Emails/search api/Emails/schema