Table of Contents

Lead Intake Form Processing

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 allows 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 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.

You provide

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).

From form

This would process the data that a prospective customer fills out, rather than something you are statically providing.

mutation {
input: {
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
mailing_address: {
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
primary_contact: {
name: "Aaron Rogers", # Required; From form
role: "Quarterback", # Optional; From form
email_address:"", # Optional; From form
email_category_ids: [1,2], # Optional; You provide
phone_numbers: {
number: 9205697500, # Optional; From form
phone_number_type_id:1, # Conditional; From form
country: US # Conditional; From form
}) {

What Next?

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:

  1. A mailing address does not require GPS coordinates, whereas a serviceable address does.
  2. 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:

  1. 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.
  2. Create the serviceable address in Sonar (using the createServiceableAddress mutation) and read the ID that it outputs.
  3. Feed that ID into the createAccount mutation above using the serviceable_address_id property.

How did we do?

Specify Account ID upon Creation

Account Groups: Overview & Example Use Cases