OData- A Primer

What we support

Currently only OData queries on Get statements are supported at the moment, but not ALL of them. Anything that gets more than 1 element (Get contacts by groupID for instance) will accept an OData query. The features we support are a mix of Filter, Sort and OrderBy and Paging

(anything not listed here can be assumed to be unsupported)

• Activities:
  • GET api/activities - Get all activities available for the current API user - Filter, OrderBy, Paging, and Select|Expand
  • GET api/contacts/{contactID}/activities - Get a list of activities that the given contact is associated with and available for the current API user - Filter, OrderBy, Paging, and Select|Expand
  • GET api/activityseries - Get all series currently in the system matching an (optional) odata filter - Filter, OrderBy
• Calendar:
  • GET api/calendar - Get calendar schedule for the current user matching an (optional) OData query
  • GET api/calendar?$select=total,date&$expand=items($select=duration,starttime,endtime,recordtype,id) - get current day to end of month.
  • GET api/calendar?$filter=items/any(a: a/startTime ge 2018-10-01T08:00:00-07:00 and a/startTime le 2018-10-31T17:00:00-07:00)&$select=total,date&$expand=items($select=duration,starttime,endtime,recordtype,id)
• Companies:
  • GET api/companies - Get all companies available for the current API user - Filter, OrderBy, Paging, and Select|Expand
• Contacts:
  • GET api/contacts/{contactID}/companies - Filter, OrderBy, Paging, and Select|Expand
  • GET api/contacts/{contactID}/groups - Filter, OrderBy, Paging, and Select|Expand
  • GET api/contacts?groupID={groupID} - Filter, OrderBy, Paging, and Select|Expand
  • Get api/contacts - Filter, OrderBy, Paging, and Select|Expand
• Groups:
  • GET api/groups - Get all groups currently available for the current API user - Filter, OrderBy, Paging, and Select|Expand
  • GET api/groups/{id}/contacts - Get all the contacts that are a member of a given group - Filter, OrderBy, Paging, and Select|Expand
• History:
  • GET api/history - GetAll - Filter, OrderBy, Paging, and Select|Expand
• Note:
  • GET By Contact api/contacts/{contactid}/note - Gets all notes by contact currently available for the current API user - Filter, OrderBy, Paging, and Select|Expand
• Opportunities:
  • GET api/opportunities - Get all opportunities currently available for the current API user - Filter, OrderBy, Paging, and Select|Expand
  • GET Contacts api/opportunities/{id}/companies - Get all companies associated with an opportunity currently available for the current API user - Filter, OrderBy, Paging, and Select|Expand
  • GET Contacts api/opportunities/{id}/contacts - Get all contacts associated with an opportunity currently available for the current API user - Filter, OrderBy, Paging, and Select|Expand
  • GET Groups api/opportunities/{id}/groups - Get all groups associated with an opportunity currently available for the current API user - Filter, OrderBy, Paging, and Select|Expand
  • GET Groups api/opportunities/{id}/products - Get all products associated with an opportunity currently available for the current API user - Filter, OrderBy, Paging, and Select|Expand
• Products:
  • GET api/products/{productID} - Gets all products currently available for the current API user - Filter, OrderBy, Paging, and Select|Expand

Custom Entities

All OData features are supported with custom entities.

• Act! supported Queries:
  • GET api/custom/entities/{entityname} - Get all rows for the custom entity.
  • GET api/custom/entities/{entityname}?$filter=({field} eq '{value}') - Get all rows for the custom entity where it is equal to a string.
  • GET api/custom/entities/{entityname}?$filter=contains({field}, '{value}') - Get all rows that contain a particular value.
• We support filtering on collections (companies, contacts, groups, and opportunities):
  • GET api/custom/entities/{entityname}?$filter=contacts/any(c:c/FullName eq 'admin') - Get all rows where a contact is assigned to the custom entity.

>

Batching

Batching is a web API feature that allows a consumer to pack several API requests and send them to the web API opportunityService in one HTTP request and receive a single HTTP response with the response to all their requests.

POST api/$batch : multipart/mixed

• The primary subtype for multipart, "mixed", is intended for use when the body parts are independent and intended to be displayed serially. Any multipart subtypes that an implementation does not recognize should be treated as being of subtype "mixed".

