NAV Navbar
Logo

Email Lookup

curl -X GET -H "X-Api-Key: your_api_key" "https://api.usergems.com/v1/person?email=support@usergems.com&first_name=Michael&last_name=Smith&company_name=UserGems"

The above command returns JSON structured like this:

{
    "name": "Firstname Lastname",
    "email": "support@usergems.com",
    "gender" : "female",
    "avatar": "https://pbs.twimg.com/profile_image.jpg",
    "location": {
        "display_name": "2 Townsend Street, San Francisco, California, 94107, US"
    },
    "bio": "This is me and what I'm doing",
    "angellist": {
        "url" : "https://angel.co/testuser",
        "bio": "This is me and what I'm doing on Angellist",
        "followers": 600
    },
        "followers": 500
    },
    "facebook": {
        "url" : "https://www.facebook.com/testuser",
        "friends": 800,
        "followers": 600,
        "engagement": 22,
        "engagement_percent": 0.03929
    },
    "twitter": {
        "url" : "https://www.twitter.com/testuser",
        "bio": "This is me and what I'm doing on Twitter",
        "followers": 18129,
        "posts": 3989,
        "engagement": 8,
        "engagement_percent": 0.00010
    },
    "pinterest": {
        "url" : "https://www.pinterest.com/testuser",
        "bio": "This is me and what I'm doing on Pinterest",
        "followers": 19903
    },
    "instagram": {
        "url": "https://www.instagram.com/testuser",
        "bio": "This is me and what I'm doing on Instagram",
        "followers": 19425,
        "is_private": 0,
        "posts": 792,
        "engagement": 121,
        "engagement_percent": 0.00620
    },
    "youtube": {
        "url": "https://www.youtube.com/user/testuser",
        "followers": 530,
        "posts": 166,
        "engagement": 1886,
        "engagement_percent": 3.55261
    },
    "max_followers": 19903,
    "sum_followers": 61755
}

If we don’t find information, we’ll return the following:

{
    "email": "support@usergems.com",
    "message": "No results found for this email."
}

UserGems returns information to individual email addresses via its API.

If available, the API will immediately return information about the specified email address. If no information is available, UserGems will start to collect new data and either send this information to a specified webhook or present it when requested again.

HTTP Request

GET https://api.usergems.com/v1/person

Authentication

Please use your API Key to authenticate your request. You can request a new API Key via email to support@usergems.com. The API key must be included in a header that looks like the following:

X-Api-Key: your_api_key

Query Parameters

Parameter Values Mandatory Description
email string X The person’s email address
first_name string The first name of the person
last_name string The last name of the person
company_name string The name of the company where the person works or worked
webhook string Callback URL to which we’ll POST the person’s information.

Please note: If you add a webhook, the return of the lookup will always be {"result": "Email address added to queue"} and the user information will be POSTed to the webhook.

Email Lookup - Bulk

curl -X POST -H "X-Api-Key: your_api_key" --data-urlencode '{
  "emails" : ["support@usergems.com", "support1@usergems.com"]
}' "https://api.usergems.com/v1/person"


The above command returns JSON structured like this:

{
    "result": "Email address added to queue"
}

UserGems allows to analyze email addresses via its Bulk API. The Bulk API requires a webhook url and sends all results to this webhook.

The request will not return information about the specified email addresses, but will only return {"result": "Email address added to queue"}.

HTTP Request

POST https://api.usergems.com/v1/person

Authentication

Please use your API Key to authenticate your request. You can request a new API Key via email to support@usergems.com. The API key must be included in a header that looks like the following:

X-Api-Key: your_api_key

Query Parameters

Parameter Values Mandatory Description
emails array X The person’s email address
Please note: The maximum array size is 1,000.
webhook string X Callback URL to which we’ll POST the person’s information.

Risk Lookup

curl -X GET -H "X-Api-Key: your_api_key" -G --data-urlencode '{
  "email" : "support@usergems.com"
}' "https://www.usergems.com/api/risk"


The above command returns JSON structured like this:

{
    "email": "support@usergems.com",
    "risk_score" : 17,
    "risk_level": "level"
}

If we don’t find information, we’ll return the following:

{
    "email": "support@usergems.com",
    "message": "No results found for this email."
}

UserGems returns a risk assessment for an individual email addresses via its API.

If available, the API will immediately return information about the specified email address. If no information is available, UserGems will start to collect new data and either send this information to a specified webhook or present it when requested again.

HTTP Request

GET https://www.usergems.com/api/risk

Authentication

Please use your API Key to authenticate your request. You can request a new API Key via email to support@usergems.com. The API key must be included in a header that looks like the following:

X-Api-Key: your_api_key

Query Parameters

Parameter Values Mandatory Description
email string X The person’s email address
webhook string Callback URL to which we’ll POST the person’s information.

