Customers

Get the customer list

Get the list of customers for the current site.

Request

Response

An array of the first 10 customers; each object has the following properties:

The response is paginated, you can skip and limit the number if items retrieved. Also take a look at the API V3: sorting and filtering for additional switches you can use.

You can output additional fields to those listed above as default, see the API v3 Discovery APP for additional details.

Accepts and returns JSON as Content-Type.


Request:

GET /webresources/api/v3/sites/current/customers HTTPS/1.1
Authorization: 14f87f21c5ea4830a06a6314a8aad82b45bc61dc08f24a0fb55599cea83ca811
Connection: keep-alive
Content-Type: application/json

Response:

{
  "items": [
    {
      "id": 7051740,
      "siteId": 38581,
      "customerTypeId": 287044,
      "leadSourceTypeId": 318173,
      "industryTypeId": 743915,
      "ratingTypeId": 85977,
      "titleTypeId": 249385,
      "firstName": "Doe",
      "middleName": "Manny",
      "lastName": "John",
      "company": "",
      "dateOfBirth": "1982-12-06T23:00:00",
      "username": "",
      "createDate": "2015-02-20T14:51:26.23",
      "lastUpdateDate": "2015-02-20T14:51:26.23",
      "wholesaler": false
    },
    {
      "id": 7051757,
      "siteId": 38581,
      "customerTypeId": 287049,
      "leadSourceTypeId": 318175,
      "industryTypeId": 743939,
      "ratingTypeId": 85979,
      "titleTypeId": 249385,
      "firstName": "Usernov",
      "middleName": "Paolonov",
      "lastName": "Mihaiel",
      "company": "",
      "dateOfBirth": "",
      "username": "mbol",
      "createDate": "2015-02-20T14:51:26.23",
      "lastUpdateDate": "2015-02-20T14:51:26.23",
      "wholesaler": false
    }
  ],
  "totalItemsCount": 2,
  "skip": 0,
  "limit": 10
}

Sample code

Get the list of customers for a site

var access_token = BCAPI.Helper.Site.getAccessToken();
//the authorization token is now stored in the access_token cookie, we will need to pass it in the "Authorization" header

var request = $.ajax({
    url: "/webresources/api/v3/sites/current/customers",
    type: "GET",
    connection: "keep-alive",    
    contentType: "application/json",
    mimeType: "application/json ",
    headers: {
        "Authorization": $.cookie('access_token')

    }
});
request.done(function (msg) {
    console.log(msg);
})
request.fail(function (jqXHR) {
    console.log("Request failed.");
    console.log("Error code: " + jqXHR.status);
    console.log("Error text: " + jqXHR.statusText);
    console.log("Response text: " + jqXHR.responseText);
})

Get the list of customers - this only includes the specified fields:

var access_token = BCAPI.Helper.Site.getAccessToken();
//the authorization token is now stored in the access_token cookie, we will need to pass it in the "Authorization" header

var request = $.ajax({
    url: "/webresources/api/v3/sites/current/customers?fields=email1,email2,email3,homeFax,mobilePhone,pager,webAddress,workFax,workPhone,anniversary,titleType,ratingType,leadSourceType,industryType,customerType",
    type: "GET",
    connection: "keep-alive",    
    contentType: "application/json",
    mimeType: "application/json ",
    headers: {
        "Authorization": $.cookie('access_token')
    }
});
request.done(function (msg) {
    console.log(msg);
})
request.fail(function (jqXHR) {
    console.log("Request failed.");
    console.log("Error code: " + jqXHR.status);
    console.log("Error text: " + jqXHR.statusText);
    console.log("Response text: " + jqXHR.responseText);
})

In this case the response looks like this:

