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, usingsearch=221
may match a location withexternal_key=221
and another with221b Baker Street
address.Usage:
https://zenput.com/api/v3/locations?search=221
-
external_key
: This parameter will only match theexternal_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
andteams
items should exist already on Zenputexternal_key
must be unique across your companycountry
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 matchexternal_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 companyparent
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 theemail
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
user_role
andteams
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 matchname
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 uniqueparent
is optionaldefault_permission
andparent
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 over 2 years ago