Hierarchy

Manage your company hierarchy at Zenput.

Suggest Edits

Overview

You can fully manipulate a company hierarchy stored in Zenput by using exclusively Zenput API endpoints. In other words, you can read, create, edit, and deactivate any company hierarchy resource record.

Such actions enable you to achieve numerous tasks involving a company hierarchy, for example:

  • Building a hierarchy from scratch
  • Updating a record property of a hierarchy resource, such as:
    • Team
      • Name
      • Description
    • User role
      • Name
      • Permission level
    • User
      • Email
      • Password
      • First name
      • Last name
      • SMS number
      • User role
      • Permission level
    • Location
      • Name
      • Address
      • Owner user
  • Making changes to an existing hierarchy, such as:
    • Moving a team and placing it under other team
    • Moving a user role and placing it under other user role
    • Moving a user or a location from one team to another
    • Deactivating teams, user roles, users, or locations

How to build a hierarchy?

This section contains step-by-step instructions on building a company hierarchy.

Prerequisites

You must break down company records to align them with the resources' records that a Zenput hierarchy can allocate.

Components

You need the following components to build a company hierarchy:

Note: The following endpoints are not essential to building a company hierarchy. However, you can leverage them for further actions regarding the resources' records that you store in Zenput.

Steps

Note: There is a one-to-one relationship between the editable properties of a resource record and the parameters in the JSON request body of any resource endpoint request included in these steps.

  1. Create teams.
    • For each team:
      1. Set up a POST Create Team endpoint request.
      a. Set the corresponding URL address: https://www.zenput.com/api/v3/teams/.
      b. Set up the request header.
      I. Set JSON both as request and as response media type.
      II. Add a valid API token.
      c. Set up a JSON request body.
      * Include the parameters in the following list:
      - Team's name: name
      - Team's parent team ID: parent.id
      Note: The previous list does not include all available parameters to create a team, only the essential ones. Hence, not all of the editable team's properties would have values at first. You can provide values for any missing properties by including the corresponding parameters in this request body or by including them later in a PATCH Update Team Properties endpoint request. The complete list of parameters is available in the BODY PARAMS section of either of these endpoints' reference pages.
      2. Send the request to create the team and keep the ID that the endpoint response includes.
      Important: You need the ID that Zenput generates per team to assign users and locations to such team as well as to set such team as the parent of another team.
      Note: You can immediately verify teams' properties by querying either of the following endpoints:
      - GET List Teams
      - GET Retrieve Team by appending an existing team ID
  2. Create user roles.
    • For each user role:
      1. Set up a POST Create User Role endpoint request.
      a. Set the corresponding URL address: https://www.zenput.com/api/v3/userroles/.
      b. Set up the request header.
      I. Set JSON both as request and as response media type.
      II. Add a valid API token.
      c. Set up a JSON request body.
      * Include the parameters in the following list:
      - User role's name: name
      - User role's default permission level ID: default_permission.id
      - User role's parent user role ID: parent.id
      2. Send the request to create the user role and keep the ID that the endpoint response includes.
      Important: You need the ID that Zenput generates per user role to assign such user role to a user as well as to set such user role as the parent of another user role.
      Note: You can immediately verify user roles' properties by querying either of the following endpoints:
      - GET List User Roles
      - GET Retrieve User Role by appending an existing user role ID
  3. Create users, set their user roles, set their permission level, and assign each user to its corresponding team.
    • For each user:
      1. Set up a POST Create User endpoint request.
      a. Set the corresponding URL address: https://www.zenput.com/api/v3/users/.
      b. Set up the request header.
      I. Set JSON both as request and as response media type.
      II. Add a valid API token.
      c. Set up a JSON request body.
      * Include the parameters in the following list:
      - User's Zenput account email: email
      - User's Zenput account password: password
      - User's first name: first_name
      - User's last name: last_name
      - User's user role ID: user_role.id
      - IDs of user's permission levels: groups[]
      - IDs of user's teams: teams[]
      Note: The previous list does not include all available parameters to create a user, only the essential ones. Hence, not all of the editable user's properties would have values at first. You can provide values for any missing properties by including the corresponding parameters in this request body or by including them later in a PATCH Update User Properties endpoint request. The complete list of parameters is available in the BODY PARAMS section of either of these endpoints' reference pages.
      2. Send the request to create the user and keep the ID that the endpoint response includes.
      Important: You need the ID that Zenput generates per user to assign such user to a team.
      Note: You can immediately verify users' properties by querying either of the following endpoints:
      - GET List Users
      - GET Retrieve User by appending an existing user ID
  4. Create locations, set their owner user, and assign each location to its corresponding team.
    • For each location:
      1. Set up a POST Create Location endpoint request.
      a. Set the corresponding URL address: https://www.zenput.com/api/v3/locations/.
      b. Set up the request header.
      I. Set JSON both as request and as response media type.
      II. Add a valid API token.
      c. Set up a JSON request body.
      * Include the parameters in the following list:
      - Location's name: name
      - Location's address: address
      - Location's city: city
      - Location's state: state
      - Location's country: country
      - IDs of location's owner users: owners []
      - IDs of location's teams: teams []
      Note: The previous list does not include all available parameters to create a location, only the essential ones. Hence, not all of the editable location's properties would have values at first. You can provide values for any missing properties by including the corresponding parameters in this request body or by including them later in a PATCH Update Location Properties endpoint request. The complete list of parameters is available in the BODY PARAMS section of either of these endpoints' reference pages.
      2. Send the request to create the location and keep the ID that the endpoint response includes.
      Important: You need the ID that Zenput generates per location to assign such location to a team.
      Note: You can immediately verify locations' properties by querying either of the following endpoints:
      - GET List Locations
      - GET Retrieve Location by appending an existing location ID

