Documentation (2024.2 Enterprise)

# Collaborator

Collaborators are users with limited access to the Company they're created in. Collaborators can only access Projects they have been specifically added to.

- Attributes
- Searchable attributes
- Child objects
- Operations
  - `GET /collaborators`
  - `GET /collaborators/:id`
  - `POST /collaborators`
  - `PUT /collaborators/:id`
  - `DELETE /collaborators/:id`

## Attributes

Collaborators share the same attributes with Users.

## Searchable attributes

Collaborators can be searched by their `id`, `email`, and `display_name` attributes. See the search documentation for instructions how to do this.

## Child objects

The following child objects can be attached to the collaborators returned, to eliminate the need for requesting them separately:

Object | Attribute
--- | ---
Project | `projects`
Repository | `repositories`

For example, to get all of the collaborators's projects in full, attach `include=projects` to your GET request.

See the child object API documentation for a description of the possible operations.

## Operations

### GET /collaborators

Returns all the collaborators in the company, with optional limit and offset parameters, as a metadata-results object.

#### Example Request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/collaborators

#### Example Response

    {
      "metadata": {
        "more_results": false,
        "next_offset": 7,
        "count": 7
      },
      "results": [
        {
          "api_status": 200,
          "api_timestamp": "2014-11-25T13:55:11Z",
          "id": "norris",
          "created_at": "2014-11-18T13:19:40Z",
          "updated_at": "2014-11-18T13:19:40Z",
          "type": "collaborator",
          "email": "norris@acme.org",
          "first_name": "Chuck",
          "last_name": "Norris",
          "display_name": "Chuck Norris",
          "company_admin": false,
          "instance_admin": false,
          "description": "",
          "phone": "",
          "title": "",
          "avatar": {
            "large": "",
            "medium": "",
            "small": ""
          },
          "synchronized_fields": [

          ],
          "locale": "en",
          "source": ""
        },
        ...
      ]
    }

### GET /collaborators/:id

Returns a specific collaborator.

#### Example Request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/collaborators/norris

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2014-11-25T13:55:11Z",
      "id": "norris",
      "created_at": "2014-11-18T13:19:40Z",
      "updated_at": "2014-11-18T13:19:40Z",
      "type": "collaborator",
      "email": "norris@acme.org",
      "first_name": "Chuck",
      "last_name": "Norris",
      "display_name": "Chuck Norris",
      "company_admin": false,
      "instance_admin": false,
      "description": "",
      "phone": "",
      "title": "",
      "avatar": {
        "large": "",
        "medium": "",
        "small": ""
      },
      "synchronized_fields": [

      ],
      "locale": "en",
      "source": ""
    }

### POST /collaborators

Creates a new collaborator to the company and returns the created collaborator object. A matching collaborator is first searched from the directory (by `email` and `id`) when LDAP authentication is enabled for collaborators. The collaborator must be found from the directory when LDAP only authentication is used for collaborators, otherwise a 404 response is returned.

#### Example Request

    curl -X POST \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "id": "norris", "email": "norris@acme.org" }' \
      https://helixteamhub.cloud/api/collaborators

#### Example Response

    {
      "api_status": 201,
      "api_timestamp": "2014-11-25T13:55:11Z",
      "id": "norris",
      "created_at": "2014-11-18T13:19:40Z",
      "updated_at": "2014-11-18T13:19:40Z",
      "type": "collaborator",
      "email": "norris@acme.org",
      "first_name": "",
      "last_name": "",
      "display_name": "norris@acme.org",
      "company_admin": false,
      "instance_admin": false,
      "description": "",
      "phone": "",
      "title": "",
      "avatar": {
        "large": "",
        "medium": "",
        "small": ""
      },
      "synchronized_fields": [

      ],
      "locale": "en",
      "source": ""
    }

### PUT /collaborators/:id

Updates a collaborator. Returns the updated collaborator.

#### Example Request

    curl -X PUT \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "first_name": "Chuck", "last_name": "Norris" }' \
      https://helixteamhub.cloud/api/collaborators/norris

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2014-11-25T13:55:11Z",
      "id": "norris",
      "created_at": "2014-11-18T13:19:40Z",
      "updated_at": "2014-11-18T13:19:40Z",
      "type": "collaborator",
      "email": "norris@acme.org",
      "first_name": "Chuck",
      "last_name": "Norris",
      "display_name": "norris@acme.org",
      "company_admin": false,
      "instance_admin": false,
      "description": "",
      "phone": "",
      "title": "",
      "avatar": {
        "large": "",
        "medium": "",
        "small": ""
      },
      "synchronized_fields": [

      ],
      "locale": "en",
      "source": ""
    }

### DELETE /collaborators/:id

Deletes a collaborator. Returns the deleted collaborator.

#### Example Request

    curl -X DELETE \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/collaborators/norris

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2014-11-25T13:55:11Z",
      "id": "norris",
      "created_at": "2014-11-18T13:19:40Z",
      "updated_at": "2014-11-18T13:19:40Z",
      "type": "collaborator",
      "email": "norris@acme.org",
      "first_name": "Chuck",
      "last_name": "Norris",
      "display_name": "norris@acme.org",
      "company_admin": false,
      "instance_admin": false,
      "description": "",
      "phone": "",
      "title": "",
      "avatar": {
        "large": "",
        "medium": "",
        "small": ""
      },
      "synchronized_fields": [

      ],
      "locale": "en",
      "source": ""
    }

Your search for returned results

Your search for returned results