Customer

  • 15.5
This article is may not be up to date with the latest stable release of M4.

Description

The Customer endpoint provides the API consumer with access to methods pertaining to customers and related data objects. The methods allow consumers to pull data and add, update, and delete customers.

Methods

URL base/Billing/Customer/Specification
Action GET
Description Returns a data dictionary that details the available web service methods related to the Customer controller.
Parameters None
 Returns  A JSON object with method descriptions
Sample Return Object 
[
    {
        "HttpAction": "Get",
        "MethodName": "GetCustomer",
        "Description": "Returns the record for a single Customer given the passed in ID value (see Path).",
        "Path": "/Customer/GetCustomer/25032"
    },
    {
        "HttpAction": "Post",
        "MethodName": "GetCustomerBySourceID",
        "Description": "Returns the record for a single Customer given the SourceID and SourceTable. Both are required fields.",
        "Format": {
            "SourceID": 2147,
            "SourceTable": "ClientTable"
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "GetCustomersByPhoneNumber",
        "Description": "Returns a list of Customers given the contact phone number.  The phone number is a required field.",
        "Format": {
            "PhoneNumber": "2344234439"
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "GetCustomerByServicePhoneNumber",
        "Description": "Returns the record for a single Customer given the service phone number.  The phone number is a required field.",
        "Format": {
            "PhoneNumber": "2344234439"
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "GetCustomersByName",
        "Description": "Returns a list of customers that match the given name.  At least one of the fields in the payload must be specified -- i.e. FirstName, LastName or both fields can be specified, but both fields cannot be null/empty.  The name specified will be treated as a wildcard search, so searching on the last name of 'Smith' will return entries with 'Smith', 'Smithville' and 'Smithe'.",
        "Format": {
            "Name": "Washington & Co.",
            "FirstName": "John",
            "LastName": "Washington"
        }
    },
    {
        "HttpAction": "Get",
        "MethodName": "GetStructures",
        "Description": "Returns all associated structures for a single Customer given the passed in ID value (see Path).",
        "Path": "/Customer/GetStructures/25032"
    },
    {
        "HttpAction": "Post",
        "MethodName": "AddCustomer",
        "Description": "Adds a new Customer to the database using the specified format.  While the StructureIDList is optional, if it is included, that list of structures will be associated with the customer.",
        "Format": {
            "UserID": 125,
            "CustomerNumber": "SK45792",
            "Name": "Jack Johnson",
            "FirstName": "Jack",
            "LastName": "Johnson",
            "MiddleName": "Griffin",
            "Phone": "804-123-4567",
            "Email": "jack.johnson@sampledomain.com",
            "MailingAddress": "1234 Palm Tree Drive, Sample City, VA 23236",
            "MailingCity": "Sample City",
            "MailingState": "VA",
            "MailingCountry": "United States",
            "MailingPostalCode": "23236",
            "MailingStreet": "1234 Palm Tree Drive",
            "BillingAddress": "1234 Palm Tree Drive, Sample City, VA 23236",
            "BillingCity": "Sample City",
            "BillingCountry": "United States",
            "BillingPostalCode": "23236",
            "BillingState": "VA",
            "BillingStreet": "1234 Palm Tree Drive",
            "Description": "Sample comments or description",
            "CustomerType": "B",
            "SourceTable": "ClientTable",
            "SourceID": 4758,
            "StructureIDList": [
                25,
                78,
                132,
                45
            ]
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "UpdateCustomer",
        "Description": "Updates an existing customer in the database using the specified format.",
        "Format": {
            "ID": 45,
            "UserID": 125,
            "CustomerNumber": "SK45792",
            "Name": "Jack Johnson",
            "FirstName": "Jack",
            "LastName": "Johnson",
            "MiddleName": "Griffin",
            "Phone": "804-123-4567",
            "Email": "jack.johnson@sampledomain.com",
            "MailingAddress": "1234 Palm Tree Drive, Sample City, VA 23236",
            "MailingCity": "Sample City",
            "MailingState": "VA",
            "MailingCountry": "United States",
            "MailingPostalCode": "23236",
            "MailingStreet": "1234 Palm Tree Drive",
            "BillingAddress": "1234 Palm Tree Drive, Sample City, VA 23236",
            "BillingCity": "Sample City",
            "BillingCountry": "United States",
            "BillingPostalCode": "23236",
            "BillingState": "VA",
            "BillingStreet": "1234 Palm Tree Drive",
            "Description": "Sample comments or description",
            "CustomerType": "B",
            "SourceTable": "ClientTable",
            "SourceID": 4758
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "RemoveCustomer",
        "Description": "Deletes an existing customer in the database.",
        "Format": {
            "ID": 45
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "ReactivateCustomer",
        "Description": "Reactivates a customer that is flagged as deleted.",
        "Format": {
            "ID": 1
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "LinkStructures",
        "Description": "Link Structures to Customer Service using customer Service ID.",
        "Format": {
            "ID": 45,
            "StructureIDList": [
                25,
                48,
                73,
                12
            ]
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "UnlinkStructures",
        "Description": "Unlink Structures to Customer Service using customer Service ID.",
        "Format": {
            "ID": 45,
            "StructureIDList": [
                25,
                48,
                73,
                12
            ]
        }
    }
]
URL base/Billing/Customer/GetCustomer/ID
Action GET
Description Returns a Customer object when given an ID of a valid customer in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a customer in the M4 database.
Returns A JSON Structure data object
Sample Return Object 
{
  "ID": 125,
  "UserID": null,
  "CustomerNumber": "B0B626F0-D12B-4F38-8AC9-106AE6936DB1",
  "Name": "",
  "FirstName": "Victor",
  "LastName": "Torres",
  "MiddleName": "",
  "Phone": "",
  "Email": "",
  "MailingAddress": "2874 OLD MEMORIAL DR",
  "MailingCity": "DEMOVILLE",
  "MailingState": "VA",
  "MailingCountry": "USA",
  "MailingPostalCode": "",
  "MailingStreet": "VA",
  "BillingAddress": "",
  "BillingCity": "",
  "BillingCountry": "",
  "BillingPostalCode": "",
  "BillingState": "",
  "BillingStreet": "",
  "Description": "",
  "CustomerType": "B",
  "SourceTable": "",
  "SourceID": null,
  "IsDeleted": false,
  "CreateDate": "2016-11-29T16:53:03.137",
  "LastUpdatedDate": "2017-01-30T12:56:20.243"
}
URL base/Billing/Customer/GetCustomerBySourceID
Action POST
Description Returns a Customer object of a valid customer in the M4 database with Source ID and Source Table values.
Parameters
Name Required? Type Description
SourceID Yes Integer The Source ID from the Source table.
SourceTable Yes String The Source Table referenced by the Source ID.
Sample JSON Package 
{
      "SourceID": 4758,
      "SourceTable": "Additional Field Data"
}
Returns A JSON Customer data object.
Sample Return Object 
{
  "ID": 45,
  "UserID": null,
  "CustomerNumber": "SK45792",
  "Name": "",
  "FirstName": "Jack",
  "LastName": "Johnson",
  "MiddleName": "Griffin",
  "Phone": "804-123-4567",
  "Email": "",
  "MailingAddress": "",
  "MailingCity": "",
  "MailingState": "",
  "MailingCountry": "",
  "MailingPostalCode": "",
  "MailingStreet": "",
  "BillingAddress": "",
  "BillingCity": "",
  "BillingCountry": "",
  "BillingPostalCode": "",
  "BillingState": "",
  "BillingStreet": "",
  "Description": "",
  "CustomerType": "B",
  "SourceTable": "Additional Field Data",
  "SourceID": 4758,
  "IsDeleted": false,
  "CreateDate": "2016-11-29T16:53:03.137",
  "LastUpdatedDate": "2017-01-30T12:07:24.05"
}
Business Rules
  • SourceID/SourceTable:
    • The SourceID and SourceTable fields are fields that work in tandem. Both can be ignored (by setting the value to null) or both can be specified.
    • If SourceID is specified, SourceTable must be specified. If SourceTable is specified, SourceID must be specified.
    • There is a unique constraint on the SourceID/SourceTable fields in the database. At most, only 1 record can be returned for a given SourceID/SourceTable combination.
    • Leading/trailing spaces are ignored in the SourceTable parameter.
URL base/Billing/Customer/GetCustomersByPhoneNumber
Action POST
Description Returns a List of Customer objects representing the customers with the matching phone number.
Parameters
Name Required? Type Description
PhoneNumber Yes String A JSON object that includes the full phone number of a customer
Sample JSON Package 
{
      "PhoneNumber": "804-123-4567"
}
Returns A JSON Customer data object
Sample Return Object 
[{
  "ID": 353675,
  "UserID": null,
  "CustomerNumber": "SK457100",
  "Name": "",
  "FirstName": "Jack",
  "LastName": "Johnson",
  "MiddleName": "Griffin",
  "Phone": "8041234567",
  "Email": "jack.johnson@sampledomain.com",
  "MailingAddress": "1234 Palm Tree Drive, Sample City, VA 23236",
  "MailingCity": "Sample City",
  "MailingState": "VA",
  "MailingCountry": "United States",
  "MailingPostalCode": "23236",
  "MailingStreet": "VA",
  "BillingAddress": "1234 Palm Tree Drive, Sample City, VA 23236",
  "BillingCity": "Sample City",
  "BillingCountry": "United States",
  "BillingPostalCode": "23236",
  "BillingState": "VA",
  "BillingStreet": "1234 Palm Tree Drive",
  "Description": "Sample comments or description",
  "CustomerType": "B",
  "SourceTable": "Mapping Data",
  "SourceID": 4758,
  "IsDeleted": false,
  "CreateDate": "2016-02-06T11:12:45.61",
  "LastUpdatedDate": null
},
{
  "ID": 353699,
  "UserID": null,
  "CustomerNumber": "SK457199",
  "FirstName": "Devin",
  "LastName": "Nelson",
  "MiddleName": "Penderton",
  "Phone": "8041234567",
  "Email": "devinthemainman@bigegodomain.com",
  "MailingAddress": "134 Scatterbush Road, Sample City, VA 23205",
  "MailingCity": "Sample City",
  "MailingState": "VA",
  "MailingCountry": "United States",
  "MailingPostalCode": "23205",
  "MailingStreet": "VA",
  "BillingAddress": "134 Scatterbush Road, Sample City, VA 23205",
  "BillingCity": "Sample City",
  "BillingCountry": "United States",
  "BillingPostalCode": "23205",
  "BillingState": "VA",
  "BillingStreet": "134 Scatterbush Road",
  "Description": "Sample comments or description",
  "CustomerType": "B",
  "SourceTable": "Mapping Data",
  "SourceID": 4778,
  "IsDeleted": false,
  "CreateDate": "2018-07-06T15:03:45.61",
  "LastUpdatedDate": null
}]
Business Rules
  • This API method searches for the Customer contact phone number assigned to the customer records.
  • Before searching, the following characters are stripped from the parameter: spaces, dashes, periods, open/close parenthesis. All other characters are allowed to remain.
URL base/Billing/Customer/GetCustomerByServicePhoneNumber
Action POST
Description Returns a Customer object representing the customer with the matching phone number in a linked CustomerService record.
Parameters
Name Required? Type Description
PhoneNumber Yes String A JSON object that includes the full phone number of a customer service
Sample JSON Package 
{
      "PhoneNumber": "804-123-4567"
}
Returns A JSON Customer data object
Sample Return Object 
{
  "ID": 353675,
  "UserID": null,
  "CustomerNumber": "SK457100",
  "Name": "",
  "FirstName": "Jack",
  "LastName": "Johnson",
  "MiddleName": "Griffin",
  "Phone": "8041234567",
  "Email": "jack.johnson@sampledomain.com",
  "MailingAddress": "1234 Palm Tree Drive, Sample City, VA 23236",
  "MailingCity": "Sample City",
  "MailingState": "VA",
  "MailingCountry": "United States",
  "MailingPostalCode": "23236",
  "MailingStreet": "VA",
  "BillingAddress": "1234 Palm Tree Drive, Sample City, VA 23236",
  "BillingCity": "Sample City",
  "BillingCountry": "United States",
  "BillingPostalCode": "23236",
  "BillingState": "VA",
  "BillingStreet": "1234 Palm Tree Drive",
  "Description": "Sample comments or description",
  "CustomerType": "B",
  "SourceTable": "Mapping Data",
  "SourceID": 4758,
  "IsDeleted": false,
  "CreateDate": "2016-02-06T11:12:45.61",
  "LastUpdatedDate": null
}
Business Rules
  • This API method searches for the Customer contact phone number assigned to a CustomerService record linked to the Customer record.
  • There is a unique constraint on the service PhoneNumber field in the database. At most, only 1 record can be returned for a given phone number.
  • Before searching, the following characters are stripped from the parameter: spaces, dashes, periods, open/close parenthesis. All other characters are allowed to remain.
URL base/Billing/Customer/GetCustomersByName
Action POST
Description Returns a list of customers that match the given name. At least one of the fields in the payload must be specified -- i.e. FirstName, LastName or both fields can be specified, but both fields cannot be null/empty. The name specified will be treated as a wildcard search, so searching on the last name of 'Smith' will return entries with 'Smith', 'Smithville' and 'Smithe'.
Parameters
Name Required? Code Description
Name *No (with caveats -- see business rules) String The name of the customer
FirstName *No (with caveats -- see business rules) String The first name of the customer
LastName *No (with caveats -- see business rules) String The last name of the customer
Returns A list of JSON Customer data objects
Sample Return Object 
[
	{
		"ID": 353675,
		"UserID": null,
		"CustomerNumber": "SK457100",
		"Name": "",
		"FirstName": "Jack",
		"LastName": "Johnson",
		"MiddleName": "Griffin",
		"Phone": "8041234567",
		"Email": "jack.johnson@sampledomain.com",
		"MailingAddress": "1234 Palm Tree Drive, Sample City, VA 23236",
		"MailingCity": "Sample City",
		"MailingState": "VA",
		"MailingCountry": "United States",
		"MailingPostalCode": "23236",
		"MailingStreet": "VA",
		"BillingAddress": "1234 Palm Tree Drive, Sample City, VA 23236",
		"BillingCity": "Sample City",
		"BillingCountry": "United States",
		"BillingPostalCode": "23236",
		"BillingState": "VA",
		"BillingStreet": "1234 Palm Tree Drive",
		"Description": "Sample comments or description",
		"CustomerType": "B",
		"SourceTable": "Mapping Data",
		"SourceID": 4758,
		"IsDeleted": false,
		"CreateDate": "2016-02-06T11:12:45.61",
		"LastUpdatedDate": null
	},
	{
		"ID": 353682,
		"UserID": null,
		"CustomerNumber": "TK457100",
		"Name": "",
		"FirstName": "Joanne",
		"LastName": "Brown",
		"MiddleName": "Tiffany",
		"Phone": "8041234545",
		"Email": "joanne.brown@sampledomain.com",
		"MailingAddress": "1234 Southlawn Drive, Sample City, VA 23236",
		"MailingCity": "Sample City",
		"MailingState": "VA",
		"MailingCountry": "United States",
		"MailingPostalCode": "23236",
		"MailingStreet": "VA",
		"BillingAddress": "1234 Southlawn Drive, Sample City, VA 23236",
		"BillingCity": "Sample City",
		"BillingCountry": "United States",
		"BillingPostalCode": "23236",
		"BillingState": "VA",
		"BillingStreet": "1234 Southlawn Drive",
		"Description": "Sample comments or description",
		"CustomerType": "B",
		"SourceTable": "Mapping Data",
		"SourceID": 4775,
		"IsDeleted": false,
		"CreateDate": "2016-02-06T11:10:45.61",
		"LastUpdatedDate": null
	}
]
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
Name/FirstName/LastName:
  • The Name, FirstName, and LastName fields cannot all be null/empty. All fields may contain data, but at a minimum, one of the fields must contain a name to be searched.
Name/FirstName/LastName:
  • The following characters are not allowed in the Name, FirstName, or LastName parameter fields: %_[]^.
URL base/Billing/Customer/GetCustomersByCustomerNumber
Action POST
Description Returns a List of Customer objects representing the customers with the matching customer number.
Parameters
Name Required? Type Description
CustomerNumber Yes String The customer number of a customer.
Sample JSON Package 
{
      "CustomerNumber": "1234-AXT"
}
Returns A collection of JSON Customer data objects
Sample Return Object 
[
	{
		"ID": 353675,
		"UserID": null,
		"CustomerNumber": "1234-AXT",
		"Name": "",
		"FirstName": "Jack",
		"LastName": "Johnson",
		"MiddleName": "Griffin",
		"Phone": "8041234567",
		"Email": "jack.johnson@sampledomain.com",
		"MailingAddress": "1234 Palm Tree Drive, Sample City, VA 23236",
		"MailingCity": "Sample City",
		"MailingState": "VA",
		"MailingCountry": "United States",
		"MailingPostalCode": "23236",
		"MailingStreet": "VA",
		"BillingAddress": "1234 Palm Tree Drive, Sample City, VA 23236",
		"BillingCity": "Sample City",
		"BillingCountry": "United States",
		"BillingPostalCode": "23236",
		"BillingState": "VA",
		"BillingStreet": "1234 Palm Tree Drive",
		"Description": "Sample comments or description",
		"CustomerType": "B",
		"SourceTable": "Mapping Data",
		"SourceID": 4758,
		"IsDeleted": false,
		"CreateDate": "2016-02-06T11:12:45.61",
		"LastUpdatedDate": null
	},
	{
		"ID": 353699,
		"UserID": null,
		"CustomerNumber": "1234-AXT",
		"FirstName": "Devin",
		"LastName": "Nelson",
		"MiddleName": "Penderton",
		"Phone": "8041234567",
		"Email": "devinthemainman@bigegodomain.com",
		"MailingAddress": "134 Scatterbush Road, Sample City, VA 23205",
		"MailingCity": "Sample City",
		"MailingState": "VA",
		"MailingCountry": "United States",
		"MailingPostalCode": "23205",
		"MailingStreet": "VA",
		"BillingAddress": "134 Scatterbush Road, Sample City, VA 23205",
		"BillingCity": "Sample City",
		"BillingCountry": "United States",
		"BillingPostalCode": "23205",
		"BillingState": "VA",
		"BillingStreet": "134 Scatterbush Road",
		"Description": "Sample comments or description",
		"CustomerType": "B",
		"SourceTable": "Mapping Data",
		"SourceID": 4778,
		"IsDeleted": false,
		"CreateDate": "2018-07-06T15:03:45.61",
		"LastUpdatedDate": null
	}
]
Business Rules
  • This API method searches for the Customer customer number assigned to the customer records.
URL base/Billing/Customer/GetStructures/ID
Action GET
Description Returns a list of Structure objects when given an ID of a valid customer in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a customer in the M4 database.
Returns JSON Structure data objects
Sample Return Object 
[
  {
    "ID": 260820,
    "ParentID": null,
    "FullAddress": "TAPLOW RD",
    "HouseNumber": "",
    "PreDirectional": "",
    "Street": "TAPLOW RD",
    "StreetSuffix": "",
    "PostDirectional": "",
    "UnitNumber": "",
    "City": "",
    "State": "VA",
    "Zip_Code": "",
    "County": "Chesterfield",
    "Latitude": null,
    "Longitude": null,
    "CensusBlock": null,
    "CensusTract": null,
    "Exchange": "",
    "StructureType": "",
    "Comments": "",
    "COID": null,
    "LoopLength": null,
    "Mapped": null,
    "LastUpdateUser": "",
    "LastUpdateDate": null
  },
  {
    "ID": 342720,
    "ParentID": 26,
    "FullAddress": "111 Sample Street Drive, Apt 12A, Sample City, VA 23236",
    "HouseNumber": "111",
    "PreDirectional": "PreDirectional Information",
    "Street": "Sample Street",
    "StreetSuffix": "Drive",
    "PostDirectional": "",
    "UnitNumber": "",
    "City": "",
    "State": "",
    "Zip_Code": "",
    "County": "",
    "Latitude": null,
    "Longitude": null,
    "CensusBlock": null,
    "CensusTract": null,
    "Exchange": "",
    "StructureType": "",
    "Comments": "",
    "COID": null,
    "LoopLength": null,
    "Mapped": true,
    "LastUpdateUser": "Namey Namerson",
    "LastUpdateDate": "2015-01-30T11:40:48.037"
  }
]
URL base/Billing/Customer/AddCustomer
Action POST
Description Returns the Customer object just added to the M4 database.
Parameters
Name Required? Type Description
UserID No Integer The ID of a user in the M4 database.
CustomerNumber No String A unique identifier for the customer.
Name No String The name of the customer
FirstName No String The first name of the customer
LastName No String The last name of the customer
MiddleName No String The middle name of the customer
Phone No String The contact phone number of the customer in the M4 database.
Email No String The email address of the customer
MailingAddress No String The full mailing address of the customer
MailingCity No String The mailing city
MailingState No String The mailing state code
MailingCountry No String The mailing address country
MailingPostalCode No String The mailing zip code
MailingStreet No String The mailing name of the street
BillingAddress No String The full billing address of the customer
BillingCity No String The billing city
BillingState No String The billing state code
BillingCountry No String The billing address country
BillingPostalCode No String The billing zip code
BillingStreet No String The billing name of the street
Description No String
CustomerType Yes String Must be either (B) Business or (R) Residential
SourceID No Integer The Source ID from the Source table.
SourceTable No String The Source Table referenced by the Source ID.
StructureIDList No List of Integer A list of the IDs of the Structures related to the Customer in the M4 database.
Sample JSON Package 
{
      "UserID": null,
      "CustomerNumber": "SK45797",
      "Name": "Johnson Co.",
      "FirstName": "Jack",
      "LastName": "Johnson",
      "MiddleName": "Griffin",
      "Phone": "804-123-4567",
      "Email": "jack.johnson@sampledomain.com",
      "MailingAddress": "1234 Palm Tree Drive, Sample City, VA 23236",
      "MailingCity": "Sample City",
      "MailingState": "VA",
      "MailingCountry": "United States",
      "MailingPostalCode": "23236",
      "MailingStreet": "1234 Palm Tree Drive",
      "BillingAddress": "1234 Palm Tree Drive, Sample City, VA 23236",
      "BillingCity": "Sample City",
      "BillingCountry": "United States",
      "BillingPostalCode": "23236",
      "BillingState": "VA",
      "BillingStreet": "1234 Palm Tree Drive",
      "Description": "Sample comments or description",
      "CustomerType": "B",
      "SourceTable": "Field Data",
      "SourceID": 4758,
      "StructureIDList": [
        342720,
        260820
    ]
}
Returns A JSON Customer data object
Sample Return Object 
{
  "ID": 352200,
  "UserID": null,
  "CustomerNumber": "SK45797",
  "Name": "Johnson Co.",
  "FirstName": "Jack",
  "LastName": "Johnson",
  "MiddleName": "Griffin",
  "Phone": "8041234567",
  "Email": "jack.johnson@sampledomain.com",
  "MailingAddress": "1234 Palm Tree Drive, Sample City, VA 23236",
  "MailingCity": "Sample City",
  "MailingState": "VA",
  "MailingCountry": "United States",
  "MailingPostalCode": "23236",
  "MailingStreet": "VA",
  "BillingAddress": "1234 Palm Tree Drive, Sample City, VA 23236",
  "BillingCity": "Sample City",
  "BillingCountry": "United States",
  "BillingPostalCode": "23236",
  "BillingState": "VA",
  "BillingStreet": "1234 Palm Tree Drive",
  "Description": "Sample comments or description",
  "CustomerType": "B",
  "SourceTable": "Field Data",
  "SourceID": 4758,
  "IsDeleted": false,
  "CreateDate": "2017-02-03T16:47:33.397",
  "LastUpdatedDate": null
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • CustomerType: must be either (B) Business or (R) Residential
  • UserID: must already exist in the database as an existing user. Must be greater than 0.
  • CustomerNumber: must be unique among all customers (if not specified, a unique customer number will be automatically generated)
  • Phone:
    • Before saving, the following characters are stripped from the parameter: spaces, dashes, periods, open/close parenthesis. All other characters are allowed to remain.
  • SourceID/SourceTable:
    • The SourceID and SourceTable fields are fields that work in tandem. Both can be ignored (by setting the value to null) or both can be specified.
    • If SourceID is specified, SourceTable must be specified. If SourceTable is specified, SourceID must be specified.
    • There is a unique constraint on the SourceID/SourceTable fields in the database. At most, only 1 record can be returned for a given SourceID/SourceTable combination.
    • Leading/trailing spaces are ignored in the SourceTable parameter.
  • StructureIDList:
    • If a structure ID list is specified, each value must exist in the database as a valid structure.
    • Duplicate entries are automatically removed.
URL base/Billing/Customer/UpdateCustomer
Action POST
Description Returns the Customer object just updated in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer The ID of the Customer in the M4 database.
UserID No Integer The ID of a user in the M4 database.
CustomerNumber No String The number of the Customer in the M4 database.
Name No String The name of the customer
FirstName No String The first name of the customer
LastName No String The last name of the customer
MiddleName No String The middle name of the customer
Phone No String The contact phone number of the customer in the M4 database.
Email No String The email address of the customer
MailingAddress No String The full mailing address of the customer
MailingCity No String The mailing city
MailingState No String The mailing state code
MailingCountry No String The mailing address country
MailingPostalCode No String The mailing zip code
MailingStreet No String The mailing name of the street
BillingAddress No String The full billing address of the customer
BillingCity No String The billing city
BillingState No String The billing state code
BillingCountry No String The billing address country
BillingPostalCode No String The billing zip code
BillingStreet No String The billing name of the street
Description No String
CustomerType No String
SourceID No Integer The Source ID from the Source table.
SourceTable No String The Source Table referenced by the Source ID.
Sample JSON Package 
{     
  "ID": 125,
  "UserID": null,
  "CustomerNumber": "B0B626F0-D12B-4F38-8AC9-106AE6936DB1",
  "Name": "Victory Corp",
  "FirstName": "Victor",
  "LastName": "Torres",
  "MiddleName": "",
  "Phone": "",
  "Email": "",
  "MailingAddress": "2874 OLD MEMORIAL DR",
  "MailingCity": "DEMOVILLE",
  "MailingState": "VA",
  "MailingCountry": "USA",
  "MailingPostalCode": "",
  "MailingStreet": "",
  "BillingAddress": "",
  "BillingCity": "",
  "BillingCountry": "",
  "BillingPostalCode": "",
  "BillingState": "",
  "BillingStreet": "",
  "Description": "",
  "CustomerType": "",
  "SourceTable": "",
  "SourceID": null,
  "IsDeleted": false,
  "CustomerType": "B",
  "CreateDate": "2016-11-29T16:53:03.137",
  "LastUpdatedDate": null,
  "StructureIDList": [
        342720,
        260820
    ]
}
Returns A JSON Customer data object
Sample Return Object 
{
  "ID": 125,
  "UserID": null,
  "CustomerNumber": "B0B626F0-D12B-4F38-8AC9-106AE6936DB1",
  "Name": "Victory Corp",
  "FirstName": "Victor",
  "LastName": "Torres",
  "MiddleName": "",
  "Phone": "",
  "Email": "",
  "MailingAddress": "2874 OLD MEMORIAL DR",
  "MailingCity": "DEMOVILLE",
  "MailingState": "VA",
  "MailingCountry": "USA",
  "MailingPostalCode": "",
  "MailingStreet": "VA",
  "BillingAddress": "",
  "BillingCity": "",
  "BillingCountry": "",
  "BillingPostalCode": "",
  "BillingState": "",
  "BillingStreet": "",
  "Description": "",
  "CustomerType": "B",
  "SourceTable": "",
  "SourceID": null,
  "IsDeleted": false,
  "CreateDate": "2016-11-29T16:53:03.137",
  "LastUpdatedDate": "2017-02-03T16:48:39.883"
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • ID: the ID of the customer to be updated. Must be greater than 0.
  • CustomerType: must be either (B) Business or (R) Residential
  • UserID: must already exist in the database as an existing user. Must be greater than 0.
  • CustomerNumber: must be unique among all customers (if not specified, a unique customer number will be automatically generated)
  • Phone:
    • Before saving, the following characters are stripped from the parameter: spaces, dashes, periods, open/close parenthesis. All other characters are allowed to remain.
  • SourceID/SourceTable:
    • The SourceID and SourceTable fields are fields that work in tandem. Both can be ignored (by setting the value to null) or both can be specified.
    • If SourceID is specified, SourceTable must be specified. If SourceTable is specified, SourceID must be specified.
    • There is a unique constraint on the SourceID/SourceTable fields in the database. At most, only 1 record can be returned for a given SourceID/SourceTable combination.
    • Leading/trailing spaces are ignored in the SourceTable parameter.
URL base/Billing/Customer/RemoveCustomer
Action POST
Description Deletes a Customer and all associated linkages.
Parameters
Name Required? Type Description
ID Yes Integer A JSON object that includes the ID of a valid customer
Sample JSON Package 
{
      "ID": 125
}
Returns A JSON object with a message either the confirming the deletion or notifying the user of an invalid ID.
Sample Return Object 
"The Customer with ID [125] was deleted successfully and all assigned services and features have been disconnected."
Business Rules
  • ID: represents the ID of the customer to be deleted.
  • Must be greater than 0.
  • The customer cannot have any services that are attached to line cards.
  • Special Note: Deleting a customer will automatically disconnect all associated services and features. The disconnect date of the services and features will be the date/time the customer was deleted.
URL base/Billing/Customer/ReactivateCustomer
Action POST
Description Reactivates (makes active) a customer that has been flagged as deleted.
Parameters
Name Required? Type Description
ID Yes Integer The ID of a Customer in the M4 database.
Sample JSON Package 
{
      "ID": 15359
}
Returns A JSON message data object
Sample Return Object 
{
    "Message": "The customer with ID [15359] was reactivated successfully."
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.

ID:
  • The ID must be a valid customer in the database.
  • The customer must already be flagged as deleted (i.e. not currently active).
Duplicate Fields:
  • Reactivation of a customer must maintain the requirement for a unique CustomerNumber.
  • Reactivation of a customer must maintain the requirement for a unique SourceID/SourceTable combination.
URL base/Billing/Customer/LinkStructures
Action POST
Description Link Structures to Customer using customer ID.
Parameters
Name Required? Type Description
ID Yes Integer The ID of a Customer in the M4 database.
StructureIDList No List of Integer A list of the IDs of the Structures related to the Customer in the M4 database.
Sample JSON Package 
{
      "ID": 15359,
      "StructureIDList": [
        342720,
        260820
    ]
}
Returns A JSON list of the Structure IDs just linked
Sample Return Object 
{
      "ID": 15359,
      "StructureIDList": [
        342720,
        260820
    ]
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.

ID:
  • The ID must be a valid customer in the database.
StructureIDList:
  • All the Structures (IDs) in the list must exist in the system.
  • The API will return an error message if the Structures (IDs) in the list are already linked to the Customer in the system.
URL base/Billing/Customer/UnlinkStructures
Action POST
Description Unlink Structures to Customer using customer ID.
Parameters
Name Required? Type Description
ID Yes Integer The ID of a Customer in the M4 database.
StructureIDList No List of Integer A list of the IDs of the Structures related to the Customer in the M4 database.
Sample JSON Package 
{
      "ID": 15359,
      "StructureIDList": [
        342720,
        260820
    ]
}
Returns A JSON list of the Structure IDs just un-linked
Sample Return Object 
{
      "ID": 15359,
      "StructureIDList": [
        342720,
        260820
    ]
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.

ID:
  • The ID must be a valid customer in the database.
StructureIDList:
  • All the Structures (IDs) in the list must exist in the system.
URL base/Billing/Customer/GetCustomersByStructure/ID
Action GET
Description Returns all Customer objects as an array that are linked to a given Structure ID.
Version Added in 19.3.8
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a Structure in the M4 database.
Returns A JSON Customer data object
Sample Return Object 
[
{
  "ID": 125,
  "UserID": null,
  "CustomerNumber": "B0B626F0-D12B-4F38-8AC9-106AE6936DB1",
  "Name": "",
  "FirstName": "Victor",
  "LastName": "Torres",
  "MiddleName": "",
  "Phone": "",
  "Email": "",
  "MailingAddress": "2874 OLD MEMORIAL DR",
  "MailingCity": "DEMOVILLE",
  "MailingState": "VA",
  "MailingCountry": "USA",
  "MailingPostalCode": "",
  "MailingStreet": "VA",
  "BillingAddress": "",
  "BillingCity": "",
  "BillingCountry": "",
  "BillingPostalCode": "",
  "BillingState": "",
  "BillingStreet": "",
  "Description": "",
  "CustomerType": "B",
  "SourceTable": "",
  "SourceID": null,
  "IsDeleted": false,
  "CreateDate": "2016-11-29T16:53:03.137",
  "LastUpdatedDate": "2017-01-30T12:56:20.243"
}
]

Was this article helpful?

Yes No

Related Articles