Api

Inlistio API Documentation (V1)

The Inlistio API enables you to query your connections and retrieve both their current occupation and past jobs. It uses standard RESTful commands and JSON responses, allowing you to connect Inlistio to your internal systems and CRMs, keeping everything in sync automatically.

Not into APIs? You can use Inlistio's API via Salesforce or Zapier instead!

Calling the API

V1 the API is hosted at https://www.inlistio.com/api/v1. All calls use this URL as the base.

Authentication

Inlistio uses token-based authentication. If you're logged into your Inlistio account, you'll see your API key below.

Your API key is <<log in to see your key>>.

Simply include key as a query parameter or a header parameter in your queries, like this: https://www.inlistio.com/api/v1/connections?key=<<log in to see your key>>.

If you don't include an API key or use the wrong one, Inlistio will respond with a 401 authorization error.

Status and Error Codes

Here are the most common HTTP status codes you may receive from our API and what they mean.

  • 200: Request and response were successful.
  • 401: The API key you used was not found.
  • 404: The connection you're looking for wasn't found or is not accessible from your account.
  • 405: The method you attempted was not allowed.
  • 500: There was a server error.

Pagination

All GET calls to the Inlistio API are paginated. Simply append a page= parameter to paginate through the results. You can use the last_page key in the JSON payload to determine if you would like to continue paginating.

Account

Get account information

Retrieves your basic account information including plan usage.

Example

GET https://www.inlistio.com/api/v1/account?key=<<log in to see your key>>

Result

{
  "status": "SUCCESS",
  "message": "Loaded user data",
  "data": {
    "email": "rbucks@gmail.com",
    "connections_count": 7
  }
}

Get ping history

Retrieves a history of your API usage.

Example

GET https://www.inlistio.com/api/v1/account/pings?key=<<log in to see your key>>

Result

{
  "status": "SUCCESS",
  "message": "Loaded pings",
  "data": [
    {
      "query_params": {
        "key": "54e30766279d9186adccfaaf0809d389",
        "query": "ryan@scripted.com",
        "action": "search",
        "format": "json",
        "controller": "api/v1/connections"
      },
      "endpoint": "connections#search",
      "created_at": "2018-02-20T05:50:21.662Z"
    }
  ],
  "last_page": false
}

Search ping history

Search the history of your API usage.

Parameters
query (required)
Text you want to search. It will search the endpoint and query_params fields
Example

GET https://www.inlistio.com/api/v1/account/pings/search?key=<<log in to see your key>>&query=create

Result

{
  "status": "SUCCESS",
  "message": "Loaded pings",
  "data": [
    {
      "query_params": {
        "key": "54e30666279d9186adccfaaf0809d123",
        "query": "ryan@scripted.com",
        "action": "search",
        "format": "json",
        "controller": "api/v1/connections"
      },
      "endpoint": "connections#create",
      "created_at": "2018-02-20T05:50:21.662Z"
    }
  ],
  "last_page": true
}

Connections

Get all connections

Retrieves a paginated list of all of your connections.

Example

Use GET https://www.inlistio.com/api/v1/connections?key=<<log in to see your key>> for all connections or GET https://www.inlistio.com/api/v1/connections?key=<<log in to see your key>>&has_new_job=true for only connections with new jobs.

Result

{
  "status": "SUCCESS",
  "message": "Loaded all connections.",
  "data": [
    {
      "id": 2758,
      "created_at": "2018-02-21T16:21:10.283Z",
      "has_new_job": false,
      "first_name": "ryan",
      "last_name": "buckley",
      "linkedin_url": "https://www.linkedin.com/in/rbuckley",
      "facebook_url": "https://www.facebook.com/rbucks",
      "twitter_url": "https://twitter.com/rbucks",
      "avatar_url": "https://d2ojpxxtu63wzl.cloudfront.net/static/bb01b76057252a4e3a1218b3e7ab4e1d_8c112ae46c1c884d84c3b0a5e7184b293c18db0d8508062a049ce1a16e67dfa9",
      "location": "San Francisco, CA, US",
      "in_eu?": false,
      "starting_employment": {
        "email": "ryan@scripted.com",
        "title": "ceo",
        "company": "scripted",
        "started_at": null,
        "ended_at": null,
        "current": false,
        "email_confidence": null
      },
      "current_employment": {
        "email": "ryan@toofr.com",
        "title": "founder",
        "company": "toofr",
        "started_at": "2017-07-01",
        "ended_at": null,
        "current": true,
        "email_confidence": 116
      }
    }
  ],
  "last_page": true,
  "total_count": 1
}

Add a new connection

Creates a new connection for Inlistio to track on your account.

Parameters
email (required)
Properly formed email address of the new connection
first_name (optional)
First name of the new connection
last_name (optional)
Last name of the new connection
company (optional)
Company name on your record
title (optional)
Job title on your record
Example

POST https://www.inlistio.com/api/v1/connections?key=<<log in to see your key>>&email=ryan@inlistio.com

Result

{
  "status": "SUCCESS",
  "message": "Your connection is processing. Use the ID to check again in a few minutes.",
  "data": {
    "id": 2761,
    "created_at": "2018-02-21T16:37:54.865Z",
    "has_new_job": null,
    "first_name": "ryan",
    "last_name": "buckley",
    "linkedin_url": null,
    "facebook_url": null,
    "twitter_url": null,
    "avatar_url": null,
    "location": "",
    "starting_employment": {
      "email": "ryan@toofr.com",
      "title": "ceo",
      "company": "toofr",
      "started_at": null,
      "ended_at": null,
      "current": null,
      "email_confidence": null
    }
  }
}

