OData service

From Resco's Wiki
Jump to navigation Jump to search
Integration with third-party systems

Resco CRM Connector (web APIs):




Resco OData v4 service is a web API that can be used to exchange data between Resco Cloud and other servers. Resco offers many integration options; see Resco CRM Connector to learn about our API interfaces and see Integration for additional options.

Authentication

The service uses standard BASIC authentication with the organization's username and password.

Service document

Lists all entities available.

URI

The service URI depends on server settings; whether the server uses domain organization selection or simple URL organization selection.

  • https://[baseURI]/odata/v4/[organization]/
  • https://[organization].[baseURI]/odata/v4/

URI examples

  • Resco Cloud: https://my_org.rescocrm.com/odata/v4/
  • Resco Cloud US: https://my_org.us1.rescocrm.com/odata/v4/
  • Resco Inspections: https://inspections.resco.net/odata/v4/my_org/

Example

Request: https://inspections.resco.net/odata/v4/[organization]/

(If you're trying this from a web browser, append /?$format=json to display the answer in the correct format.)

Response (shortened):

{
  "@odata.context": "https://inspections.resco.net/odata/v4/[organization]/$metadata",
  "value": [
    {
      "kind": "EntitySet",
      "title": "Account",
      "name": "account",
      "url": "account"
    },
    {
      "kind": "EntitySet",
      "title": "E-Mail Attachment",
      "name": "activitymimeattachment",
      "url": "activitymimeattachment"
    },
    {
      "kind": "EntitySet",
      "title": "Activity Party",
      "name": "activityparty",
      "url": "activityparty"
    },
...

Data request

Request for entity data. The resulting dataset depends on the query applied. Without a query, a single page of entity record results is returned. Default (and max) page size is 1000.

URI

  • https://[baseURI]/odata/v4/[organization]/[EntityName]
  • https://[organization].[baseURI]/odata/v4/[EntityName]

Queries

To see how the queries can be constructed, check the OData protocol.

The service is compliant to OData 4.0 Minimal Conformance Level and partially to OData 4.0 Intermediate Conformance Level.

To see a list of unsupported stuff, check Limitations.

Paging

The data can be paged using $top and $skip query options. Except for that, also server-side paging is applied with a max page size of 1000 items. Whenever the server cuts the response to fulfill server limits, the response contains an [@odata.nextLink](http://docs.oasis-open.org/odata/odata-json-format/v4.0/cs01/odata-json-format-v4.0-cs01.html#_Toc365464689) annotation with a URI that can be used to retrieve the next page of data.

Example

Request: https://inspections.resco.net/odata/v4/[organization]/[entity]

Response (shortened):

{
  "@odata.context": "https://inspections.resco.net/odata/v4/[organization]/$metadata#account",
  "value": [
    {
      "@odata.etag": "W/\"7511A7BAE6FBAB8FF6E67C8DE78EB3CE\"",
      "address1_city": "Suffolk County",
      "address1_country": "USA",
      "address1_latitude": 42.423449,
      "address1_line1": "Charger Street",
      "address1_line2": "124",
      "address1_line3": null,
      "address1_longitude": -71.013693,
      "address1_postalcode": "02151",
      "address1_stateorprovince": "Massachusetts",
      "__createdby_id": null,
      "createdon": "2019-06-18T12:49:34.0000000Z",
      "customertypecode": null,
      "__defaultpricelevelid_id": null,
      "donotemail": false,
      "emailaddress1": "someone@example.com",
      "fax": null,
      "fs_portalpassword": null,
      "id": "585ace18-4eec-4288-9294-1286d768c210",
      "__modifiedby_id": null,
      "modifiedon": "2019-06-18T12:49:34.0000000Z",
      "name": "Warner Apartment Building",
      "__originatingleadid_id": null,
      "__ownerid_id": "601d9d17-89b4-e111-9c9a-00155d0b710a",
      "__owningbusinessunit_id": null,
      "__parentaccountid_id": null,
      "__primarycontactid_id": null,
      "revenue": 8630000,
      "revenue_base": 8630000,
      "statecode": 0,
      "statuscode": 1,
      "telephone1": "738-1946",
      "__transactioncurrencyid_id": "af05b07e-89b4-e111-9c9a-00155d0b710a",
      "vatid": null,
      "versionnumber": 2054,
      "websiteurl": "http://www.example28.com"
    },

Example: filter with expand

Since release 17.0, you can also filter by expand query.

https:/[organization].[baseURI]/odata/v4/annotation?$select=id,subject,filesize,__objectid_id&$expand=objectid_product&$filter=objectid_product/id ne null

Metadata document

Provides a standard OData CSDL model description XML.

URI

  • https://[baseURI]/odata/v4/[organization]/$metadata
  • https://[organization].[baseURI]/odata/v4/$metadata

Example

Request: https://inspections.resco.net/odata/v4/[organization]/$metadata

Response (shortened):

<Edmx Version="4.0">
  <DataServices>
    <Schema Namespace="RescoCrm">
      <EntityType Name="_resco_baseentity_" Abstract="true"/>
      <EntityType Name="account" BaseType="RescoCrm._resco_baseentity_">
        <Key>
          <PropertyRef Name="id"/>
        </Key>
        <Property Name="address1_city" Type="Edm.String" MaxLength="160"/>
        <Property Name="address1_country" Type="Edm.String" MaxLength="160"/>
        <Property Name="address1_latitude" Type="Edm.Double"/>
        <Property Name="address1_line1" Type="Edm.String" MaxLength="500"/>
        <Property Name="address1_line2" Type="Edm.String" MaxLength="500"/>
        <Property Name="address1_line3" Type="Edm.String" MaxLength="500"/>
        <Property Name="address1_longitude" Type="Edm.Double"/>
        <Property Name="address1_postalcode" Type="Edm.String" MaxLength="40"/>
        <Property Name="address1_stateorprovince" Type="Edm.String" MaxLength="100"/>
        <Property Name="createdon" Type="Edm.DateTimeOffset"/>
        <Property Name="customertypecode" Type="Edm.Int32">
          <Annotation Term="RescoCloud.FormattedValue"/>
        </Property>
...

Webhooks

Resco Cloud OData API supports webhooks. A create, update, or delete operation on the server can trigger a callback to a URL of your choosing.

CreateWebhook: /$hook?$entity={entity}&$action={action}

  • entity: entity name
  • action: one of [Create | Update | Delete]
  • POST BODY: { CallbackUrl: "URL to invoke" }
  • RESPONSE HEADER: Location: URL to delete webhook

The BODY of the request to the external URL is in JSON format: '{ "id": "record id" }'

Limitations

  • OData batch processing is not supported
  • JSON response only (XML not supported)