Welcome to the leadgenius API. Below is the layout and relevant use cases.
| STATUS CODES | DESCRIPTION |
|---|---|
| 200 OK | Request processed successfully, look at response object for details |
| 202 Accepted | Means the request has been put in a queue for processing |
| 400 Bad Request | Request is malformed, or missing required data. See response object for details |
| 403 Unauthorized | Unauthorized request, check your API Key |
| 404 | Not found. |
| 500 Internal Server Error | There was an unexpected error on our server. If you see this please contact us. |
All methods are rate limited based on your API key. Other restrictions may apply, such as, file size or limits on the number of jobs submitted.
Make sure to check the response objects when getting a ```403`` error.
To authenticate, insert your key into the header of your request. The header value is: X-LG-API-KEY
import requests
r = requests.get(
'http:///api.leadgenius.com/emailguess/v1/status/29',
headers={'X-LG-API-KEY': 'mykey'}
)
METHOD: GET
DESCRIPTION: Retrieve the status of a non-bulk job by it's id
{
"status": 200,
"result": "foo@bar.com"
}
{
"status": 202
}
{
"status": 404,
result: "Not Found"
}
import requests
r = requests.get(
'http:///api.leadgenius.com/emailguess/v1/job/status/29',
headers={'X-LG-API-KEY': 'mykey'}
)
METHOD: POST
DESCRIPTION: Submit a job for search.
RATELIMIT: 300/min
SUBMISSION OBJECT SCHEMA:
{
"first": {
"type": "string",
"required": True
},
"middle": {
"type": "string",
"required": True
}
"last": {
"type": "string",
"required": True
},
"domain": {
"type": "string",
"required": True
},
"use_smtp_sniff": {
"type": "boolean",
"required": False,
"default": False
},
'use_catch_all': {
'type': 'boolean',
'required': False,
'default': False
}
}
NOTE: use_smtp_sniff will be ignored if it is not on your account contract.
{
"status": 202,
"id": "somejobid"
}
{"message": "First name is required"}
{
"status": 404,
result: "Not Found"
}
import requests, json
r = requests.post(
'http:///api.leadgenius.com/emailguess/v1/job/submit',
headers={'X-LG-API-KEY': 'mykey'},
data=json.dumps(
dict(
first='chris',
last='george',
middle='',
domain='foo.com',
use_smtp_sniff=True
)
)
)
if r.status_code == 202:
#submit jobid to some queue to look up status
jobid = r.json().get('id')
METHOD: POST
DESCRIPTION: Submit a bulk job for search.
RATELIMIT: 5000 objects to find/hour.
SUBMISSION OBJECT SCHEMA:
{
"data": [
{
"first": {
"type": "string",
"required": True
},
"middle": {
"type": "string",
"required": True
}
"last": {
"type": "string",
"required": True
},
"domain": {
"type": "string",
"required": True
}
}
],
"options": {
'use_smtp_sniff': {
'type': 'boolean',
'required': False,
'default': False
},
'use_catch_all': {
'type': 'boolean',
'required': False,
'default': False
}
},
'webhook_url': {
'type': 'string',
'required': False
}
}
NOTE: use_smtp_sniff will be ignored if it is not on your account contract.
It is strongly suggested that, instead of using a status call, webhook urls are implemented for bulk jobs. When the job finishes, we call your callback url.
In doing so, we return a match for every sub job in the batch e.g. for Chris George at LeadGenius, we could return multiple emails.
You'll see that the response will include a webhookid. This is a semi-colon split string that contains: bulk job id, sub job id, and email.
An example: 1;2;foo@leadgenius.com
It's important to note, that we retry hitting the url three times in three minutes before giving up*.
{
"status": 202,
"job_id": 1232
}
{
"status": 200,
"webhook_id": "1;2;foo@leadgenius.com",
"result": {
"bulk_id": 2,
"domain": "leadgenius.com",
"first": "foo",
"jobid": 2,
"last": "bar",
"middle": "",
"email": "foo@leadgenius.com"
}
}
{
"status": 400,
"error": "Message about issue"
}
import requests, json
r = requests.post(
'http:///api.leadgenius.com/emailguess/v1/bulk/job',
headers={'X-LG-API-KEY': 'mykey'},
data=json.dumps(dict(
data=[
dict(
first='chris',
last='george',
middle='',
domain='foo.com'
)
],
options=dict(use_smtp_sniff=True),
webhook_url='http://myawesomewebhook/callback'
))
)
if r.status_code == 202:
#submit jobid to some queue to look up status
jobid = r.json().get('id')
METHOD: GET
DESCRIPTION: Look up the status of a bulk job.
RATELIMIT: 1/min, 60/hour
###EXAMPLE
import requests
r = requests.get(
'http:///api.leadgenius.com/v1/emailguess/bulk/job/status/2999',
headers={'X-LG-API-KEY': 'mykey'}
)
if r.status_code == 200:
result = r.json()
elif r.status_code >= 400:
#handle errors
###RESPONSE OBJECTS ####SUCCESS
{
"status": 200,
"results": {
"results": [
{
"first": "foo",
"middle": "baz",
"last": "bar",
"email": "foo@baz.com"
}
],
"failed": 10,
"total": 1000,
"completed": false
}
}
####ERROR
{
"status": 500,
"error": "Some message"
}