# Company User Assignment API

### Overview and Motivation

One of the primary challenges for new clients implementing Procore is process of importing users into the Directory and assinging those user to projects with the correct permission templates. Today this is a largely manual process, with exceptions for larger customers who rely on our Technical Services team to write custom integrations to help speed up the import process.

The complexitity of these challenges scales exponentially across larger workforces with thousands of users and projects they must be assinged to. This challenge is becoming increasing more common for Specialty Contractors who use Procore to manage their workforces. The process of assinging users to projects in the company directory is extremely inefficiet. On top of this, the directory caps out at displaying 500 projects in the UI. We need to find a way around this for larger clients.

### Proposed Solution

As a solution to this problem, we will build a bulk assignments endpoint that the custom solutions team can use to rapidly assign users to projects with the correct permission template.

#### Request

##### URL

`POST rest/v1.1/companies/:company_id/users/bulk_add`

##### Body

{
    "users": [
        {
            "user_id": 123456,
            "project_id": 246810,
            "permission_template_id": 42,
        },
        ...
    ]
}

#### Response

##### Content

Success

`{ status: 'ok' }` # up to you on what you want here

Failure

`{ errors: [] }` # up to you on what you want here

##### Status

`200` - Success. All users passed are successfully assigned to projects.

`206` - Parital Success? We could use this if we want to process ones that succeed and ones that don't. This could conflict with 403 though.

`422` - Unprocessable Entity. The request body is malformed. We should return suggestions of what's missing or expected.

`403` - Forbidden. Client does not have proper permissions to add users to one of the given projects. An error should be returned explaining which line items failed.

`404` - Not Found. Cannot find one of the users, projets, or permission templates passed.

`500` - Internal Server Error. Send a bugsnag and hope it's not our problem.

### Questions and Consideration

- Overall, do you agree with this contract?
- What should we return in the response if successful?
- Any preference on error spec / shape?
- If one of the inserts fails should we rollback the entire transaction?
- Do we want object level error messages? X, Y, Z items failed because you don't have the correct permissions or is this a security flaw?