Table of Contents
Updated by Matt Glosson
Read Time: 3 mins
One of the main use-cases for utilizing the Sonar API is centered around the question, “How can I develop a ‘Lead-Intake’ form?” Below is a GraphQL mutation that will allow you to take in that data from a public website.
The general idea is that you would have a form that processes on your web server. It takes in the data from the form and massages it into a GraphQL mutation for feeding into your Sonar instance. In the example below, there are comments included in the code - an explanation of what each comment means is provided below.
This must be provided to Sonar in order to create an account.
This field is optional when creating an account.
These fields are required if something else is set. For example, if you set a phone number, you have to also set a phone_number_type_id and a country.
This means that you would provide that value on the back-end of your form (and would therefore not expect the prospective customer to provide that information).
This would process the data that a prospective customer fills out, rather than something you are statically providing.
company_id:1, # Required; You provide
account_type_id: 2, # Required; You provide
account_status_id: 3, # Required; You provide
account_group_ids: [1,3], # Optional; You provide
name: "Green Bay Packers", # Required; From form
line1: "1265 Lombardi Avenue", # Optional; From form
line2: "Suite 37B", # Optional; From form
city: "Green Bay", # Optional; From form
subdivision: US_WI, # Optional; From form (concatenate Country_State)
country: US, # Optional; From form
zip: "54304" # Optional; From form
name: "Aaron Rogers", # Required; From form
role: "Quarterback", # Optional; From form
email_address:"email@example.com", # Optional; From form
email_category_ids: [1,2], # Optional; You provide
number: 9205697500, # Optional; From form
phone_number_type_id:1, # Conditional; From form
country: US # Conditional; From form
This will create an address, but the account cannot be set to Active at this point, because it has only a mailing address. A serviceable address (a.k.a. a physical address) is required before an account can be set to Active. There are two reasons we are feeding in a mailing address:
- A mailing address does not require GPS coordinates, whereas a serviceable address does.
- Creating a serviceable address is a separate mutation, which then must be referred to in the mutation above. For simplicity, one mutation is desirable.
When you are ready to convert the account from a Lead status to Active status, use the Sonar GUI to create a proper serviceable address. At that point, you can make any necessary adjustments to the mailing address (e.g., change it to a PO Box if desired).
What if I want a physical address from the get-go?
In this case, you would need to do the following:
- Get the lead account's address, then perform an API call to somewhere (e.g., Google Maps) to get the GPS coordinates. As an easier alternative to this step, put in static GPS coordinates to be converted later.Note that they must be real GPS coordinates (i.e., don't use 0,0 which puts you in the ocean off the coast of Ghana). Using your headquarters is recommended, as you can filter on that later to find addresses with incomplete coordinates.
- Create the serviceable address in Sonar (using the
createServiceableAddressmutation) and read the ID that it outputs.
- Feed that ID into the
createAccountmutation above using the