{
  "items": [
    {
      "email1": {
        "id": 8489222,
        "siteId": 38581,
        "value": "john.doe.1@mail.com",
        "deleted": false,
        "customerId": 7051740,
        "default": true
      },
      "email2": {},
      "email3": {},
      "homeFax": {},
      "mobilePhone": {},
      "pager": {},
      "webAddress": {
        "id": 8489224,
        "siteId": 38581,
        "value": "johndoerepairs.com",
        "deleted": false,
        "customerId": 7051740,
        "default": false
      },
      "workFax": {},
      "workPhone": {},
      "anniversary": {
        "customerId": 7051740,
        "siteId": 38581,
        "anniversary1": "1993-09-01T07:00:00",
        "anniversary1Title": "Birth",
        "anniversary2": "2013-12-31T08:00:00",
        "anniversary2Title": "New year!",
        "anniversary3": "2014-08-01T07:00:00",
        "anniversary3Title": "Mom's birthday",
        "anniversary4": null,
        "anniversary4Title": "",
        "anniversary5": null,
        "anniversary5Title": ""
      },
      "titleType": {
        "id": 249385,
        "siteId": 38581,
        "titleType": "MR",
        "default": true
      },
      "ratingType": {
        "id": 85977,
        "siteId": 38581,
        "ratingType": "Hot",
        "default": false
      },
      "leadSourceType": {
        "id": 318173,
        "siteId": 38581,
        "leadSourceType": "Web",
        "default": false
      },
      "industryType": {
        "id": 743915,
        "siteId": 38581,
        "industryType": "Aerospace & Defence",
        "default": true
      },
      "customerType": {
        "id": 287044,
        "siteId": 38581,
        "customerType": "Analyst",
        "default": false
      }
    },
    {
      "email1": {},
      "email2": {},
      "email3": {},
      "homeFax": {},
      "mobilePhone": {
        "id": 8489223,
        "siteId": 38581,
        "value": "0244154154",
        "deleted": false,
        "customerId": 7051757,
        "default": true
      },
      "pager": {},
      "webAddress": {},
      "workFax": {},
      "workPhone": {},
      "anniversary": {},
      "titleType": {
        "id": 249385,
        "siteId": 38581,
        "titleType": "MR",
        "default": true
      },
      "ratingType": {
        "id": 85979,
        "siteId": 38581,
        "ratingType": "Cold",
        "default": false
      },
      "leadSourceType": {
        "id": 318175,
        "siteId": 38581,
        "leadSourceType": "Other",
        "default": true
      },
      "industryType": {
        "id": 743939,
        "siteId": 38581,
        "industryType": "Other",
        "default": false
      },
      "customerType": {
        "id": 287049,
        "siteId": 38581,
        "customerType": "Other",
        "default": true
      }
    }
  ],
  "totalItemsCount": 2,
  "skip": 0,
  "limit": 10
}

Get a customer's details

Get a particular customer by ID.

Request

Response

The details for the specified customer ID in JSON format.

The response is paginated, you can return only a few of the customer's fields. Take a look at the API V3: sorting and filtering for additional switches you can use.

Accepts and returns JSON as Content-Type.


Request:

GET /webresources/api/v3/sites/current/customers/7051740 HTTPS/1.1
Authorization: 14f87f21c5ea4830a06a6314a8aad82b45bc61dc08f24a0fb55599cea83ca811
Connection: keep-alive
Content-Type: application/json

Response:

{
    "customerId": 7051740,
    "siteId": 38581,
    "customerTypeId": 287044,
    "leadSourceTypeId": 318173,
    "industryTypeId": 743915,
    "ratingTypeId": 85977,
    "titleTypeId": 249385,
    "firstName": "Doe",
    "middleName": "Manny",
    "lastName": "John",
    "company": "",
    "dateOfBirth": "1982-12-06T23:00:00",
    "createDate": "2015-02-20T14:51:26.23",
    "lastUpdateDate": "2015-02-20T14:51:26.23",
    "username": "",
    "wholesaler": false
}

Sample code

Get the details of customer

var access_token = BCAPI.Helper.Site.getAccessToken();
//the authorization token is now stored in the access_token cookie, we will need to pass it in the "Authorization" header

var request = $.ajax({
    url: "/webresources/api/v3/sites/current/customers/7051740",
    type: "GET",
    connection: "keep-alive",    
    contentType: "application/json",
    mimeType: "application/json ",
    headers: {
        "Authorization": $.cookie('access_token')
    }
});
request.done(function (msg) {
    console.log(msg);
})
request.fail(function (jqXHR) {
    console.log("Request failed.");
    console.log("Error code: " + jqXHR.status);
    console.log("Error text: " + jqXHR.statusText);
    console.log("Response text: " + jqXHR.responseText);
})

Get the details of a customer - this only includes the specified fields:

var access_token = BCAPI.Helper.Site.getAccessToken();
//the authorization token is now stored in the access_token cookie, we will need to pass it in the "Authorization" header

