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 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 \
    http://compass.uat.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 \
    http://compass.uat.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 \
    http://compass.uat.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 \
    http://compass.uat.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 \
    http://compass.uat.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 \
    http://compass.uat.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 \
    http://compass.uat.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 \
    http://compass.uat.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 \
    http://compass.uat.cosential.com/api/contacts/search?q=CreateDate:[20140101 TO 20141231]

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 \
    http://compass.uat.cosential.com/api/contacts/search?q=CompanyName:Acme AND NOT FirstName:John

Response

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

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"
    }]' http://compass.uat.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",
 }
]' ' http://compass.uat.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 \
    http://compass.uat.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 \
    http://compass.uat.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 \
    http://compass.uat.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. FROM specifies the number of elements you would like 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.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    http://compass.uat.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"
        }' http://compass.uat.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",
        }' http://compass.uat.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 \
    http://compass.uat.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 \
    http://compass.uat.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 \
    http://compass.uat.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.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    http://compass.uat.cosential.com/api/personnel/changes?includeDeleted=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 \
    http://compass.uat.cosential.com/api/personnel/changes?version=AAAAABbE%2FRg%3D&includeDeleted=true

Response

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

Schema Discovery

Property metadata is available using an HTTP GET request appending /schema to the element endpoint. A complete list of endpoints is available.

Request

    curl -X GET -H Content-Type:application/json \
    -H x-compass-token:b3d83cd6-9cd2-4f2a-a3e5-911e94025ecd \
    http://compass.uat.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
    },{
            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"
            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