Contact

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

Description

The Contact endpoint provides the API consumer with access to methods pertaining to contacts and related data objects. The endpoint allows consumers to load contact data, add new contacts, and update contacts.

Methods

URL base/CRM/Contact/Specification
Action GET
Description Returns a data dictionary that details the available web service methods related to the Contact endpoint.
Parameters None
 Returns  A JSON object with method descriptions
Sample Return Object 
[
    {
        "HttpAction": "Get",
        "MethodName": "GetContact",
        "Description": "Returns the record for a single 'Contact' given the passed in ID value (see Path).",
        "Path": "/Contact/GetContact/25032"
    },
    {
        "HttpAction": "Get",
        "MethodName": "GetContactByEstimate",
        "Description": "Returns the record for a single 'Contact' for the passed in Estimate ID value (see Path).",
        "Path": "/Contact/GetContactByEstimate/25032"
    },
    {
        "HttpAction": "Get",
        "MethodName": "GetContactByOpportunity",
        "Description": "Returns the record for a single 'Contact' for the passed in Opportunity ID value (see Path).",
        "Path": "/Contact/GetContactByOpportunity/25032"
    },
    {
        "HttpAction": "Post",
        "MethodName": "GetContactsByName",
        "Description": "Returns the record for a single 'Contact' given the passed in name.",
        "Format": {
            "Name": "John Smith"
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "GetContactsByPhone",
        "Description": "Returns the record for a single 'Contact' given the passed in phone number.",
        "Format": {
            "Phone": "8047431860"
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "GetContactByNamePhoneEmail",
        "Description": "Returns the record for a single 'Contact' given the passed in name, phone number, and email.",
        "Format": {
            "Name": "John Smith",
            "Phone": "8047431860",
            "Email": "email@mapcom.com"
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "AddContact",
        "Description": "Creates the record for a single 'Contact' and returns the Contact object",
        "Format": {
            "Name": "John Smith",
            "Description": null,
            "Phone": "8047431860",
            "Email": "email@mapcom.com",
            "StreetNumber": "601",
            "StreetName": "Southlake Boulevard",
            "City": "Richmond",
            "State": "VA",
            "PostalCode": "23236",
            "Country": "US",
            "CreatedOn": "2018-06-11T14:55:04.3451731-04:00",
            "CreatedBy": "Mapcom"
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "UpdateContact",
        "Description": "Updates the record for a single 'Contact' and returns the Contact object",
        "Format": {
            "ID": 117,
            "Name": "John Smith",
            "Description": null,
            "Phone": "8047431860",
            "Email": "email@mapcom.com",
            "StreetNumber": "601",
            "StreetName": "Southlake Boulevard",
            "City": "Richmond",
            "State": "VA",
            "PostalCode": "23236",
            "Country": "US",
            "CreatedOn": "2018-06-11T14:55:04.3466725-04:00",
            "CreatedBy": "Mapcom"
        }
    },
    {
        "HttpAction": "Get",
        "MethodName": "DeleteContact",
        "Description": "Deletes the record for a single 'Contact' given the passed in ID value (see Path).",
        "Path": "/Contact/DeleteContact/25032"
    },
    {
        "HttpAction": "Post",
        "MethodName": "LinkContactToCustomer",
        "Description": "Links the ContactID to the CustomerID. Returns a cross reference object.",
        "Format": {
            "ContactID": 117,
            "CustomerID": 117
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "UnlinkContactFromCustomer",
        "Description": "Unlinks the ContactID from the CustomerID. Returns a cross reference object.",
        "Format": {
            "ContactID": 117,
            "CustomerID": 117
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "LinkContactToStructure",
        "Description": "Links the ContactID to the StructureID. Returns a cross reference object.",
        "Format": {
            "ContactID": 117,
            "StructureID": 117
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "UnlinkContactFromStructure",
        "Description": "Unlinks the ContactID from the StructureID. Returns a cross reference object.",
        "Format": {
            "ContactID": 117,
            "StructureID": 117
        }
    },
    {
        "HttpAction": "Get",
        "MethodName": "GetLinkedStructuresByContactID",
        "Description": "Returns all 'Structure' records given the passed in Contact ID value (see Path).",
        "Path": "/Contact/GetLinkedStructuresByContactID/25032"
    },
    {
        "HttpAction": "Get",
        "MethodName": "GetLinkedCustomersByContactID",
        "Description": "Returns all 'Customer' records given the passed in Contact ID value (see Path).",
        "Path": "/Contact/GetLinkedCustomersByContactID/25032"
    }
]
URL base/CRM/Contact/AddContact
Action POST
Description Adds the specified contact object and returns a the newly created contact object.
Parameters
Name Required? Type Description
Name Yes String The full name of the contact.
Description No String The description of the contact.
Phone No String The phone number of the contact.
Email No String The email of the contact.
StreetNumber No String The street number of the contact's address.
StreetName No String The street name of the contact's address.
City No String The city of the contact's address.
State No String The state of the contact's address.
PostalCode No String The postal code of the contact's address.
Country No String The country of of the contact's address.
Sample JSON Package 
{
     "Name": "John Smith",
     "Description": null,
     "Phone": "8047431860 ",
     "Email": "email@mapcom.com",
     "StreetNumber": "601",
     "StreetName": "Southlake Boulevard",
     "City": "Richmond",
     "State": "VA",
     "PostalCode": "23236",
     "Country": "US"
}
Returns A JSON Contact data object
Sample Return Object 
{
     "ID": 224,
     "Name": "John Smith",
     "Description": null,
     "Phone": "8047431860",
     "Email": "email@mapcom.com",
     "StreetNumber": "601",
     "StreetName": "Southlake Boulevard",
     "City": "Richmond",
     "State": "VA",
     "PostalCode": "23236",
     "Country": "US",
     "CreatedOn": "2017-11-27T10:57:28.0562462-05:00",
     "CreatedBy": "Mapcom"
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • Name: must not be null.
  • If including an address, all address fields must have a value.
URL base/CRM/Contact/GetContact/ID
Action GET
Description Returns a Contact object when given an ID of a valid contact in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a contact in the M4 database.
Returns A JSON Contact data object
Sample Return Object 
{
    "ID": 224,
    "Name": "John Smith",
    "Description": null,
    "Phone": "8047431860",
    "Email": "email@mapcom.com",
    "StreetNumber": "601",
    "StreetName": "Southlake Boulevard",
    "City": "Richmond",
    "State": "VA",
    "PostalCode": "23236",
    "Country": "US",
    "CreatedOn": "2017-11-27T10:57:28.0562462-05:00",
    "CreatedBy": "Mapcom"
}
URL base/CRM/Contact/GetContactByNamePhoneEmail
Action POST
Description Returns the contact object based on the specified name, phone number, and email address.
Parameters
Name Required? Type Description
Name Yes String The full name of the contact.
Phone No String The phone number of the contact.
Email No String The email of the contact.
Sample JSON Package 
{
     "Name": "John Smith",
     "Phone": "8047431860",
     "Email": "email@mapcom.com"     
}
Returns A JSON Contact data object
Sample Return Object 
{
     "ID": 224,
     "Name": "John Smith",
     "Description": null,
     "Phone": "8047431860",
     "Email": "email@mapcom.com",
     "StreetNumber": "601",
     "StreetName": "Southlake Boulevard",
     "City": "Richmond",
     "State": "VA",
     "PostalCode": "23236",
     "Country": "US",
     "CreatedOn": "2017-11-27T10:57:28.0562462-05:00",
     "CreatedBy": "Mapcom"
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • Name: must not be null
URL base/CRM/Contact/GetContactsByName
Action POST
Description Returns the collection of Contact objects based on the specified name.
Parameters
Name Required? Type Description
Name Yes String The full name of the contact.
Sample JSON Package 
{
     "Name": "John Smith"    
}
Returns A list JSON Contact data objects
Sample Return Object 
[
     {
          "ID": 224,
          "Name": "John Smith",
          "Description": null,
          "Phone": "8047431860",
          "Email": "email@mapcom.com",
          "StreetNumber": "601",
          "StreetName": "Southlake Boulevard",
          "City": "Richmond",
          "State": "VA",
          "PostalCode": "23236",
          "Country": "US",
          "CreatedOn": "2017-11-27T10:57:28.0562462-05:00",
          "CreatedBy": "Mapcom"
     }
]
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • Name: must not be null
URL base/CRM/Contact/GetContactsByPhoneNumber
Action POST
Description Returns the collection of Contact objects based on the specified phone number.
Parameters
Name Required? Type Description
PhoneNumber Yes String The phone number of the contact.
Sample JSON Package 
{
     "PhoneNumber": "8047431860"    
}
Returns A list of JSON Contact data objects
Sample Return Object 
[
     {
          "ID": 224,
          "Name": "John Smith",
          "Description": null,
          "Phone": "8047431860",
          "Email": "email@mapcom.com",
          "StreetNumber": "601",
          "StreetName": "Southlake Boulevard",
          "City": "Richmond",
          "State": "VA",
          "PostalCode": "23236",
          "Country": "US",
          "CreatedOn": "2017-11-27T10:57:28.0562462-05:00",
          "CreatedBy": "Mapcom"
     }
]
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • PhoneNumber: must not be null
URL base/CRM/Contact/GetContactByEstimate
Action GET
Description Returns a Contact object when given an ID of a valid Estimate in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of an Estimate in the M4 database.
Returns A JSON Contact data object
Sample Return Object 
{
     "ID": 224,
     "Name": "John Smith",
     "Description": null,
     "Phone": "8047431860 ",
     "Email": "email@mapcom.com",
     "StreetNumber": "601",
     "StreetName": "Southlake Boulevard",
     "City": "Richmond",
     "State": "VA",
     "PostalCode": "23236",
     "Country": "US",
     "CreatedOn": "2017-11-27T10:57:28.0562462-05:00",
     "CreatedBy": "Mapcom"
}
URL base/CRM/Contact/GetContactByOpportunity
Action GET
Description Returns a Contact object when given an ID of a valid Opportunity in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of an Opportunity in the M4 database.
Returns A JSON Contact data object
Sample Return Object 
{
     "ID": 224,
     "Name": "John Smith",
     "Description": null,
     "Phone": "8047431860 ",
     "Email": "email@mapcom.com",
     "StreetNumber": "601",
     "StreetName": "Southlake Boulevard",
     "City": "Richmond",
     "State": "VA",
     "PostalCode": "23236",
     "Country": "US",
     "CreatedOn": "2017-11-27T10:57:28.0562462-05:00",
     "CreatedBy": "Mapcom"
}
URL base/CRM/Contact/UpdateContact
Action POST
Description Updates the specified contact object and returns a the newly updated contact object.
Parameters
Name Required? Type Description
ID Yes Integer The ID of the contact.
Name Yes String The full name of the contact.
Description No String The description of the contact.
Phone No String The phone number of the contact.
Email No String The email of the contact.
StreetNumber No String The street number of the contact's address.
StreetName No String The street name of the contact's address.
City No String The city of the contact's address.
State No String The state of the contact's address.
PostalCode No String The postal code of the contact's address.
Country No String The country of of the contact's address.
Sample JSON Package 
{
     "ID": 224, 
     "Name": "John Smith",
     "Description": null,
     "Phone": "8047431860 ",
     "Email": "email@mapcom.com",
     "StreetNumber": "601",
     "StreetName": "Southlake Boulevard",
     "City": "Richmond",
     "State": "VA",
     "PostalCode": "23236",
     "Country": "US"
}
Returns A JSON Contact data object
Sample Return Object 
{
     "ID": 224,
     "Name": "John Smith",
     "Description": null,
     "Phone": "8047431860 ",
     "Email": "email@mapcom.com",
     "StreetNumber": "601",
     "StreetName": "Southlake Boulevard",
     "City": "Richmond",
     "State": "VA",
     "PostalCode": "23236",
     "Country": "US",
     "CreatedOn": "2017-11-27T10:57:28.0562462-05:00",
     "CreatedBy": "Mapcom"
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • Name: must not be null
URL base/CRM/Contact/DeleteContact/ID
Action GET
Description Deletes Contact object when given an ID of a valid contact in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a contact in the M4 database.
Returns A JSON data object
Sample Return Object 
{
  "Message": "The Contact with ID [55] was deleted successfully."
}
URL base/CRM/Contact/GetLinkedCustomersByContactID/ID
Action GET
Description Returns a list of Customer objects when given an ID of a valid contact in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a contact in the M4 database.
Returns A JSON List of customer data objects
Sample Return Object 
[
{
  "ID": 125,
  "UserID": null,
  "CustomerNumber": "B0B626F0-D12B-4F38-8AC9-106AE6936DB1",
  "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"
},
{
  "ID": 145,
  "UserID": null,
  "CustomerNumber": "B0B62BFF-A113-4F38-9BC9-106AA69B6DB1",
  "FirstName": "Hugo",
  "LastName": "Walker",
  "MiddleName": "",
  "Phone": "",
  "Email": "",
  "MailingAddress": "8741 NEW MEMORIAL DR",
  "MailingCity": "SOUTH 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/CRM/Contact/GetLinkedStructuresByContactID/ID
Action GET
Description Returns a list of Structure objects when given an ID of a valid contact in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a contact in the M4 database.
Returns A JSON List of structure data objects
Sample Return Object 
[
{
  "ID": 342711,
  "ParentID": 26,
  "FullAddress": "111 Sample Street Drive, Apt 12A, Sample City, VA 23236",
  "Description": "Description of this structure",
  "HouseNumber": "111",
  "PreDirectional": "PreDirectional Information",
  "Street": "Sample Street",
  "StreetSuffix": "Drive",
  "PostDirectional": "",
  "UnitNumber": "",
  "City": "",
  "State": "",
  "Zip_Code": "",
  "County": "",
  "Latitude": null,
  "Longitude": null,
  "CensusBlock": "060670011011085",
  "CensusTract": "06067001101",
  "Exchange": "",
  "StructureType": "Res",
  "Comments": "",
  "COID": null,
  "LoopLength": null,
  "Mapped": true,
  "LastUpdateUser": "Namey Namerson",
  "LastUpdateDate": "2015-01-30T11:40:48.037"
},
{
  "ID": 342720,
  "ParentID": 23,
  "FullAddress": "333 Other Sample Avenue, Apt 121G, Sample City, VA 23236",
  "Description": "Description of this other structure",
  "HouseNumber": "333",
  "PreDirectional": "PreDirectional Information",
  "Street": "Other Sample",
  "StreetSuffix": "Avenue",
  "PostDirectional": "",
  "UnitNumber": "",
  "City": "",
  "State": "",
  "Zip_Code": "",
  "County": "",
  "Latitude": null,
  "Longitude": null,
  "CensusBlock": "060670011011085",
  "CensusTract": "06067001101",
  "Exchange": "",
  "StructureType": "Res",
  "Comments": "",
  "COID": null,
  "LoopLength": null,
  "Mapped": true,
  "LastUpdateUser": "Namey Namerson, Jr",
  "LastUpdateDate": "2015-01-30T11:40:48.037"
}
]
URL base/CRM/Contact/LinkContactToCustomer
Action POST
Description Links the specified contact object to the specified customer object and returns a cross reference object.
Parameters
Name Required? Type Description
ContactID Yes Integer The ID of the contact.
CustomerID Yes Integer The ID of the customer.
Sample JSON Package 
{
     "ContactID": 224, 
     "CustomerID": 1225
}
Returns A JSON Contact Xref data object
Sample Return Object 
{
     "ContactID": 224, 
     "CustomerID": 1225
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • ContactID: must be a valid contact
  • CustomerID: must be a valid customer
URL base/CRM/Contact/LinkContactToStructure
Action POST
Description Links the specified contact object to the specified structure object and returns a cross reference object.
Parameters
Name Required? Type Description
ContactID Yes Integer The ID of the contact.
StructureID Yes Integer The ID of the structure.
Sample JSON Package 
{
     "ContactID": 224, 
     "StructureID": 1225
}
Returns A JSON Contact Xref data object
Sample Return Object 
{
     "ContactID": 224, 
     "StructureID": 1225
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • ContactID: must be a valid contact
  • StructureID: must be a valid structure
URL base/CRM/Contact/UnlinkContactFromCustomer
Action POST
Description Unlinks the specified contact object from the specified customer object and returns a cross reference object.
Parameters
Name Required? Type Description
ContactID Yes Integer The ID of the contact.
CustomerID Yes Integer The ID of the customer.
Sample JSON Package 
{
     "ContactID": 224, 
     "CustomerID": 1225
}
Returns A JSON Contact Xref data object
Sample Return Object 
{
     "ContactID": 224, 
     "CustomerID": 1225
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • ContactID: must be a valid contact
  • CustomerID: must be a valid customer
URL base/CRM/Contact/UnlinkContactFromStructure
Action POST
Description Unlinks the specified contact object from the specified structure object and returns a cross reference object.
Parameters
Name Required? Type Description
ContactID Yes Integer The ID of the contact.
StructureID Yes Integer The ID of the structure.
Sample JSON Package 
{
     "ContactID": 224, 
     "StructureID": 1225
}
Returns A JSON Contact Xref data object
Sample Return Object 
{
     "ContactID": 224, 
     "StructureID": 1225
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • ContactID: must be a valid contact
  • StructureID: must be a valid structure
URL base/CRM/Contact/GetContactsByCustomer/ID
Action GET
Description Returns the collection of Contact objects based on the specified customer.
Parameters
Name Required? Type Description
ID Yes Integer The ID of the contact.
Returns A list JSON Contact data objects
Sample Return Object 
[
     {
          "ID": 224,
          "Name": "John Smith",
          "Description": null,
          "Phone": "8047431860",
          "Email": "email@mapcom.com",
          "StreetNumber": "601",
          "StreetName": "Southlake Boulevard",
          "City": "Richmond",
          "State": "VA",
          "PostalCode": "23236",
          "Country": "US",
          "CreatedOn": "2017-11-27T10:57:28.0562462-05:00",
          "CreatedBy": "Mapcom"
     }
]
Business Rules
URL base/CRM/Contact/GetContactsByStructure/ID
Action GET
Description Returns the collection of Contact objects based on the specified structure.
Parameters
Name Required? Type Description
ID Yes Integer The ID of the structure.
Returns A list JSON Contact data objects
Sample Return Object 
[
     {
          "ID": 224,
          "Name": "John Smith",
          "Description": null,
          "Phone": "8047431860",
          "Email": "email@mapcom.com",
          "StreetNumber": "601",
          "StreetName": "Southlake Boulevard",
          "City": "Richmond",
          "State": "VA",
          "PostalCode": "23236",
          "Country": "US",
          "CreatedOn": "2017-11-27T10:57:28.0562462-05:00",
          "CreatedBy": "Mapcom"
     }
]
Business Rules
URL base/CRM/Contact/LinkContactToCircuit
Action POST
Description Links the specified contact object to the specified circuit object and returns a cross reference object.
Parameters
Name Required? Type Description
ContactID Yes Integer The ID of the contact.
CircuitID Yes Integer The ID of the circuit.
Sample JSON Package 
{
     "ContactID": 224, 
     "CircuitID": 1225
}
Returns A JSON Contact Xref data object
Sample Return Object 
{
     "ContactID": 224, 
     "CircuitID": 1225
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • ContactID: must be a valid contact
  • CircuitID: must be a valid circuit
URL base/CRM/Contact/UnlinkContactFromCircuit
Action POST
Description Unlinks the specified contact object from the specified circuit object and returns a cross reference object.
Parameters
Name Required? Type Description
ContactID Yes Integer The ID of the contact.
CircuitID Yes Integer The ID of the circuit.
Sample JSON Package 
{
     "ContactID": 224, 
     "CircuitID": 1225
}
Returns A JSON Contact Xref data object
Sample Return Object 
{
     "ContactID": 224, 
     "CircuitID": 1225
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • ContactID: must be a valid contact
  • CircuitID: must be a valid circuit

Was this article helpful?

Yes No

Related Articles