Working with Companies and Users

activeCollab offers several commands which are designed to allow other applications to create and manage company or user accounts.

1. Company Fields

  1. name (string) - Company name. Value of this field is required and needs to be unique in the entire system.

2. User Fields

  1. email (string) - The user's email address. The value of this field is required when a user account is created and must be properly formatted. There can also only be one user associated with any given email address in the system.
  2. password (string) - The user's password. A value for this field is required when a user account is created. Minimal length of the password is 3 characters.
  3. first_name (string) -The user's first name
  4. last_name (string) - The user's last name
  5. role_id (integer) - ID of the user's System Role. Only administrators or people with manage_people permissions included in their System Role are able to change the value of this field.
Note

When a new user account is created, a user can set the role_id to a custom value only if he/she is an Administrator or has the manage_people permission in their Role. If a user who creates an account is not an Administrator or People manager, then the user's role will be set to the default role configured on the Administration > Roles page.

3. /people

Lists all the companies defined in the System, no matter if they are Active or Archived.

Method: GET

Example response:

<companies>
  <company>
    <id>...</id>
    <name>...</name>
    <created_on>...</created_on>
    <permalink>...</permalink>
    <office_address>...</office_address>
    <office_phone>...</office_phone>
    <office_fax>...</office_fax>
    <office_homepage>...</office_homepage>
  </company>
</companies>

4. /people/add-company

This command will create a new company, and if the post is successful, then details of the newly created company will be returned.

Method: POST

Request example:

submitted=submitted
company[name]=New Company

Example response:

<company>
  <id>...</id>
  <name>...</name>
  <created_on>...</created_on>
  <permalink>...</permalink>
  <office_address></office_address>
  <office_phone></office_phone>
  <office_fax></office_fax>
  <office_homepage></office_homepage>
</company>

5. /people/:company_id

Displays the properties of a specific company.

Method: GET.

Example response:

<company>
  <id>...</id>
  <name>...</name>
  <created_on>...</created_on>
  <permalink>...</permalink>
  <office_address></office_address>
  <office_phone></office_phone>
  <office_fax></office_fax>
  <office_homepage></office_homepage>
  <users>
    ...
  </users>
  <logo_url>...</logo_url>
</company>

6. /people/:company_id/edit

Updates properties of an existing company. On success, updated company details are returned.

Method: POST.

Request example:

submitted=submitted
company[name]=Updated Company Name

Response example:

<company>
  <id>...</id>
  <name>...</name>
  <created_on>...</created_on>
  <permalink>...</permalink>
  <office_address></office_address>
  <office_phone></office_phone>
  <office_fax></office_fax>
  <office_homepage></office_homepage>
</company>

7. /people/:company_id/delete

You can use this to delete a company and all of its users. Projects that this company and its users were assigned to will not be deleted! If successful, the system will return a HTTP status of 200 OK.

Note

There is one company which can't be deleted - the Owner Company!

Method: POST.

Request example:

submitted=submitted

8. /people/:company_id/add-user

Creates a user account in the selected company. If successful, the function will display details of the newly created user account.

Note

Only Administrators and people with manage_people permission included in their System Role can set role_id value. If a user who creates the new account is not an Administrator or People Manager, the default role ID will be used.

Method: POST.

Request example:

submitted = submitted
user[email] = ilija@a51dev.com
user[password] = new-password
user[password_a] = new-password
user[role_id] = 1

Response:

<user>
  <id>...</id>
  <company_id>...</company_id>
  <first_name>...</first_name>
  <last_name>...</last_name>
  <email>...</email>
  <last_visit_on>...</last_visit_on>
  <permalink>...</permalink>
  <role_id>...</role_id>
  <is_administrator>...</is_administrator>
  <is_project_manager>...</is_project_manager>
  <is_people_manager>...</is_people_manager>
  <token>...</token>
</user>

9. /people/:company_id/users/:user_id

Shows details of a specific user.

Method: GET

Example response:

<user>
  <id>...</id>
  <first_name>...</first_name>
  <last_name>...</last_name>
  <email>...</email>
  <last_visit_on>...</last_visit_on>
  <permalink>...</permalink>
  <role_id>...</role_id>
  <is_administrator>...</is_administrator>
  <is_project_manager>...</is_project_manager>
  <is_people_manager>...</is_people_manager>
  <token>...</token>
  <company>
    <id>...</id>
    <name>...</name>
    <created_on>...</created_on>
    <permalink>...</permalink>
    <office_address>...</office_address>
    <office_phone>...</office_phone>
    <office_fax>...</office_fax>
    <office_homepage>...</office_homepage>
  </company>
  <avatar_url>...</avatar_url>
</user>

10. /people/:company_id/users/:user_id/edit

Updates details of an existing user.

Method: POST.

Request example:

submitted = submitted
user[first_name] = John
user[last_name] = Doe

Example response:

<user>
  <id>...</id>
  <first_name>...</first_name>
  <last_name>...</last_name>
  <email>...</email>
  <last_visit_on>...</last_visit_on>
  <permalink>...</permalink>
  <role_id>...</role_id>
  <is_administrator>...</is_administrator>
  <is_project_manager>...</is_project_manager>
  <is_people_manager>...</is_people_manager>
  <token>...</token>
  <company>
    <id>...</id>
    <name>...</name>
    <created_on>...</created_on>
    <permalink>...</permalink>
    <office_address>...</office_address>
    <office_phone>...</office_phone>
    <office_fax>...</office_fax>
    <office_homepage>...</office_homepage>
  </company>
  <avatar_url>...</avatar_url>
</user>

11. /people/:company_id/users/:user_id/delete

Delete a specific user account. if successful, a HTTP 200 OK status will be returned.

Note

Data created by this user - project, tickets, discussions, comments, etc. will not be deleted.

Method: POST.

Request example:

submitted = submitted