var request = $.ajax({
    url: "/webresources/api/v3/sites/current/customers/7051740?fields=email1,email2,email3,homeFax,mobilePhone,pager,webAddress,workFax,workPhone,anniversary,titleType,ratingType,leadSourceType,industryType,customerType",
    type: "GET",
    connection: "keep-alive",    
    contentType: "application/json",
    mimeType: "application/json ",
    headers: {
        "Authorization": $.cookie('access_token')
    }
});
request.done(function (msg) {
    console.log(msg);
})
request.fail(function (jqXHR) {
    console.log("Request failed.");
    console.log("Error code: " + jqXHR.status);
    console.log("Error text: " + jqXHR.statusText);
    console.log("Response text: " + jqXHR.responseText);
})

Get a customer by email address

For this example we will add the email address field to the output and add a filtering condition. Take a look at this

var access_token = BCAPI.Helper.Site.getAccessToken();
//the authorization token is now stored in the access_token cookie, we will need to pass it in the "Authorization" header

var request = $.ajax({
  url: '/webresources/api/v3/sites/current/customers?fields=email1,middleName,firstName,lastName&where={"email1.value":"mtest@mailinator.com"}',
  type: "GET",
  connection: "keep-alive",    
    contentType: "application/json",
    mimeType: "application/json ",
  headers: {
    "Authorization": $.cookie('access_token')
  }
});
request.done(function(msg) {
  $('.output pre').html(JSON.stringify(msg))
  console.log(msg);
})
request.fail(function(jqXHR) {
  console.log("Request failed.");
  console.log("Error code: " + jqXHR.status);
  console.log("Error text: " + jqXHR.statusText);
  console.log("Response text: " + jqXHR.responseText);
})

In this case the response is a single CRM entry and looks like this:

{
  "items": [{
    "email1": {
      "id": 11520864,
      "siteId": 146985,
      "phoneNumberTypeId": 7,
      "objectId": 9532870,
      "objectType": 1001,
      "value": "mtest@mailinator.com",
      "default": true
    },
    "middleName": "Mtest C",
    "firstName": "Mtest B",
    "lastName": "Mtest A"
  }],
  "totalItemsCount": 1,
  "skip": 0,
  "limit": 10
}

Get a customer by username

var access_token = BCAPI.Helper.Site.getAccessToken();
//the authorization token is now stored in the access_token cookie, we will need to pass it in the "Authorization" header

var request = $.ajax({
    url: '/webresources/api/v3/sites/current/customers?where={"username":"myUsername"}',
  type: "GET",
  connection: "keep-alive",    
    contentType: "application/json",
    mimeType: "application/json ",
  headers: {
    "Authorization": $.cookie('access_token')
  }
});
request.done(function(msg) {
  $('.output pre').html(JSON.stringify(msg))
  console.log(msg);
})
request.fail(function(jqXHR) {
  console.log("Request failed.");
  console.log("Error code: " + jqXHR.status);
  console.log("Error text: " + jqXHR.statusText);
  console.log("Response text: " + jqXHR.responseText);
})

In this case the response is a single CRM entry and looks like this:

{
  "items": [{
    "id": 9339548,
    "siteId": 146985,
    "customerTypeId": 420538,
    "leadSourceTypeId": 465473,
    "industryTypeId": 1090438,
    "ratingTypeId": 126400,
    "titleTypeId": 317597,
    "firstName": "New_user",
    "middleName": "",
    "lastName": "New_user",
    "company": "",
    "username": "myUsername"
    "createDate": "2015-02-20T14:51:26.23",
    "lastUpdateDate": "2015-02-20T14:51:26.23",
  }],
  "totalItemsCount": 1,
  "skip": 0,
  "limit": 10
}

Create a customer

Create a new customer.

Request

Parameters

Response

Returns an empty body if successful or a detailed error message.

Accepts and returns JSON as Content-Type.


Request:

POST /webresources/api/v3/sites/current/customers HTTPS/1.1
Authorization: 14f87f21c5ea4830a06a6314a8aad82b45bc61dc08f24a0fb55599cea83ca811
Connection: keep-alive
Content-Type: application/json


{
  "customerTypeId": 287049,
  "leadSourceTypeId": 318175,
  "industryTypeId": 743939,
  "ratingTypeId": 85979,
  "titleTypeId": 249385,
  "firstName": "Michael",
  "middleName": "Jennar",
  "lastName": "Boston",
  "username": "mbo1",
  "homeFax": "123",
  "workFax": "123",
  "workPhone": "123",
  "anniversary": {
    "anniversary1Title": "Birthday",
    "anniversary1": "2014-02-03T23:00:00"
  },
  "email1": {
    "value": "john.doe1@mailinator.com",
    "default": true
  },
  "email2": {
    "value": "john.doe2@mailinator.com",
    "default": false
  },
  "email3": {
    "value": "john.doe13@mailinator.com",
    "default": false
  }
}