Example

This section describes how to build the hierarchy of a fictitious company by following the previous steps.

Company Information

This section contains information about Awesome Company, Inc., a fictitious company.

The following table contains information about Awesome Company, Inc.'s users.

First NameLast NameEmailPasswordRolePermission LevelTeam
AnaEisler[email protected]Zenput012CEOAdminAwesome Company
JoseSmith[email protected]Zenput210CTOOwnerAwesome Company
SandraHill[email protected]Zenput123CFOAdminAwesome Company
CrisSolace[email protected]Zenput321Operations DirectorManagerOperations
ShawnWest[email protected]Zenput234Store SupervisorManagerMontana
CarlaGray[email protected]Zenput432Store StaffSubmitterMontana

Table 1: Awesome Company Inc.'s users.

The following table contains information about Awesome Company, Inc.'s locations.

NameEmailAddressCityStateCountry
Arne Plains[email protected]6288 Arne PlainsNew VenaportMontanaUSA

Table 2: Awesome Company Inc.'s locations.

Components

Given the information from the previous tables, the following facts are true about the hierarchy resources' records of Awesome Company Inc.:

  • Regarding teams:
    • Three teams exist:
      • Team 1: Awesome Company
      • Team 2: Operations
      • Team 3: Montana
    • The team precedence is:
      • Awesome Company > Operations
      • Operations > Montana

Note: In this example, there is no indication that any user is solely in charge of the one location. Hence, none of the users would be the owner of such location. In cases like this, you can create an auxiliary user and its corresponding user role to set the ownership of the location.

  • Regarding user roles:

    • Seven user roles exist:
      • User role 1: CEO
      • User role 2: CTO
      • User role 3: CFO
      • User role 4: Operations Director
      • User role 5: Store Supervisor
      • User role 6: Store Staff
      • User role 7: Location
    • The user role precedence is:
      • CEO > CTO
      • CEO > CFO
      • CEO > Operations Director
      • Operations Director > Store Supervisor
      • Store Supervisor > Store Staff

  • Regarding users:

    • Seven users exist:
      • User 1: Ana Eisler
      • User 2: Jose Smith
      • User 3: Sandra Hill
      • User 4: Cris Solace
      • User 5: Shawn West
      • User 6: Carla Gray
      • User 7: Arne Plains

Note: The auxiliary user "Arne Plains" would have the "Location" auxiliary user role.

  • Regarding locations:
    • One location exists:
      • Location 1: Arne Plains