• • POST https://localhost/act.web.api/api/$batch HTTP/1.1

    Content-Type: multipart/mixed; boundary="dd4b18a3-1821-95b2-111c-142286cb9533"

    Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdnIiOiIobG9jYWwpIiw...

    Act-Database-Name: ACT2016Demo

    Host: localhost

     

    --dd4b18a3-1821-95b2-111c-142286cb9533

    Content-Type: application/http; msgtype=request

     

    POST /act.web.api/api/contacts HTTP/1.1

    Host: localhost

    Content-Type: application/json

     

    {"fullName": "Joe Smith" }

     

    --dd4b18a3-1821-95b2-111c-142286cb9533

    Content-Type: application/http; msgtype=request

     

    POST /act.web.api/api/contacts HTTP/1.1

    Host: localhost

    Content-Type: application/json

     

    {"fullName": "Susan Mint" }

     

    --dd4b18a3-1821-95b2-111c-142286cb9533

    Content-Type: application/http; msgtype=request

     

    POST /act.web.api/api/companies HTTP/1.1

    Host: localhost

    Content-Type: application/json

     

    {"name": "Swiftpage" }

     

    --dd4b18a3-1821-95b2-111c-142286cb9533--

Definitions

(Anything that is not implemented will throw an exception upon use.)

the $ symbol denotes an OData operation.

• $top - The maximum number of items returned in each page.
• $skip - The number of rows to skip in the result set before returning results.
• $filter - restrict the result set based on Query criteria
  • Comparison Operators:
    • eq - Equal to
    • ne - Not equal to
    • lt - Less than
    • le - Less than or equal to
    • gt - Greater than
    • ge - Greater than or equal to
  • Concatenation Operators:
    • and
    • or
  • Functions:
    • contains(ColumnName, 'ColumnValue')
    • startswith(ColumnName, 'ColumnValue')
    • endswith(ColumnName, 'ColumnValue')
• $orderby - Specifies the order of the result set

Samples

(Note: you may need to URL Encode these strings depending on how you are making the calls. For example, replace all spaces with %20 and so on.)

• Order By:
  • http://localhost/act.web.api/api/groups/{id}/contacts?$orderby=name
• Filter:
  • GET:/api/contacts/?$filter=(Company eq 'Pool Supplies Inc.' and FirstName eq 'John') or (Company eq 'Pool Supplies Co.' and FirstName eq 'Joe')
  • GET:/api/contacts/?$filter=(FirstName eq 'Chilly' or FirstName eq 'Willy' or FirstName eq 'Leonardo') and (LastName eq 'Willy' or LastName eq 'Wonka')
  • GET:/api/contacts/?$filter=(created gt 2016-02-26T14:07:12Z)&$orderby=created desc
  • GET:/api/contacts/?$filter=(created ge 2016-03-01T08:00:00Z and created le 2016-03-31T23:59:59Z)
• Functions:
  • GET:/api/contacts?$filter=lastname eq 'Gates' or startswith(lastname, 'c')
  • GET:/api/contacts?$filter=lastname eq 'Gates' or endswith(lastname, 'n')
  • GET:/api/contacts?$filter=lastname eq 'Gates' or contains(fullname, 'mark')
  • GET:/api/contacts?$filter=businessAddress/State eq 'CA' or startswith(lastname, 'c')
  • GET:/api/contacts?$filter=startswith(lastname, 'c') or startswith(lastname, 'b') or startswith(lastname, 'p')
• Paging:
  • GET:/api/activityseries/?$skip=10&$top=5
• Select|Expand:
  • GET:/api/companies?$select=phone,name,id
  • GET:/api/companies?$select=phone,name,id&$expand=address($select=city,postalCode)
  • GET:/api/companies/{id}/contacts?$expand=businessAddress($select=city,state)&$select=company,fullname,id
  • GET:/api/companies?$select=phone,name,id&$expand=address&$top=4&$skip=0&$orderby=name
  • GET:/api/companies?$select=phone,name,id&$expand=address&$top=4&$skip=0&$orderby=name desc
  • GET:/api/opportunities?$select=name,id&$expand=stage($expand=process($select=name,id);$select=name,id)
  • GET:/api/opportunities?$select=name,id&$expand=stage($expand=process($select=name,id);$select=name,id)&$top=5&$skip=0&$orderby=name desc
• Combination:
  • GET:/api/activityseries/?$skip=10&$top=5&$filter=(Company eq 'Pool Supplies Inc.' and FirstName eq 'John')