Tutorials

Leverage Zenput API endpoints.

Suggest Edits

Overview

The tutorials on this page contain step-by-step instructions on using Zenput API endpoints.

Hierarchy Tutorials

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 company hierarchy resources' records that Zenput can allocate.

Components

You need the following components to build a company hierarchy:

After building a company hierarchy, you can use the following Zenput API endpoints for actions regarding the resources' records that you store in Zenput.

Note: The following endpoints are not essential to building a company hierarchy.

Steps

Note: There is a one-to-one relationship between the editable properties of a hierarchy resource record and the parameters in the JSON request body of any hierarchy 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:
      Note: The following 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. The complete list of parameters is available in the BODY PARAMS section of either the POST Create Team or the PATCH Update Team Properties endpoint reference page. 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.
      - Team's name: name
      - Team's parent team ID: parent.id
      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 Get Teams
      - GET Get 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 Get User Roles
      - GET Get 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:
      Note: The following 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. The complete list of parameters is available in the BODY PARAMS section of either the POST Create User or the PATCH Update User Properties endpoint reference page. 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.
      - 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[]
      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 Get Users
      - GET Get 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:
      Note: The following 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. The complete list of parameters is available in the BODY PARAMS section of either the POST Create Location or the PATCH Update Location Properties endpoint reference page. 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.
      - 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 []
      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 Get Locations
      - GET Get 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 Name

Last Name

Email

Password

Role

Permission Level

Team

Ana

Eisler

[email protected]

Zenput012

CEO

Admin

Awesome Company

Jose

Smith

[email protected]

Zenput210

CTO

Owner

Awesome Company

Sandra

Hill

[email protected]

Zenput123

CFO

Admin

Awesome Company

Cris

Solace

[email protected]

Zenput321

Operations Director

Manager

Operations

Shawn

West

[email protected]

Zenput234

Store Supervisor

Manager

Montana

Carla

Gray

[email protected]

Zenput432

Store Staff

Submitter

Montana

Table 1: Awesome Company Inc.'s users.

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

Name

Email

Address

City

State

Country

Arne Plains

[email protected]

6288 Arne Plains

New Venaport

Montana

USA

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.

Note: You can assign any permission level except "Owner" to both the auxiliary user role and the auxiliary user.

  • 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 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 2: POST Create Team endpoint responses.

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

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

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 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 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.

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

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 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 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 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 8: PATCH Update User Properties endpoint response.

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

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

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 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 10: POST Create Location endpoint response.

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

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

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

End Result

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

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

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

Updated 1 day ago