Assumptions

In this example, Jose Smith (the CTO of Awesome Company Inc.) would be the user that would create every hierarchy resource record because of its "Owner" permission level. Such fact means that this user record would already have to exist in Zenput.

Steps

  1. Create teams.

Set up the POST Create Team endpoint requests.

Each of the following code snippets shows the necessary cURL command to place the corresponding request.

curl --request POST \
     --url https://www.zenput.com/api/v3/teams/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "name": "Awesome Company"
}
'

curl --request POST \
     --url https://www.zenput.com/api/v3/teams/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "name": "Operations",
     "parent": {
         "id": 1
     }
}
'

curl --request POST \
     --url https://www.zenput.com/api/v3/teams/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "name": "Montana",
     "parent": {
         "id": 2
     }
}
'

Code Snippets Set 1: POST Create Team endpoint requests.

Send each request to create the corresponding team and keep the ID that each endpoint response includes.

Each of the following code snippets shows the corresponding endpoint response.

{
    "meta": {
        "status_code": 201
    },
    "data": {
        "id": 1,
        "name": "Awesome Company",
        "description": "",
        "children": [],
        "users": [],
        "locations": [],
        "company": {
            "id": 1,
            "name": "Awesome Company",
            "features": []
        },
        "external_key": null,
        "created_user": {
            "id": 2,
            "username": "[email protected]",
            "display_name": "Jose Smith",
            "user_role": null,
            "groups": [
                {
                    "id": 1,
                    "name": "Owner"
                }
            ]
        },
        "parent": null,
        "is_editable": true,
        "is_company_root": false,
        "has_accounts": false,
        "has_children": false,
        "has_users": false
    }
}

{
    "meta": {
        "status_code": 201
    },
    "data": {
        "id": 2,
        "name": "Operations",
        "description": "",
        "children": [],
        "users": [],
        "locations": [],
        "company": {
            "id": 1,
            "name": "Awesome Company",
            "features": []
        },
        "external_key": null,
        "created_user": {
            "id": 2,
            "username": "[email protected]",
            "display_name": "Jose Smith",
            "user_role": null,
            "groups": [
                {
                    "id": 1,
                    "name": "Owner"
                }
            ]
        },
        "parent": {
            "id": 1,
            "name": "Awesome Company"
        },
        "is_editable": true,
        "is_company_root": false,
        "has_accounts": false,
        "has_children": false,
        "has_users": false
    }
}

{
    "meta": {
        "status_code": 201
    },
    "data": {
        "id": 3,
        "name": "Montana",
        "description": "",
        "children": [],
        "users": [],
        "locations": [],
        "company": {
            "id": 1,
            "name": "Awesome Company",
            "features": []
        },
        "external_key": null,
        "created_user": {
            "id": 2,
            "username": "[email protected]",
            "display_name": "Jose Smith",
            "user_role": null,
            "groups": [
                {
                    "id": 1,
                    "name": "Owner"
                }
            ]
        },
        "parent": {
            "id": 2,
            "name": "Operations"
        },
        "is_editable": true,
        "is_company_root": false,
        "has_accounts": false,
        "has_children": false,
        "has_users": false
    }
}

Code Snippets Set 2: POST Create Team endpoint responses.

The following image shows Awesome Company, Inc.'s teams in Zenput.

1134

Image 1: Awesome Company Inc.'s teams in Zenput.

  1. Create user roles.

Set up the POST Create User Role endpoint requests.

Each of the following code snippets shows the necessary cURL command to place the corresponding request.

curl --request POST \
     --url https://www.zenput.com/api/v3/userroles/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "name": "CEO",
     "default_permission": {
          "id": 4
     }
}
'

curl --request POST \
     --url https://www.zenput.com/api/v3/userroles/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "name": "CTO",
     "default_permission": {
          "id": 1
     },
     "parent":{
          "id": 1
    }
}
'

curl --request POST \
     --url https://www.zenput.com/api/v3/userroles/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "name": "CFO",
     "default_permission": {
          "id": 4
     },
     "parent":{
          "id": 1
    }
}
'

