Users

The users API route allows you to control all vWork users (either mobile workers, dispatchers or admins). Users can be workers using the vWork mobile app or dispatchers using the vWork website. The following web services can be used to create, update, delete and search for users within vWork.

Here are the fields you can use when making a user request:

Name	Type	Description
name	String	Unique name of user, cannot be blank.
third_party_id	String	Your unique ID for the user. (optional)
email	String	Unique email of user, cannot be blank.
phone	String	Mobile phone number of user. (Be sure to include the country code)
notes	String	Ancillary information about the user. (optional)
password	String	Password of user (Please refer to the tech note regarding password strength at the top of this doc).
group_ids	String	Comma-separated list of ids of groups this user shall be a member of. (optional)
permissions	Array	Array of permissions that allow the user to access various parts of vWork

When retrieving a user from vWork, you may also see these additional fields in the response. (Depending on what optional features are enabled on your account, you may also see: tags, capacity, start location or end location. More information on these options are available further down this document under the route optimisation and health and safety headings)

Name	Type	Description
id	Integer	The unique ID of the user.
updated_at	DateTime	Time user was last updated.
created_at	DateTime	Time user was created.
latest_telemetry	Object	Latest telemetry for user.
heading	Decimal	Direction (angle) the user is heading to.
lat	Decimal	Latitude.
lng	Decimal	Longitude.
recorded_at	DateTime	Point of time when telemetry was recorded.
speed	Decimal	Speed in kilometers per hour (km/h).
shift_on	Boolean	Is the worker currently on shift.

Permissions

A user in vWork can be granted access to certain areas and actions by using the following permissions:

Name	Available Permissions	Description
jobs	full, none, read	Allows the user to access the jobs tab on the vWork website.
schedule	full, none, read	Allows the user to access the schedule tab on the vWork website.
map	full, none, read	Allows the user to access the map tab on the vWork website.
reports	full, none	Allows the user to access the reports tab on the vWork website.
customers	full, none, read	Allows the user to access the customers tab on the vWork website.
equipment	full, none, read	Allows the user to access the equipment tab on the vWork website if the equipment module is enabled for the account.
quotes	full, none, read	Allows the user to access the quotes tab on the vWork website if the quotes module is enabled for the account. (Also allows the user to create quotes from the mobile device when combined with mobile_jobs_create.)
messaging	full, none	Allows the user to access the messaging tab on the vWork website. (Also allows all mobile users to message users with this permission.)
admin	full, none	Allows full administration of the vWork account, content and settings.
mobile	full, none	This permission enables the worker to use the mobile application. This must be set to full for the worker to use the vWork mobile apps. If any of the other mobile permissions are enabled this will be set to 'full' automatically.
mobile_jobs_create	full, none	This permission allows the worker to create jobs using the mobile application, setting create will enable mobile automatically.
mobile_jobs_assign	full, none	This permission allows the worker to assign jobs using the mobile application, setting assign will enable mobile and create automatically.
mobile_invoice	full, none, read	This permission allows the worker to work with invoices using the mobile application.

Operations

Create A New User

Request

Creates a new user in vWork.

Security

apiKey

Query

api_keystringrequired

Accept-Encodingstringrequired

Must be gzip. The vWork API requires HTTP compression on all requests; requests without it may be rejected with 406 Not Acceptable (see Tech Notes → HTTP Compression).

Value:"gzip"

Example:gzip

Bodyapplication/xml; charset=utf-8

string

Raw XML payload — see the example.

POST

/v5/users.xml

curl -i -X POST \
  'https://api.vworkapp.com/v5/users.xml?api_key=string&api_key=YOUR_API_KEY_HERE' \
  -H 'Accept-Encoding: gzip' \
  -H 'Content-Type: application/xml; charset=utf-8' \
  -d '<?xml version="1.0" encoding="utf-8"?>
  <user>
  <name>George Smith</name>
  <group_ids></group_ids>
  <third_party_id></third_party_id>
  <email>george@example.com</email>
  <phone>1 555 111 1111</phone>
  <notes>Mack 3DC 12L V-TEC</notes>
  <password>fvw234r32qvrqe</password>
      <permissions>
          <admin>none</admin>
          <schedule>none</schedule>
          <map>none</map>
          <reports>none</reports>
          <jobs>none</jobs>
          <customers>none</customers>
          <quotes>none</quotes>
          <equipment>none</equipment>
          <messaging>none</messaging>
          <mobile>full</mobile>
          <mobile_jobs_create>full</mobile_jobs_create>
          <mobile_jobs_assign>full</mobile_jobs_assign>
          <mobile_invoice>full</mobile_invoice>
      </permissions>
  </user>'

Responses

Created

Headers

Cache-Controlstring

Example:"max-age=0, private, must-revalidate"

Content-Security-Policystring

Example:"frame-ancestors *.vworkapp.com *.vwork.io *.visfleet.com *.salesforce.com *.zoho.com, default-src: google.com google-analytics.com googleapis.com gst

Datestring

Example:"Mon, 13 Jun 2016 23:39:38 GMT"

ETagstring

Example:"W/\"2dbcb6a04f44419e584b939d643b66f1\""

Statusstring

Example:"201 Created"

Strict-Transport-Securitystring

Example:"max-age=31536000"

Transfer-Encodingstring

Example:"chunked"

X-Content-Type-Optionsstring

Example:"nosniff"

X-Frame-Optionsstring

Example:"SAMEORIGIN"

X-Request-Idstring

Example:"c984cbfd-2df1-4010-bad2-d5ef1e4d5412"

X-Runtimestring

Example:"0.586222"

X-Unique-IDstring

Example:"CA7C7B8A:CD56_0A000ED8:01BB_575F4426_6E78F2:1EB6"

X-XSS-Protectionstring

Example:"1; mode=block"