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.

Comment

Explanation

Required

This must be provided to Sonar to create an account.

Optional

This field is optional when creating an account.

Conditional

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 {
  createAccount(
    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:"qb@packers.com", # 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
            }
        }
    }) {
        id
    }
}

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?

Future Serviceable Addresses: Overview

Notes & Tasks: Best Practices & Use Cases

Contact