Search your connections

Retrieves the employments given a set of search parameters. Retrieve the connection_id from the Get all connections result and include it in the URL address.

Parameters
query (required)
First name, last name, email, company, or title of your connections
Example

GET https://www.inlistio.com/api/v1/connections/search?key=<<log in to see your key>>&query=ryan@toofr.com

Result

A successful result will look like this.

{
  "status": "SUCCESS",
  "message": "Searched your connections.",
  "data": [
    {
      "id": 2758,
      "created_at": "2018-02-21T16:21:10.283Z",
      "has_new_job": false,
      "first_name": "ryan",
      "last_name": "buckley",
      "linkedin_url": "https://www.linkedin.com/in/rbuckley",
      "facebook_url": "https://www.facebook.com/rbucks",
      "twitter_url": "https://twitter.com/rbucks",
      "avatar_url": "https://d2ojpxxtu63wzl.cloudfront.net/static/bb01b76057252a4e3a1218b3e7ab4e1d_8c112ae46c1c884d84c3b0a5e7184b293c18db0d8508062a049ce1a16e67dfa9",
      "location": "San Francisco, CA, US",
      "in_eu?": false,
      "starting_employment": {
        "email": "ryan@scripted.com",
        "title": "ceo",
        "company": "scripted",
        "started_at": null,
        "ended_at": null,
        "current": false,
        "email_confidence": null
      },
      "current_employment": {
        "email": "ryan@toofr.com",
        "title": "founder",
        "company": "toofr",
        "started_at": "2017-07-01",
        "ended_at": null,
        "current": true,
        "email_confidence": 116
      }
    },
    {
      "id": 2761,
      "created_at": "2018-02-21T16:37:54.865Z",
      "has_new_job": false,
      "first_name": "ryan",
      "last_name": "buckley",
      "linkedin_url": "https://www.linkedin.com/in/rbuckley",
      "facebook_url": "https://www.facebook.com/rbucks",
      "twitter_url": "https://twitter.com/rbucks",
      "avatar_url": "https://d2ojpxxtu63wzl.cloudfront.net/static/bb01b76057252a4e3a1218b3e7ab4e1d_8c112ae46c1c884d84c3b0a5e7184b293c18db0d8508062a049ce1a16e67dfa9",
      "location": "San Francisco, CA, US",
      "starting_employment": {
        "email": "ryan@toofr.com",
        "title": "ceo",
        "company": "toofr",
        "started_at": "2017-07-01",
        "ended_at": null,
        "current": false,
        "email_confidence": null
      },
      "current_employment": {
        "email": "ryan@toofr.com",
        "title": "advisor",
        "company": "toofr llc",
        "started_at": "2012-06-01",
        "ended_at": null,
        "current": true,
        "email_confidence": 116
      }
    }
  ],
  "last_page": true,
  "total_count": 2
}

Harvest connections

Creates a pool of connections from which you can harvest job changes.

Parameters
company (required)
The name of the company or account you are targeting
term (required)
Query term (one word) describing the job or position
Example

POST https://www.inlistio.com/api/v1/connections/harvest?key=<<log in to see your key>>&company=salesforce&term=engineering

Result

{
  "status": "SUCCESS",
  "message": "Harvester job is queued."
}

Destroy all connections

Permanently deletes all of your connections. BE CAREFUL WITH THIS ENDPOINT! It cannot be undone.

Example

GET https://www.inlistio.com/api/v1/connections/destroy_all?key=<<log in to see your key>>

Result

{
  "status": "SUCCESS",
  "message": "Destroyed all connections."
}

Employments

Get all employments from a connection

Retrieves the employment history of a given connection. Retrieve the connection_id from the Get all connections result and include it in the URL address.

Parameters
Connection ID (required)
The ID of the connection retrieved from the GET Connections call
Example

GET https://www.inlistio.com/api/v1/connections/:id/employments?key=<<log in to see your key>>

Result

A successful result will look like this.

{
  "status": "SUCCESS",
  "message": "Loaded all employments.",
  "data": [
    {
      "id": 3481,
      "email": "ryan@toofr.com",
      "title": "founder",
      "company": "toofr",
      "started_at": "2017-07-01",
      "ended_at": null,
      "current": true,
      "email_confidence": 116,
      "connection_id": 2758
    },
    {
      "id": 3483,
      "email": "ryan@toofr.com",
      "title": "advisor",
      "company": "toofr llc",
      "started_at": "2012-06-01",
      "ended_at": null,
      "current": false,
      "email_confidence": 116,
      "connection_id": 2758
    },
    {
      "id": 3484,
      "email": "ryan@rapleaf.com",
      "title": "business development",
      "company": "rapleaf",
      "started_at": "2010-09-01",
      "ended_at": "2011-04-01",
      "current": false,
      "email_confidence": 24,
      "connection_id": 2758
    },
    {
      "id": 3482,
      "email": "ryan.buckley@hired.com",
      "title": "advisor",
      "company": "hired, inc",
      "started_at": "2012-11-01",
      "ended_at": null,
      "current": false,
      "email_confidence": 21,
      "connection_id": 2758
    },
    {
      "id": 3480,
      "email": "ryan@scripted.com",
      "title": "ceo",
      "company": "scripted",
      "started_at": null,
      "ended_at": null,
      "current": false,
      "email_confidence": null,
      "connection_id": 2758
    }
  ],
  "last_page": true,
  "total_count": 5
}