Please note: If you add a webhook, the return of the lookup will always be {"result": "Email address added to queue"} and the user information will be POSTed to the webhook.

Export

curl -X GET -H "Authorization: Bearer user_token" -G --data-urlencode '{
  "file_name" : "upload.xls",
  "email" : "support@usergems.com",
  "date_from" : "2016-08-04",
  "date_to" : "2016-09-04",
  "min" : 1000,
  "max" : 1000000,
  "keyword" : "blogger",
  "facebook" : 1,
  "twitter" : 0,
  "instagram" : 0,
  "youtube" : 1,
  "googleplus" : 1,
  "pinterest" : 0
}' "https://www.usergems.com/api/export"



The above command returns JSON structured like this:

[
  {
    "name": "Firstname Lastname",
    "email": "support@usergems.com",
    "email_encrypted" : "[encrypted_value]",
    "gender" : "female",
    "avatar": "https://pbs.twimg.com/profile_image.jpg",
    "location": "San Francisco",
    "bio": "This is me and what I'm doing",
    "angellist_bio": "This is me and what I'm doing on Angellist",
    "angellist_followers": 600,
    "facebook": "https://www.facebook.com/testuser",
    "facebook_friends": 1634,
    "facebook_followers": 460,
    "facebook_engagement": 22,
    "facebook_engagement_percent": 0.039285714285714,
    "twitter": "https://www.twitter.com/testuser",
    "twitter_bio": "This is me and what I'm doing on Twitter",
    "twitter_followers": 18129,
    "twitter_posts": 3989,
    "twitter_engagement": 8,
    "twitter_engagement_percent": 0.00010239475738842,
    "pinterest": "https://www.pinterest.com/testuser",
    "pinterest_followers": 19903,
    "instagram": "https://www.instagram.com/testuser",
    "instagram_bio": "This is me and what I'm doing on Instagram",
    "instagram_followers": 19425,
    "instagram_posts": 792,
    "instagram_engagement": 121,
    "instagram_engagement_percent": 0.0062290862290862,
    "youtube": "https://www.youtube.com/user/testuser",
    "youtube_followers": 530,
    "youtube_posts": 166,
    "youtube_engagement": 1886,
    "youtube_engagement_percent": 3.5584905660377,
    "googleplus": "https://plus.google.com/1234567890",
    "googleplus_followers": 662,
    "klout": "https://www.klout.com/testuser",
    "klout_score": 66,
    "max_followers": 19903,
    "sum_followers": 61755
  },
  {
    "name": "Firstname2 Lastname2",
    "...": "..."
  }
]

Filter and export all user information from your UserGems account.

This includes all email addresses you looked up via API as well as all email addresses you uploaded via CSV, XLS or XLSX.

HTTP Request

GET https://www.usergems.com/api/export

Authentication

Every request needs to include a token. Please refer to “Create Token” to learn how you can retrieve a token.

The token must be included in a header that looks like the following:

Authorization: Bearer user_token

URL Parameters

Parameter Values Mandatory Description
file_name string Select a specific file to export
email string Select a specific email to export
date_from string Export only users added after/on a specific date (e.g. 2016-08-04)
date_to string Export only users added before/on a specific date (e.g. 2016-08-04)
min integer Select the minimum number of followers a user needs to have
max integer Set the maximum number of followers a user needs to have
keyword string Filter your export with a keyword. Only users with that keyword in any of their information (name, email, bio, professional & educational experience) will be exported.
facebook boolean Only users with a Facebook account will be exported.
twitter boolean Only users with a Twitter account will be exported.
instagram boolean Only users with a Instagram account will be exported.
youtube boolean Only users with a YouTube account will be exported.
googleplus boolean Only users with a Google+ account will be exported.
pinterest boolean Only users with a Pinterest account will be exported.

Create Token

To authorize, use this code:

# With shell, you can just pass the correct header with each request

curl -X POST -H "Content-Type: application/json" -d '{
"email": "test@test.com",
"password" : "my_password"
}' "https://www.usergems.com/api/token/create"

The above command returns JSON structured like this:

{
  "user_token": "eyJ0eXAiOikKV1QiLCJhbGciOiJ...iYzk0In0.6lKQNVEOZqHmXoixl6"
}

Some API requests need to include a user_token in the header. The created token will be valid for 120 minutes.

HTTP Request

POST https://www.usergems.com/api/token/create

Query Parameters

Parameter Values Mandatory Description
email string X The email address you signed up with
password string X The password you signed up with

Errors

The UserGems API uses the following error codes:

Error Code Meaning
400 Bad Request
401 Unauthorized
403 Forbidden – You are not allowed to access this resource
404 Not Found
405 Method Not Allowed
406 Not Acceptable – You requested a format that isn’t json
410 Gone
429 Too Many Requests
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.