Response:

HTTP/1.1 201 CREATED
Location: /webresources/api/v3/sites/current/customers
Content-Type: application/json; charset=utf-8
Content-Length: length

Sample code

Create a new customer

var access_token = BCAPI.Helper.Site.getAccessToken();
//the authorization token is now stored in the access_token cookie, we will need to pass it in the "Authorization" header

var request = $.ajax({
url: "/webresources/api/v3/sites/current/customers",
type: "POST",
connection: "keep-alive",    
    contentType: "application/json",
    mimeType: "application/json ",
processData: false,
headers: {
    "Authorization": $.cookie('access_token'),
  
},
  data: JSON.stringify({
        "titleTypeId": 3054302,
        "firstName": "Michael",
        "middleName": "John",
        "lastName": "Doe",
        "username": "MichaelD",
        "anniversary": {
            "anniversary1Title": "Birthday",
            "anniversary1": "1980-02-03"
        },
        "email1": {
            "value": "mdoe@mailinator.com",
            "default": true
        }
    })
});
request.done(function(msg) {
console.log(msg);
})
request.fail(function(jqXHR) {
console.log("Request failed.");
console.log("Error code: " + jqXHR.status);
console.log("Error text: " + jqXHR.statusText);
console.log("Response text: " + jqXHR.responseText);
})

Edit a customer's details

Edit the details for an existing customer record.

Request

Parameters

Response

Returns an empty body if successful or a detailed error message.

Accepts and returns JSON as Content-Type.


Request:

PUT /webresources/api/v3/sites/current/customers HTTPS/1.1
Authorization: 14f87f21c5ea4830a06a6314a8aad82b45bc61dc08f24a0fb55599cea83ca811
Connection: keep-alive
Content-Type: application/json


{
  "customerTypeId": 287049,
  "leadSourceTypeId": 318175,
  "industryTypeId": 743939,
  "ratingTypeId": 85979,
  "titleTypeId": 249385,
  "firstName": "Michael",
  "middleName": "Jennar",
  "lastName": "Boston",
  "username": "mbo1",
  "homeFax": "123",
  "workFax": "123",
  "workPhone": "123",
  "anniversary": {
    "anniversary1Title": "Birthday",
    "anniversary1": "1980-02-03"
  },
  "email1": {
    "value": "john.doe1@mailinator.com",
    "default": true
  },
  "email2": {
    "value": "john.doe2@mailinator.com",
    "default": false
  },
  "email3": {
    "value": "john.doe13@mailinator.com",
    "default": false
  }
}

Response:


HTTP/1.1 204 NO CONTENT
Location: /webresources/api/v3/sites/current/customers/[customer_ID]
Content-Type: application/json; charset=utf-8
Content-Length: length

Sample code

Edit a customer's name and e-mail address

var access_token = BCAPI.Helper.Site.getAccessToken();
//the authorization token is now stored in the access_token cookie, we will need to pass it in the "Authorization" header

var request = $.ajax({
url: "/webresources/api/v3/sites/current/customers/9593213",
type: "PUT",
connection: "keep-alive",    
    contentType: "application/json",
    mimeType: "application/json ",
headers: {
    "Authorization": $.cookie('access_token')
},
processData: false,
data: JSON.stringify({
    "firstName": "Michael",
    "lastName": "Smith",
    "email1": {
        "value": "mdoe@mailinator.com",
        "default": true
     }
})
});
request.done(function(msg) {
console.log(msg);
})
request.fail(function(jqXHR) {
console.log("Request failed.");
console.log("Error code: " + jqXHR.status);
console.log("Error text: " + jqXHR.statusText);
console.log("Response text: " + jqXHR.responseText);
})

Get a customer by email address and edit its details

var access_token = BCAPI.Helper.Site.getAccessToken();
//the authorization token is now stored in the access_token cookie, we will need to pass it in the "Authorization" header

