OCS Recipient API

Introduction

The OCS Recipient API is a new OCS endpoint that is used by the share dialog autocomplete process, when you pick a user or group to share to.

The base URL for all calls to the share API is: <owncloud_base_url>/ocs/v1.php/apps/files_sharing/api/v1/sharees?format=json&itemType=file

Get Shares Recipients

Get all share recipients for the provided search term.

  • Syntax: /sharees

  • Method: GET

Query Attributes

Attribute Type Description Required Default

format

string

The response format. Can be either xml or json

xml

search

string

The search string

itemType

string

The type which is shared.

Yes

Can be either file or folder

shareType

integer

Any one of:

- 0 (user)

- 1 (group)

- 6 (remote)

page

integer

The page number in the results to be returned

1

perPage

integer

The number of items per page

Yes

200

Status Codes

Code Description

100

Successful

400

Failure due to invalid query parameters

Example Request Response Payloads

If the users admin, user1, user2 and the groups group1 and group2 were registered on a server.

{    
	"ocs": {
        "data": {
            "exact": {
                "groups": [],
                "remotes": [],
                "users": [
                    {
                        "label": "admin",
                        "value": {
                            "shareType": 0,
                            "shareWith": "admin"
                        }
                    }
                ]
            },
            "groups": [
                {
                    "label": "group1",
                    "value": {
                        "shareType": 1,
                        "shareWith": "group1"
                    }
                },
                {
                    "label": "group2",
                    "value": {
                        "shareType": 1,
                        "shareWith": "group2"
                    }
                }
            ],
            "remotes": [],
            "users": [
                {
                    "label": "user1",
                    "value": {
                        "shareType": 0,
                        "shareWith": "user1",
                        "shareWithAdditionalInfo": "user1@user1.com"
                    }
                },
                {
                    "label": "user2",
                    "value": {
                        "shareType": 0,
                        "shareWith": "user2"
                    }
                }
            ]
        },
        "meta": {
            "itemsperpage": "",
            "message": "OK",
            "status": "ok",
            "statuscode": 200,
            "totalitems": ""
        }
    }
}

The same request with xml body.

<?xml version="1.0"?>
<ocs>
  <meta>
  <status>ok</status>
  <statuscode>200</statuscode>
  <message>OK</message>
  <totalitems></totalitems>
  <itemsperpage></itemsperpage>
  </meta>
  <data>
    <exact>
      <users>
        <element>
          <label>admin</label>
          <value>
            <shareType>0</shareType>
            <shareWith>admin</shareWith>
          </value>
        </element>
      </users>
      <groups/>
      <remotes/>
    </exact>
    <users>
      <element>
        <label>user1</label>
        <value>
          <shareType>0</shareType>
          <shareWith>user1</shareWith>
          <shareWithAdditionalInfo>user1@user1.com</shareWithAdditionalInfo>
        </value>
      </element>
      <element>
        <label>user2</label>
        <value>
          <shareType>0</shareType>
          <shareWith>user2</shareWith>
        </value>
      </element>
    </users>
    <groups>
      <element>
        <label>group1</label>
        <value>
          <shareType>1</shareType>
          <shareWith>group1</shareWith>
        </value>
      </element>
      <element>
        <label>group2</label>
        <value>
          <shareType>1</shareType>
          <shareWith>group2</shareWith>
        </value>
      </element>
    </groups>
    <remotes/>
  </data>
</ocs>