curl --request POST \
     --url https://www.zenput.com/api/v3/userroles/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "name": "Operations Director",
     "default_permission": {
          "id": 2
     },
     "parent":{
          "id": 1
    }
}
'

curl --request POST \
     --url https://www.zenput.com/api/v3/userroles/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "name": "Store Supervisor",
     "default_permission": {
          "id": 2
     },
     "parent":{
          "id": 4
    }
}
'

curl --request POST \
     --url https://www.zenput.com/api/v3/userroles/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "name": "Store Staff",
     "default_permission": {
          "id": 3
     },
     "parent":{
          "id": 5
    }
}
'

curl --request POST \
     --url https://www.zenput.com/api/v3/userroles/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "name": "Location",
     "default_permission": {
          "id": 3
     }
}
'

Code Snippets Set 3: POST Create User Role endpoint requests.

Send each request to create the corresponding user role and keep the ID that each endpoint response includes.

Each of the following code snippets shows the corresponding endpoint response.

{
    "meta": {
        "status_code": 200
    },
    "data": {
        "id": 1,
        "name": "CEO",
        "parent": null,
        "children": [],
        "default_permission": {
            "id": 4,
            "name": "Admin"
        }
    }
}

{
    "meta": {
        "status_code": 200
    },
    "data": {
        "id": 2,
        "name": "CTO",
        "parent": {
            "id": 1,
            "name": "CEO"
        },
        "children": [],
        "default_permission": {
            "id": 1,
            "name": "Owner"
        }
    }
}

{
    "meta": {
        "status_code": 200
    },
    "data": {
        "id": 3,
        "name": "CFO",
        "parent": {
            "id": 1,
            "name": "CEO"
        },
        "children": [],
        "default_permission": {
            "id": 4,
            "name": "Admin"
        }
    }
}

{
    "meta": {
        "status_code": 200
    },
    "data": {
        "id": 4,
        "name": "Operations Director",
        "parent": {
            "id": 1,
            "name": "CEO"
        },
        "children": [],
        "default_permission": {
            "id": 2,
            "name": "Manager"
        }
    }
}

{
    "meta": {
        "status_code": 200
    },
    "data": {
        "id": 5,
        "name": "Store Supervisor",
        "parent": {
            "id": 4,
            "name": "Operations Director"
        },
        "children": [],
        "default_permission": {
            "id": 2,
            "name": "Manager"
        }
    }
}

{
    "meta": {
        "status_code": 200
    },
    "data": {
        "id": 6,
        "name": "Store Staff",
        "parent": {
            "id": 5,
            "name": "Store Supervisor"
        },
        "children": [],
        "default_permission": {
            "id": 3,
            "name": "Submitter"
        }
    }
}

{
    "meta": {
        "status_code": 200
    },
    "data": {
        "id": 7,
        "name": "Location",
        "parent": null,
        "children": [],
        "default_permission": {
            "id": 3,
            "name": "Submitter"
        }
    }
}

Code Snippets Set 4: POST Create User Role endpoint responses.

The following image shows Awesome Company, Inc.'s user roles in Zenput.

Note: The "Location" auxiliary role would not be part of the user roles' structure.

1713

Image 2: Awesome Company Inc.'s user roles in Zenput.

  1. Create users, set their user roles, set their permission level, and assign each user to its corresponding team.

Note: Although the record of the user "Jose Smith" (the CTO of Awesome Company Inc.) would have to already exist in Zenput, this example includes the code snippet that shows the cURL command to place the request to create it as well as the one that shows the corresponding endpoint response.

Set up the POST Create User endpoint requests.

Each of the following code snippets shows the necessary cURL command to place the corresponding request.

curl --request POST \
     --url https://www.zenput.com/api/v3/users/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "email": "[email protected]",
     "password": "Zenput012",
     "first_name": "Ana",
     "last_name": "Eisler",
     "user_role": {
          "id": 1
     },
     "groups": [
          {
               "id": 4
          }
     ],
     "teams": [
          {
               "id": 1
          }
     ]
}
'

