In this article:

• What is the Lead Entry API?
• Technical Requirements
• SingleOps API (Customers, Leads, Task)
• URL Patterns & Credentials
  • Account Groups
  • Auth Parameters
  • Example GET request with URL parameters
  • In Browser testing
• Referenced Entities
  • Operations
  • Custom Inputs
• Client Search
• Create a Lead
  • For an Existing Client
  • For a New Client
  • For a New Task

Appendix

• Field Information
  • Job
  • Portal Lead
  • Task

What is the Lead Entry API?

Reduce duplicate data entry, and increase your team's efficiency with a Leads API integration. This allows you to create new leads in SingleOps from an outside system. 

This will require some technical know-how on your end. If that is not available to your team, you can use our Client Portal for Lead Entry from your website! Learn more here. 

Technical Requirements

1. Technical resource on your team to connect, troubleshoot, and maintain the connection.
   *Note: SingleOps provides steps to request an API Token. All integration and maintenance is managed on your end. 
2. You will need an API Access Token. Contact support (support@singleops.com) to create a new API User on the Account you wish to create Leads on and note the Email Address and API Token. This user will not incur any additional costs. API access may not be available on all pricing tiers. 

SingleOps API (Customers, Leads, Tasks)

The SingleOps API documentation below covers customer, lead, and task entry/creation. Leads created through the process detailed here will follow the Customer Portal workflow (requiring manual confirmation before a client/location is considered valid).

URL Patterns and Credentials

Account Groups

Each account must have its own unique API user. API users are unable to make API calls to other accounts in their account group even if the user has access to the other account. These are just passed as parameters on the request:

Auth Parameters

These are passed as part of the message body.  GET requests also support passing them as URL parameters.

Example GET request with URL parameters:

In Browser testing

For testing GET requests you can use your regular user cookie to access the API endpoints with 2 caveats:

• Requests must be made over HTTPS
• You must currently be viewing the correct account for your user. If you have an account group and are currently looking at a different account in app you must switch to your “home” account before you can access that account’s data

Referenced Entities

The first two requests are to get entities whose IDs are needed for each lead: custom input and operation. Our preference would be that these IDs are cached but the API consumer can request them for each lead created.

Operations

Operations represent the division that this lead will be for. This is a required field for leads, but can be modified subsequently if it is mis-classified.
URL: https://app.singleops.com/api/v1/operations
No additional params needed.
Response

Custom Inputs

Custom Inputs are fields that accounts can specify to retain additional information about leads, jobs, clients, items, etc.
URL: https://app.singleops.com/api/v1/custom_inputs
Response

The “dropdown_options” can be ignored. This is to provide a list of dropdown options that a custom input supports, but since the lead source for your use case should all be the same this won’t be needed.

Client search

The next request is to search for clients by email and phone number. This is to find a matching existing client, if possible, for the lead.
There are two additional params for the client search request. Search field allows you to specify whether you want to search by email or phone number. Please note that this is a prefix search. Sometimes clients will append multiple phone numbers or extensions, so we wanted to allow those to be caught as well.
This example only returns one result, but it can return anywhere from 0 to 50. Additional pages are available using a “page” parameter.
URL: https://app.singleops.com/api/v1/clients/search_by_field

Response

Create a Lead 

For An Existing Client: 

URL: https://app.singleops.com/api/v1/jobs
Request should be a POST and the body should be JSON:

Response 

The response will indicate whether the lead was created or not, along with the id of created lead: 

For A New Client

URL: https://app.singleops.com/api/v1/jobs
Request should be a POST and the body should be JSON. Note that client_id for “job” is empty in this example. Instead the new client details are put under the “portal lead” section and can include phone number, email and mobile number.:

For a New Task

To create a new Task when a new Lead is created, we must add the appropriate task related fields to the POST JSON body. “job_task_create” must be set to true and the “task” Object must be provided. 

Response 

The response will indicate whether the lead was created or not, along with the id of created lead: 

Appendix

Field Information:

Job:

name: 41 characters

notes: 4000 characters 

            Custom Field Value: 4000 characters

Portal Lead:

           first_name: 255 characters

           last_name: 255 characters 

           company_name: 255 characters

           email: 255 characters

           phone: 255 characters

           mobile: 255 characters

           address: 255 characters

           city: 255 characters

           state: 5 characters (State / Province codes)

           zip: 255 characters

Task:

job_task_create: true or false

task.name: 41 characters 

            task.notes: 4000 characters

task.on_site: true or false

task.start: DateTime

task.stop: DateTime

task.all_day: true or false