Create Employee with Custom Role via Rest API

Question

question

cloveruser808 asked Jun 14, '21 cloveruser808 commented Jun 15, '21

Create Employee with Custom Role via Rest API

I've tried several methods for creating an employee with a custom role. All of them result in the Employee getting assigned the system role that the custom role is based on. I've tried:

{"name":"test","nickname":"test","pin":"9999","roleId":"XXX","roles":{"elements":[{"id":"XXX"}]}}

and

{"roles":{"elements":[{"id":"XXX"}]},"roleId":"XXX","name":"XXX","nickname":"XXX","customId":XXX,"pin":"XXX","role":"EMPLOYEE"}

and

{"roles":[{"id":"XXX"}],"name":"XXX","nickname":"XXX","customId":XXX,"pin":"XXX","role":"EMPLOYEE"}

and

{"roles":[{"id":"XXX"}],"roleId":"XXX","name":"XXX","nickname":"XXX","customId":XXX,"pin":"XXX","role":"EMPLOYEE"}

and

{"roleId":"XXX","name":"XXX","nickname":"XXX","customId":XXX,"pin":"XXX","role":"EMPLOYEE"}

Obviously, the XXX in the roles ID is my custom roles ID.

What else is there to try?

REST API Employees

10 |2000

Attachments: Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

Welcome to the
Clover Developer Community

Answer 1 · 2021-06-14T03:29:33Z

cloveruser808 answered Jun 14, '21 cloveruser808 commented Jun 15, '21

Figured it out.

The POST url has to have

?expand=roles

This allowed me to create an employee with a custom role ID.

Is this somewhere in the API guides??

6

10 |2000

Attachments: Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

David Marginian ♦♦ commented · Jun 14, 2021 at 12:17 PM

The "expand" parameter has nothing to do with the actual saving of the role. It has to do with the retrieval of the role that was just saved. Without the expand parameter the role will be created, it just won't be returned in the response (because you haven't requested it.

https://docs.clover.com/reference#employeecreateemployee-1 - You will see roles listed as an expansion on the API you are calling.

https://docs.clover.com/docs/expanding-fields

0 ·

cloveruser808 David Marginian ♦♦ commented · Jun 15, 2021 at 07:21 AM

Then you either have a bug somewhere or documentation that needs updating, because that's not what my code is showing me. I literally just tried it now:

- Create Employee with custom role with the following endpoint:

xxx/employees?access_token=[token]

The end result is a new Employee with the role of "Employee"

V.S.

- Create Employee with custom role with the following endpoint:

xxx/employees?expand=roles&access_token=[token]

The end result is a new Employee with the role of "Crew", which is my custom role

I did not change the create POST parameters. All I did was change the endpoint. The following is my POST parameters being sent via cURL:

{"roles":[{"id":"CUSTOM_ROLE_ID"}],"roleId":"CUSTOM_ROLE_ID","name":"TEST","nickname":"TEST","customId":150,"pin":"9999","role":"EMPLOYEE"}

...where "CUSTOM_ROLE_ID" is the Clover internal ID given to my custom role.

I sent the command twice (deleting the employee from the dashboard after the first time, to avoid duplicates). The only difference is the endpoint URL.

I'm verifying this via the actual Clover Dashboard to see what Role the new employee has.

I came to this conclusion after looking at the browser debug mode when creating a new employee using the Clover Dashboard. Using the Clover Dashboard to create a new employee, it looks like the POST uses the expanded endpoint.

0 ·

David Marginian ♦♦ cloveruser808 commented · Jun 15, 2021 at 11:29 AM

Weird, I am trying the same thing on sandbox, and I can't reproduce the behavior you are seeing:

1) Create employee with custom role:

{ {url}}/v3/merchants/{ {mid}}/employees

{
   "roles":[
      {
         "id":"797N....H6X68"
      }
   ],
   "name":"TEST2"
}

2) Retrieve employee that was just created:

{ {url}}/v3/merchants/{ {mid}}/employees/{employeeId}?expand=roles

Response:

{
    "href": "https://sandbox.dev.clover.com/v3/merchants/{mid}/employees/{employeeIdCreatedIn1}",
    "id": "{employeeIdCreatedIn1}",
    "name": "TEST2",
    "inviteSent": false,
    "pin": "1646",
    "role": "ADMIN",
    "roles": {
        "elements": [
            {
                "href": "https://sandbox.dev.clover.com/v3/merchants/{mid}/roles/{customRoleId}",
                "id": "{customRoleId}",
                "name": "Test2",
                "systemRole": "ADMIN",
                "merchant": {}
            }
        ]
    },
    "isOwner": false,
    "orders": {
        "href": "https://sandbox.dev.clover.com/v3/merchants/{mid}/employees/{employeeIdCreatedIn1}/orders"
    }
}

0 ·

Show more comments

question