curl --request POST \
     --url https://www.zenput.com/api/v3/users/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "email": "[email protected]",
     "password": "Zenput210",
     "first_name": "Jose",
     "last_name": "Smith",
     "groups": [
          {
               "id": 1
          }
     ]
}
'

curl --request POST \
     --url https://www.zenput.com/api/v3/users/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "email": "[email protected]",
     "password": "Zenput123",
     "first_name": "Sandra",
     "last_name": "Hill",
     "user_role": {
          "id": 3
     },
     "groups": [
          {
               "id": 4
          }
     ],
     "teams": [
          {
               "id": 1
          }
     ]
}
'

curl --request POST \
     --url https://www.zenput.com/api/v3/users/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "email": "[email protected]",
     "password": "Zenput321",
     "first_name": "Cris",
     "last_name": "Solace",
     "user_role": {
          "id": 4
     },
     "groups": [
          {
               "id": 2
          }
     ],
     "teams": [
          {
               "id": 2
          }
     ]
}
'

curl --request POST \
     --url https://www.zenput.com/api/v3/users/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "email": "[email protected]",
     "password": "Zenput234",
     "first_name": "Shawn",
     "last_name": "West",
     "user_role": {
          "id": 5
     },
     "groups": [
          {
               "id": 2
          }
     ],
     "teams": [
          {
               "id": 3
          }
     ]
}
'

curl --request POST \
     --url https://www.zenput.com/api/v3/users/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "email": "[email protected]",
     "password": "Zenput432",
     "first_name": "Carla",
     "last_name": "Gray",
     "user_role": {
          "id": 6
     },
     "groups": [
          {
               "id": 3
          }
     ],
     "teams": [
          {
               "id": 3
          }
     ]
}
'

curl --request POST \
     --url https://www.zenput.com/api/v3/users/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "email": "[email protected]",
     "password": "Zenput345",
     "first_name": "Arne Plains",
     "user_role": {
          "id": 7
     },
     "groups": [
          {
               "id": 3
          }
     ],
     "teams": [
          {
               "id": 3
          }
     ]
}
'

Code Snippets Set 5: POST Create User endpoint requests.

Send each request to create the corresponding user and keep the ID that each endpoint response includes.

Each of the following code snippets shows the corresponding endpoint response.

{
    "meta": {
        "status_code": 201
    },
    "data": {
        "id": 1,
        "username": "[email protected]",
        "first_name": "Ana",
        "last_name": "Eisler",
        "email": "[email protected]",
        "sms_number": null,
        "user_role": {
            "id": 1,
            "name": "CEO"
        },
        "company": {
            "id": 1,
            "name": "Awesome Company",
            "features": []
        },
        "locale": "en-US",
        "default_team": {
            "id": 1,
            "name": "Awesome Company"
        },
        "groups": [
            {
                "id": 4,
                "name": "Admin"
            }
        ],
        "date_invited": null,
        "date_redeemed": null,
        "display_name": "Ana Eisler",
        "time_zone": "Etc/UTC",
        "teams": [
            {
                "id": 1,
                "name": "Awesome Company"
            }
        ],
        "owned_locations": [],
        "external_key": null
    }
}

{
    "meta": {
        "status_code": 201
    },
    "data": {
        "id": 2,
        "username": "[email protected]",
        "first_name": "Jose",
        "last_name": "Smith",
        "email": "[email protected]",
        "sms_number": null,
        "user_role": null,
        "company": {
            "id": 1,
            "name": "Awesome Company",
            "features": []
        },
        "locale": "en-US",
        "default_team": null,
        "groups": [
            {
                "id": 1,
                "name": "Owner"
            }
        ],
        "date_invited": null,
        "date_redeemed": null,
        "display_name": "Jose Smith",
        "time_zone": "Etc/UTC",
        "teams": [],
        "owned_locations": [],
        "external_key": null
    }
}