var request = $.ajax({
  url: '/webresources/api/v3/sites/current/customers?fields=email1&where={"email1.value":"mtest@mailinator.com"}',
  type: "GET",
  connection: "keep-alive",    
    contentType: "application/json",
    mimeType: "application/json ",
  headers: {
    "Authorization": $.cookie('access_token')
  }
});
request.done(function(msg) {

//now that we have the CRM ID that belongs to the user with the email address mtest@mailinator.com we can edit its properties:

          var access_token = BCAPI.Helper.Site.getAccessToken();
//the authorization token is now stored in the access_token cookie, we will need to pass it in the "Authorization" header

var request = $.ajax({
          url: "/webresources/api/v3/sites/current/customers/" + msg.items[0].email1.value,
          type: "PUT",
          connection: "keep-alive",    
    contentType: "application/json",
    mimeType: "application/json ",
          headers: {
              "Authorization": $.cookie('access_token')
          },
          processData: false,
          data: JSON.stringify({
              "firstName": "Michael",
              "lastName": "Smith",
              "email1": {
                  "value": "mdoe@mailinator.com",
                  "default": true
               }
          })
          });
          request.done(function(msg) {
          console.log(msg);
          })
          request.fail(function(jqXHR) {
          console.log("Request failed.");
          console.log("Error code: " + jqXHR.status);
          console.log("Error text: " + jqXHR.statusText);
          console.log("Response text: " + jqXHR.responseText);
          })


})
request.fail(function(jqXHR) {
  console.log("Request failed.");
  console.log("Error code: " + jqXHR.status);
  console.log("Error text: " + jqXHR.statusText);
  console.log("Response text: " + jqXHR.responseText);
})

Delete a customer record

Delete a CRM record.

Request

Response

Returns an empty body if successful or a detailed error message.

Accepts and returns JSON as Content-Type.


Request:

DELETE /webresources/api/v3/sites/current/customers/9593213 HTTPS/1.1
Authorization: 14f87f21c5ea4830a06a6314a8aad82b45bc61dc08f24a0fb55599cea83ca811
Connection: keep-alive
Content-Type: application/json

Response:


HTTP/1.1 204 NO CONTENT
Location: /webresources/api/v3/sites/current/customers/[customer_ID]
Content-Type: application/json; charset=utf-8
Content-Length: length

Sample code

Delete a CRM address by ID

var access_token = BCAPI.Helper.Site.getAccessToken();
//the authorization token is now stored in the access_token cookie, we will need to pass it in the "Authorization" header

var request = $.ajax({
    url: "/webresources/api/v3/sites/current/customers/9593213",
    type: "DELETE",
    connection: "keep-alive",    
    contentType: "application/json",
    mimeType: "application/json ",
    headers: {
        "Authorization": $.cookie('access_token')
    }
});
request.done(function(msg) {
    console.log(msg);
})
request.fail(function(jqXHR) {
    console.log("Request failed.");
    console.log("Error code: " + jqXHR.status);
    console.log("Error text: " + jqXHR.statusText);
    console.log("Response text: " + jqXHR.responseText);
})

In this example we will first get a CRM entity by email address, get its ID and then delete it:

var access_token = BCAPI.Helper.Site.getAccessToken();
//the authorization token is now stored in the access_token cookie, we will need to pass it in the "Authorization" header

var request = $.ajax({
  url: '/webresources/api/v3/sites/current/customers?fields=id,email1,middleName,firstName,lastName&where={"email1.value":"new_user123123@mailinator.com"}',
  type: "GET",
  connection: "keep-alive",    
    contentType: "application/json",
    mimeType: "application/json ",
  headers: {
    "Authorization": $.cookie('access_token')
  }
});
request.done(function(msg) {

//now we have the CRM record we need to delete, bwlow we'll run a DELETE request and pass the CRM record's ID:

          var access_token = BCAPI.Helper.Site.getAccessToken();
//the authorization token is now stored in the access_token cookie, we will need to pass it in the "Authorization" header

var request = $.ajax({
            url: "/webresources/api/v3/sites/current/customers/" + msg.items[0].id,
            type: "DELETE",
            connection: "keep-alive",    
   	      contentType: "application/json",
  		  mimeType: "application/json ",
            headers: {
              "Authorization": $.cookie('access_token')
            }
          });
          request.done(function(msg) {
            console.log(msg);
          })
          request.fail(function(jqXHR) {
            console.log("Request failed.");
            console.log("Error code: " + jqXHR.status);
            console.log("Error text: " + jqXHR.statusText);
            console.log("Response text: " + jqXHR.responseText);
          })

})
request.fail(function(jqXHR) {
  console.log("Request failed.");
  console.log("Error code: " + jqXHR.status);
  console.log("Error text: " + jqXHR.statusText);
  console.log("Response text: " + jqXHR.responseText);
})