Lead Assign API

Auth

Get the request token by logging into the application (ie login as a company admin to app.leadassign.com)

company_slug indicates the company that you want to send leads into, you can see your company_slug in the url after you login to the site.

Visit

https://app.leadassign.com/company_slug/apikey/ – this is also accessible in the “Integrations” tab. If you need to refresh your auth token, please contact support. Refreshing your auth token will stop all older API endpoints from working.

You should copy the generated token somewhere safe and keep it in an environment var or similar on your server. We only keep sha256 hashes of our access tokens. If you lose it simply generate another one. I’ll call this auth_token. NOTE: Lead Assign will also take the displayed Sha256 as a valid token for add lead requests.

So you have the token – which is valid until someone presses ‘Generate new auth token’ again.

API Calls:

Add Lead POST

https://app.leadassign.com/extapi/company_slug/lead

Payload cannot exceed 25KB (attachments like photos need to be links)

Set a header called ‘X-Auth-Token’ with the auth_token you copied after you pressed generate new auth token.

The payload is JSON, (UTF-8)
ALL fields are optional, although we need to logically create a lead. If there is no text description that has phone and email of client, then the email or phone of the client should be set. In other words Lead Assign will work pretty well if the entire payload is in the ‘text’ but its best if you can set name , phone and/or email

name : customer name
phone : customer phone
email : customer email
text : message from customer – could be the entire lead payload if thats what you have.
tags : ARRAY of tags – if you want to send a lead to a specific agent first, use their email here. – other tags are also possible. Note that tags can be picked up from the text as well, these are just a hint to Lead Assign.
geolocation_address : address that google can use – 250 Niagra St, Thunder Bay On P05 7W7 Canada, or more simply 92037, USA, etc.
source_email : email address used to indicate the source of the lead. This is to tell the original source apart.
identified_agent : email address OR external ID of the agent. External ID is checked first. This is the agent to give the first shot at the lead to. (ie courtesy lead, agent picked from a popup on a web form, etc).

All fields optional
Well – obviously we want to generate a lead out of this, so we would need a least a phone number or name or some text with some kind of contact data in it.

Extra fields:

Extra – application specific fields are welcome. They will be passed on to the CSV lead export feature, etc.

NOTE you may not know the email, customer name, etc. That’s ok. Just send the ‘text’ with a reasonable format so we can figure out what the customer email is, etc.

Example text based lead:

Name: Judy Smith
Phone: 705 555 1212
email: judy@gmail.com

Address:
326 First St,
Colllingwood, On
Canada
L9Y 1P7

Property: https://myrealesatecompany.com/homes/somehouse

I am looking at this home. Can you arrange a tour on Friday after 4 pm? We are looking for a property about $800,000 in the Collingwod area.
Perhaps a waterfront location.

Form: https://myrealesatecompany.com/homes/propertyinfo

Running a test lead:

Setting up a test lead can be done via an app called Postman. Once installed, create a new Request and change the request type to POST. Set the URL to https://app.leadassign.com/extapi/YOUR_company_slug/lead. Assuming you have an auth_token, navigate to the Headers field, create a header with key X-Auth-Token and set the value to auth_token. If you do not have an auth_token, refer to the API Calls section. Then navigate to the Body tag, select raw and change the dropdown value to JSON (application/JSON.) Then, insert the relevant information in the following format:

{
“name”:”customer name”,
“phone”:”customer phone”,
“geolocation_address”:”address that google can use”,
“email”:”customer email”,
“tags”:[
YOUR TAGS HERE
],
“text”:”additional details regarding your lead”,
“source_email”: “email address used to indicate the source of the lead”
}

If you do not wish to specify a field, delete the relevant row from the text above. Hitting the Send button should now create a lead with the information specified in your request. Your Postman workspace should look something like the following:

Performance hints:
Please don’t include things like the head office in the lead body as a footer, or if you do, don’t include postal code, phone, etc. BUT if you have no choice lead assign has some regex that can strip stuff like that out. (The regex widget is called the lead transformer, and its available in the company settings)

Don’t force the agent who accepts the lead to visit a link to see the lead details, as that will mean that Lead Assign cannot figure out where the lead is,etc.

Leads may not include much of an address (think of the lead made when someone wants to buy a house) – they could type a city, province, or similar so that we can geolocate the lead.

Test Authorization POST

https://app.leadassign.com/extapi/company_slug/testauth

Set a header called ‘X-Auth-Token’ with the auth_token you copied after you pressed generate new auth token. (or the SHA256 of it)

simply returns 200 OK if you have a valid token and the company_slug is also correct.

Tom Andersen
tandersen@leadassign.com

Created Oct 13 2017

Checked June 1 2018

Sept 28 2018 – added testauth call.