{
    "meta": {
        "status_code": 201
    },
    "data": {
        "id": 3,
        "username": "[email protected]",
        "first_name": "Sandra",
        "last_name": "Hill",
        "email": "[email protected]",
        "sms_number": null,
        "user_role": {
            "id": 3,
            "name": "CFO"
        },
        "company": {
            "id": 1,
            "name": "Awesome Company",
            "features": []
        },
        "locale": "en-US",
        "default_team": {
            "id": 1,
            "name": "Awesome Company"
        },
        "groups": [
            {
                "id": 4,
                "name": "Admin"
            }
        ],
        "date_invited": null,
        "date_redeemed": null,
        "display_name": "Sandra Hill",
        "time_zone": "Etc/UTC",
        "teams": [
            {
                "id": 1,
                "name": "Awesome Company"
            }
        ],
        "owned_locations": [],
        "external_key": null
    }
}

{
    "meta": {
        "status_code": 201
    },
    "data": {
        "id": 4,
        "username": "[email protected]",
        "first_name": "Cris",
        "last_name": "Solace",
        "email": "[email protected]",
        "sms_number": null,
        "user_role": {
            "id": 4,
            "name": "Operations Director"
        },
        "company": {
            "id": 1,
            "name": "Awesome Company",
            "features": []
        },
        "locale": "en-US",
        "default_team": {
            "id": 2,
            "name": "Operations"
        },
        "groups": [
            {
                "id": 2,
                "name": "Manager"
            }
        ],
        "date_invited": null,
        "date_redeemed": null,
        "display_name": "Cris Solace",
        "time_zone": "Etc/UTC",
        "teams": [
            {
                "id": 2,
                "name": "Operations"
            }
        ],
        "owned_locations": [],
        "external_key": null
    }
}

{
    "meta": {
        "status_code": 201
    },
    "data": {
        "id": 5,
        "username": "[email protected]",
        "first_name": "Shawn",
        "last_name": "West",
        "email": "[email protected]",
        "sms_number": null,
        "user_role": {
            "id": 5,
            "name": "Store Supervisor"
        },
        "company": {
            "id": 1,
            "name": "Awesome Company",
            "features": []
        },
        "locale": "en-US",
        "default_team": {
            "id": 3,
            "name": "Montana"
        },
        "groups": [
            {
                "id": 2,
                "name": "Manager"
            }
        ],
        "date_invited": null,
        "date_redeemed": null,
        "display_name": "Shawn West",
        "time_zone": "Etc/UTC",
        "teams": [
            {
                "id": 3,
                "name": "Montana"
            }
        ],
        "owned_locations": [],
        "external_key": null
    }
}

{
    "meta": {
        "status_code": 201
    },
    "data": {
        "id": 6,
        "username": "[email protected]",
        "first_name": "Carla",
        "last_name": "Gray",
        "email": "[email protected]",
        "sms_number": null,
        "user_role": {
            "id": 6,
            "name": "Store Staff"
        },
        "company": {
            "id": 1,
            "name": "Awesome Company",
            "features": []
        },
        "locale": "en-US",
        "default_team": {
            "id": 3,
            "name": "Montana"
        },
        "groups": [
            {
                "id": 3,
                "name": "Submitter"
            }
        ],
        "date_invited": null,
        "date_redeemed": null,
        "display_name": "Carla Gray",
        "time_zone": "Etc/UTC",
        "teams": [
            {
                "id": 3,
                "name": "Montana"
            }
        ],
        "owned_locations": [],
        "external_key": null
    }
}

{
    "meta": {
        "status_code": 201
    },
    "data": {
        "id": 7,
        "username": "[email protected]",
        "first_name": "Arne Plains",
        "last_name": "",
        "email": "[email protected]",
        "sms_number": null,
        "user_role": {
            "id": 7,
            "name": "Location"
        },
        "company": {
            "id": 1,
            "name": "Awesome Company",
            "features": []
        },
        "locale": "en-US",
        "default_team": {
            "id": 3,
            "name": "Montana"
        },
        "groups": [
            {
                "id": 3,
                "name": "Submitter"
            }
        ],
        "date_invited": null,
        "date_redeemed": null,
        "display_name": "Arne Plains ",
        "time_zone": "Etc/UTC",
        "teams": [
            {
                "id": 3,
                "name": "Montana"
            }
        ],
        "owned_locations": [],
        "external_key": null
    }
}

Code Snippets Set 6: POST Create User endpoint responses.

