Documentation
Start typing to search…

Managing Hierarchies

To keep your company's hierarchy synchronized with Zenput's database you can use Zenput's API V3 to perform CRUD operations on Locations, Users, Teams, and User roles.

📘

Remember to authenticate request with your API Token

In order to interact with the Zenput API, an API TOKEN is needed. It can be found on Profile Settings on zenput.com after logging in.

To identify requests the X-API-TOKEN header must be provided with each request.

Locations

Listing locations

To get a list of locations, perform a GET request to /api/v3/locations/, this will return the following structure:

{
  "meta": {
    "status_code": 0,
    "count": 0,
    "next": "string",
    "previous": "string"
  },
  "data": [
    ...
  ]
}

data is an array of Locations, each location has the following structure:

{
        "id": 0,
        "name": "string",
        "address": "string",
        "city": "string",
        "state": "string",
        "zipcode": "string",
        "country": "string",
        "email": "string",
        "phone": "string",
        "external_key": "string",
        "lat": 0,
        "lon": 0,
        "date_modified": "2020-10-16T18:25:53.607Z",
        "date_created": "2020-10-16T18:25:53.607Z",
        "time_zone": "string",
        "company": {
          "id": 0,
          "name": "string",
          "features": [
            {
              "id": "string"
            }
          ]
        },
        "tags": [
          {
            "id": 0,
            "name": "string",
            "is_editable": true
          }
        ],
        "owners": [
          {
            "id": 0,
            "username": "string",
            "display_name": "string",
            "user_role": {
              "id": 0,
              "name": "string"
            },
            "groups": [
              {
                "id": 0,
                "name": "string"
              }
            ]
          }
        ],
        "teams": [
          {
            "id": 0,
            "name": "string"
          }
        ]
      }
    ]
  }

To retrieve an existing location without knowing it's Zenput's internal ID beforehand, either of the following 2 url parameters can be used:

  • search: This parameter will try to match the provided value to one of the location's attributes, but this can sometimes retrieve several results since more than 1 location can have the given parameter in one of its attributes, for instance, using search=221 may match a location with external_key=221 and another with 221b Baker Street address.

    Usage: https://zenput.com/api/v3/locations?search=221

  • external_key: This parameter will only match the external_key location attribute which is unique, this ensures that either 0 or 1 results will be retrieved.

    Usage: https://zenput.com/api/v3/locations?external_key=221

Creating locations

To create a location, perform a POST request to /api/v3/locations/, the payload to create a new location is:

POST /api/v3/locations/

{
        "name": "string",
        "address": "string",
        "city": "string",
        "state": "string",
        "zipcode": "string",
        "country": "string",
        "email": "string",
        "phone": "string",
        "external_key": "string",
        "owners": [
            {"id": 0}
         ],
        "teams": [
            {"id": 0}
         ]
    }
📘

Keep in mind

  • owners and teams items should exist already on Zenput
  • external_key must be unique across your company
  • country should be a 2 character country code. Correct: US, Incorrect: USA

Editing locations

There are 2 ways of updating a location, using HTTP verb PUT to replace the entire record with the new data provided, and PATCH to update only the provided properties.

PUT /api/v3/locations/<id>/

The payload data will replace the previous data that was stored for the given ID.

PATCH /api/v3/locations/<id>/

The payload data will update only the provided properties from the location.

Teams

Listing teams

To get a list of teams, perform a GET request to /api/v3/teams/, this will return the following structure:

{
  "meta": {
    "status_code": 0,
    "count": 0,
    "next": "string",
    "previous": "string"
  },
  "data": [
    ...
  ]
}

data is an array of Teams, each team has the following structure:

{
    "id": 0,
    "name": "string",
    "description": "string",
    "children": [{
        "id": 0,
        "name": "string",
        "has_children": "string",
        "has_accounts": "string",
        "has_users": "string"
    }],
    "users": [{
        "id": 0,
        "username": "string",
        "display_name": "string",
        "user_role": {
            "id": 0,
            "name": "string"
        },
        "groups": [{
            "id": 0,
            "name": "string"
        }]
    }],
    "locations": [{
        "id": 0,
        "name": "string",
        "is_active": true
    }],
    "company": {
        "id": 0,
        "name": "string",
        "features": [{
            "id": "string"
        }]
    },
    "external_key": "string",
    "created_user": {
        "id": 0,
        "username": "string",
        "display_name": "string",
        "user_role": {
            "id": 0,
            "name": "string"
        },
        "groups": [{
            "id": 0,
            "name": "string"
        }]
    },
    "parent": {
        "id": 0,
        "name": "string"
    },
    "is_editable": true,
    "is_company_root": "string"
}

