Skip to content

Customers

Customers are who you complete jobs for. You can specify a customer's first and last name, phone number, contact details, and billing information. The following web services can be used to create, update, delete and search for customers within vWork.

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

NameTypeDescription
nameStringThe customer's name. Can be either a person's full name or an organization's name.
third_party_idStringA user defined ID for this customer. Although it's not required, this ID should be unique. If you do not supply one, vWork will create one.
notesStringA text entry for notes about this customer.
delivery_contactThe address and contact details for visiting the customer.
delivery_contact.first_nameStringThe contact's first name.
delivery_contact.last_nameStringThe contact's last name.
delivery_contact.phoneStringThe contact's phone number.
delivery_contact.mobileStringThe contact's mobile phone number. (Be sure to include the country code.)
delivery_contact.emailStringThe contact's email address.
delivery_location.formatted_addressStringThe formatted address of this location.
delivery_location.latDecimalThe latitude of the location.
delivery_location.lngDecimalThe longitude of the location.
billing_contactThe address and contact details for billing the customer.
billing_contact.first_nameStringThe contact's first name.
billing_contact.last_nameStringThe contact's last name.
billing_contact.phoneStringThe contact's phone number.
billing_contact.mobileStringThe contact's mobile phone number. (Be sure to include the country code.)
billing_contact.emailStringThe contact's email address.
billing_location.formatted_addressStringThe formatted address of this location.
billing_location.latDecimalThe latitude of the location.
billing_location.lngDecimalThe longitude of the location.

When retrieving a customer from vWork, you may also see these additional fields in the response:

NameTypeDescription
idIntegerUnique ID of customer.
created_atDateTimeTime customer was created.
updated_atDateTimeTime customer was last updated.
deleted_atDateTimeTime customer was deleted. (will be blank as deleted customers are not available via the API.)
Operations

Create A New Customer

Request

Creates a new customer in vWork. Customers can have a third_party_id set. This is useful for passing through an external id, such as from a CRM.

Security
apiKey
Query
api_keystringrequired
Headers
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/customers.xml
curl -i -X POST \
  'https://api.vworkapp.com/v5/customers.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"?>
  <customer>
      <name>Joe'\''s Plumbing</name>
      <third_party_id>ABC123</third_party_id>
      <notes/>
      <delivery_contact>
          <first_name>Cathy</first_name>
          <last_name>Knocks</last_name>
          <phone>1 555 111 1111</phone>
          <mobile>1 555 111 1111</mobile>
          <email>joe@acmeplumbers.com</email>
          <location>
              <formatted_address>880 Harrison Street, San Francisco, CA, 94107</formatted_address>
              <lat>-37.779536</lat>
              <lng>-122.401503</lng>
          </location>
      </delivery_contact>
      <billing_contact>
          <first_name>Bob</first_name>
          <last_name>Lei</last_name>
          <phone>1 555 111 1111</phone>
          <location>
              <formatted_address>880 Harrison Street, San Francisco, CA, 94107</formatted_address>
              <lat>-37.779536</lat>
              <lng>-122.401503</lng>
          </location>
      </billing_contact>
  </customer>'

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 22:51:25 GMT"
ETagstring
Example:"W/\"4af298ed89390aecf7df64e20427d6ad\""
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:"52b7672b-d4fe-4ec8-88d7-e1bf8271e139"
X-Runtimestring
Example:"0.265632"
X-Unique-IDstring
Example:"CA7C7B8A:CBEF_0A001312:01BB_575F38C6_719C90:1E66"
X-XSS-Protectionstring
Example:"1; mode=block"
Bodyapplication/xml; charset=utf-8
string

Raw XML payload — see the example.

Response
<?xml version="1.0" encoding="utf-8"?>
<customer>
    <id>1119086</id>
    <name>Joe's Plumbing</name>
    <notes/>
    <third_party_id>ABC123</third_party_id>
    <billing_contact>
        <first_name>Bob</first_name>
        <last_name>Lei</last_name>
        <phone>1 555 111 1111</phone>
        <mobile/>
        <email/>
        <location>
            <id type="integer">23839050</id>
            <created_at type="datetime" readonly="readonly">2016-06-13T22:51:25+00:00</created_at>
            <updated_at type="datetime" readonly="readonly">2016-06-13T22:51:25+00:00</updated_at>
            <address1/>
            <address2/>
            <suburb/>
            <city/>
            <post_code/>
            <country/>
            <province/>
            <region/>
            <state/>
            <formatted_address>880 Harrison Street, San Francisco, CA, 94107</formatted_address>
            <lat type="decimal">-37.779536</lat>
            <lng type="decimal">-122.401503</lng>
          …