Note: Since the record of the user "Jose Smith" (the CTO of Awesome Company Inc.) would not have user role nor team data at this point, you can provide values for such properties by including the corresponding parameters in the JSON request body of a PATCH Update User Properties endpoint request.

Set up the PATCH Update User Properties endpoint request.

The following code snippet shows the necessary cURL command to place the corresponding request.

curl --request PATCH \
     --url https://www.zenput.com/api/v3/users/2/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "user_role": {
          "id": 2
     },
     "teams": [
          {
               "id": 1
          }
     ]
}
'

Code Snippets Set 7: PATCH Update User Properties endpoint request.

Send the request to update the properties of the corresponding user.

The following code snippet shows the corresponding endpoint response.

{
    "meta": {
        "status_code": 200
    },
    "data": {
        "id": 2,
        "username": "[email protected]",
        "first_name": "Jose",
        "last_name": "Smith",
        "email": "[email protected]",
        "sms_number": null,
        "user_role": {
            "id": 2,
            "name": "CTO"
        },
        "company": {
            "id": 1,
            "name": "Awesome Company",
            "features": []
        },
        "locale": "en-US",
        "default_team": {
            "id": 1,
            "name": "Awesome Company"
        },
        "groups": [
            {
                "id": 1,
                "name": "Owner"
            }
        ],
        "date_invited": null,
        "date_redeemed": null,
        "display_name": "Jose Smith",
        "time_zone": "Etc/UTC",
        "teams": [],
        "owned_locations": [],
        "external_key": null
    }
}

Code Snippets Set 8: PATCH Update User Properties endpoint response.

The following image shows Awesome Company, Inc.'s users in Zenput.

1132

Image 3: Awesome Company Inc.'s users in Zenput.

  1. Create locations, set their owner user, and assign each location to its corresponding team.

Set up the POST Create Location endpoint request.

The following code snippet shows the necessary cURL command to place the corresponding request.

curl --request POST \
     --url https://www.zenput.com/api/v3/locations/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-TOKEN: ********************************' \
     --data '
{
     "name": "Arne Plains",
     "address": "6288 Arne Plains",
     "city": "New Venaport",
     "state": "MT",
     "country": "US",
     "owners": [
          {
               "id": 7
          }
     ]
     "teams": [
          {
               "id": 3
          }
     ]
}
'

Code Snippets Set 9: POST Create Location endpoint request.

Send the request to create the corresponding location and keep the ID that the endpoint response includes.

The following code snippet shows the corresponding endpoint response.

{
    "meta": {
        "status_code": 201
    },
    "data": {
        "id": 1,
        "name": "Arne Plains",
        "address": "6288 Arne Plains",
        "city": "New Venaport",
        "state": "MT",
        "region": "",
        "zipcode": null,
        "country": "US",
        "email": null,
        "phone": null,
        "external_key": null,
        "lat": null,
        "lon": null,
        "date_modified": "YYYY-MM-DDTHH:MM:SS",
        "date_created": "YYYY-MM-DDTHH:MM:SS",
        "time_zone": "Etc/UTC",
        "company": {
            "id": 1,
            "name": "Awesome Company",
            "features": []
        },
        "tags": [
            {
                "id": 1,
                "name": "All Locations",
                "is_editable": false
            }
        ],
        "owners": [
            {
                "id": 7,
                "username": "[email protected]",
                "display_name": "Arne Plains ",
                "user_role": {
                    "id": 7,
                    "name": "Location"
                },
                "groups": [
                    {
                        "id": 3,
                        "name": "Submitter"
                    }
                ]
            }
        ],
        "teams": [
            {
                "id": 3,
                "name": "Montana"
            }
        ]
    }
}

Code Snippets Set 10: POST Create Location endpoint response.

The following image shows Awesome Company, Inc.'s locations in Zenput.

1088

Image 4: Awesome Company Inc.'s locations in Zenput.

End Result

The following image shows Awesome Company, Inc.'s hierarchy in Zenput.

1138

Image 5: Awesome Company Inc.'s hierarchy in Zenput.

Updated almost 2 years ago