To retrieve an existing team without knowing it's Zenput's internal ID beforehand, external_key parameter can be used:

  • external_key: This parameter will match external_key team attribute which is unique, this ensures that either 0 or 1 results will be retrieved.

    Usage: https://zenput.com/api/v3/teams?external_key=TEAM-EXTERNAL-KEY

Creating teams

To create a team, perform a POST request to /api/v3/teams/, the payload to create a new team is:

POST /api/v3/teams/

{
    "name": "string",
    "external_key": "string",
    "parent": {
        "id": 0
    }
}
📘

Keep in mind

  • external_key must be unique across your company
  • parent is optional, the parent must already exist before assigning it as a parent for a team.

Editing teams

There are 2 ways of updating a team, using HTTP verb PUT to replace the entire record with the new data provided, and PATCH to update only the provided properties.

PUT /api/v3/teams/<id>/

The payload data will replace the previous data that was stored for the given ID.

PATCH /api/v3/teams/<id>/

The payload data will update only the provided properties from the team.

Users

Listing users

To get a list of users, perform a GET request to /api/v3/users/, this will return the following structure:

{
  "meta": {
    "status_code": 0,
    "count": 0,
    "next": "string",
    "previous": "string"
  },
  "data": [
    ...
  ]
}

data is an array of Users, each user has the following structure:

{
      "id": 0,
      "username": "string",
      "first_name": "string",
      "last_name": "string",
      "email": "string",
      "sms_number": "string",
      "user_role": {
        "id": 0,
        "name": "string"
      },
      "company": {
        "id": 0,
        "name": "string",
        "features": []
      },
      "locale": "string",
      "default_team": {
        "id": 0,
        "name": "string"
      },
      "groups": [
        {
          "id": 0,
          "name": "string"
        }
      ],
      "date_invited": "2020-10-16T18:25:53.607Z",
      "date_redeemed": "2020-10-16T18:25:53.607Z",
      "display_name": "string",
      "time_zone": "string",
      "teams": [
        {
          "id": 0,
          "name": "string"
        }
      ],
      "owned_locations": []
  }

To retrieve an existing user without knowing it's Zenput's internal ID beforehand, the following URL parameter can be used:

  • email: This parameter will only match the email user attribute which is unique, this ensures that either 0 or 1 results will be retrieved.

    Usage: https://zenput.com/api/v3/users?email=example%40email.com

Creating users

To create a user, perform a POST request to /api/v3/users/, the payload to create a new user is:

POST /api/v3/users/

{
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "user_role": {
        "id": 0
    },
    "groups": [
        {
            "id": 0
        }
    ],
    "teams": [
        {
            "id": 0
        }
    ]
}
📘

Keep in mind

  • email must be unique
  • user_role and teams must already exist

Editing users

There are 2 ways of updating a user, using HTTP verb PUT to replace the entire record with the new data provided, and PATCH to update only the provided properties.

PUT /api/v3/users/<id>/

The payload data will replace the previous data that was stored for the given ID.

PATCH /api/v3/users/<id>/

The payload data will update only the provided properties from the user.

User Roles

Listing user roles

To get a list of user roles, perform a GET request to /api/v3/userroles/, this will return the following structure:

{
  "meta": {
    "status_code": 0,
    "count": 0,
    "next": "string",
    "previous": "string"
  },
  "data": [
    ...
  ]
}

data is an array of Roles, each role has the following structure:

{
    "id": 0,
    "name": "string",
    "parent": {
        "id": 0,
        "name": "string"
    },
    "children": [{
        "id": 0,
        "name": "string"
    }],
    "default_permission": {
        "id": 0,
        "name": "string"
    }
}

To retrieve an existing role without knowing it's Zenput's internal ID beforehand, name parameter can be used:

  • name: This parameter will match name user role attribute which is unique, this ensures that either 0 or 1 results will be retrieved.

    Usage: https://zenput.com/api/v3/userroles?name=Vice%20President

Creating roles

To create a role, perform a POST request to /api/v3/userroles/, the payload to create a new role is:

POST /api/v3/userroles/

{
    "name": "string",
    "default_permission": {
        "id": 0
    },
    "parent": {
        "id": 0
    }
}
📘

Keep in mind

  • name must be unique
  • parent is optional
  • default_permission and parent must already exist

Editing roles

There are 2 ways of updating a role, using HTTP verb PUT to replace the entire record with the new data provided, and PATCH to update only the provided properties.

PUT /api/v3/userroles/<id>/

The payload data will replace the previous data that was stored for the given ID.

PATCH /api/v3/userroles/<id>/

The payload data will update only the provided properties from the role.

Updated 2 months ago