Site resource

Get site list

OVERVIEW

This is the latest version of this API endpoint valid from Collaborate 4.3 and above, for older versions please see the child pages of this page

This method returns the list of sites a user has access to in Collaborate. 

Please note that a site which has one of the configuration options enabled as specified in the "callfrom" parameter will not serve the documents using the API, as the configuration settings such as DRM, password protection etc cannot be bypassed using the API at the moment. Until we provide API endpoints that allow you to accept these settings using the API, there is no way to get documents from these sites, doing so will conflict with the Collaborate security policies and hence cannot be achieved using the API at this time. 

URL : /api/<version>/sites?

Query string parameters
 

Parameter Name Value Description

filterby

 

 String

Possible values are {recent|favourite|category|all} Default for this field is “recent”

By default any filter will send back the first 20 sites if pagination is false
categoryid Int

This parameter is used to get the site list based on the site category ID, please provide site categoryid in addition to setting the filterby property to category. 

example = /api/1/sites?filterby=category&categoryid=1 
returncount Int The no of sites returned. Default is 20. This option does not apply if filterBy property is set to all
status String

A site status available in the system

{active|archived|readonly|preparation}

Default -> {active + readonly + preparation}

for filterBy={recent|favourite| category}]

if filterBy={all}  is set then all status become applicable.
Includefolderpermission Boolean

{true|false}

the default is false
name String

This parameter is used to search a site by name. The site is included in the search result if the string appears in the title of the site.  (The results are returned in ascending order)

example: Retrieve sites having "HighQ" word in their name: /api/1/sites?name='HighQ'

This will return all sites having "HighQ" in their site name. 

 
callFrom String

The only valid value is HIGHQDRIVE. If set the site list filters out any sites that have any restrictions on them. The conditions are as under. 

           1. 'Visible on HighQ Drive or Office Plugin' check box is not selected in Site->Admin->Advanced page.
            2. Password protected site
            3. 2FA enable site
            4. Terms & conditions applied on the site
            5. IP Restricted sites
            6. Document workflow enabled site
            7. Check-in / check out enabled site
            8. DRM enabled site
            9. Files module is disabled

example: exclude restricted site as: /api/1/sites?callFrom=HIGHQDRIVE

 

For an Internal Admin the response XML is as below:

<?xml version="1.0" encoding="UTF-8"?>
<sites>
    a list of site objects
</sites>

 

For a non-admin response, XML will be as per below :

<?xml version="1.0" encoding="UTF-8"?>
<sites>
    <site>
        <id>3</id>
        <sitename>My site</sitename>
        <sitedescription />
        <sitefolderID>16</sitefolderID>
        <category>
            <name>None</name>
        </category>
        <status>Active</status>
    </site>
</sites>

 

Error Codes: 

 

Code Meaning
400 Problem with parsing XML or JSON object (Bad Request)
401 Unauthorised
403 Validation failed/ Forbidden
405 Method not allowed (calling API with the wrong method)
500 Internal error occurred

 

Comments


6 Comments


Mark Salamon 'owns' is perhaps misleading here... I'll change to 'has access to'. But yes, A system admin user has access to all sites in an instance, so this call will return everything!


The documentation says: "This method returns the list of sites a user owns in Collaborate. " But at least for a system admin calling this, it appears to return all sites that match. Is that correct?


Hello! Is there any chance to get a site list filtered by a site object property (for example, 'matterno')?


Thanks again Andrew Quinn. The fact that you mentioned the swagger documentation will be greatly useful to me. I have requested that it be enable for my instance. Greatly appreciate all your help!

Hi Shawn Rupert, it definitely looks as though there is a disparity between this endpoint and what the documentation describes, and you should include this in the bug report (ticket) you raised.

There are four additional parameters that don't seem to be listed in the documentation here but are in the swagger documentation. I've included a screenshot of the endpoint in question (it's a little small as I'm currently on a laptop screen, but just about readable).

The four additional parameters are:

  • orderby - asc or desc
  • ordertype - owner, siteStartDate, matterNumber, siteName, clientNo, statusDisplayName, siteExpiryDate, lastUpdateDate, lastAccessedDate
  • offset - The starting position of the site list from when the site list should be returned. This is to allow pagination
  • limit - The no of items to return in an individual get call

What's not apparent is that by default (as you stated) filterby=all is returning 20 records/page. Setting 'offset' to zero (0), and not providing a limit seems to disable pagination, thus all your matching sites are returned, e.g.

https://example.highq.com/example/api/1/sites?filterby=all&name=test&status=active%2Carchived%2Creadonly%2Cpreparation&offset=0

One thing to note is that this from a 5.1.4.1 instance, so perhaps these additional parameters have been introduced recently.

Hope this helps,

Andrew

Get site list-comments-image-1


1. Where is the pagination parameter mentioned in the filterby description?

2. How do I return all sites when using the name parameter? I am only getting 20 when using ?filterby=all&name=text. I also tried returncount=0 (which returned 0). returncount=10000 worked but that should not be the way it works.

Last Updated: Nov 08,2024