question

cloveruser808 avatar image
cloveruser808 asked cloveruser808 commented

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 APIEmployees
10 |2000 characters needed characters left characters exceeded

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

1 Answer

· Write an Answer
cloveruser808 avatar image
cloveruser808 answered cloveruser808 commented

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 comments
10 |2000 characters needed characters left characters exceeded

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

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 Likes 0 ·
cloveruser808 avatar image cloveruser808 David Marginian ♦♦ ·

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 Likes 0 ·

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 Likes 0 ·
Show more comments

Write an Answer

Hint: Notify or tag a user in this post by typing @username.

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