Enrichment API

API change history

Enrichment API contains methods for retrieving details about person (or company), based on email address (or domain).

EnrichCompany

Retrieve various company details based on the provided domain.

If a webhook URL is provided as part of request, a 202 response is posted back to specified address when available.

Otherwise, if data is ready, it will be returned in response, or 202 status will be returned (and another API call is needed in order to get the data).

Credits are spent only if 2XX response is received.

Try it

Request

Request URL

Request headers

  • string

    The authorization token. The token will be in the format "Bearer API_KEY". For example: "Authorization: Bearer 123456789". Please include the space between "Bearer" and "API_KEY".

Request body

The request body in JSON format includes the following fields:

  • domain (string) Required - The domain name of the company to investigate.
  • webhookUrl (string) - An optional parameter on the request body containing a URL to an endpoint on your service that will accept a posted json response of an enrichment result.

{
    "domain": "touchbasepro.com",
    "webhookUrl": "https://tbpce.requestcatcher.com"
}
{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string"
    },
    "webhookUrl": {
      "type": "string"
    }
  },
  "example": "{\n    \"domain\": \"touchbasepro.com\",\n    \"webhookUrl\": \"https://tbpt.requestcatcher.com\"\n}"
}

Responses

200 OK

The 200 response returns a company object with the following fields:

  • name (string) The name of the company
  • location (string) The address (or location) of the company
  • twitter (string) Twitter handle of the company. Acceptable formats include handle (with or without "@"), as well as the URL to the profile
  • linkedin (string) URL of the company's LinkedIn profile
  • facebook (string) URL of the company's Facebook profile
  • bio (string) The company's bio
  • logo (string) URL to the logo or image for the company
  • website (string) URL to the company's website
  • founded (integer) The year company was founded
  • employees (integer) An approximate number of employees
  • locale (string) The locale of the company
  • category (string) The category of the company. Possible values are Adult, Email Provider, Education, SMS, or Other
  • details (object) Additional company data

Additional company data can contain the following properties:

  • locales (array) Array of Locale records, containing locales for the company
  • categories (array) Array of Category records
  • industries (array) Array of Industry records, containing company industry classification code
  • emails (array) Array of company email records
  • phones (array) Array of phone records
  • profiles (object) Profile record, containing company social profile data,
  • locations (array) Array of company Location records,
  • images (array) Array of Image records for the company, containing URLs of pictures/logos for the company
  • urls (array) Array of Url records for the company, containing URLs associated with the company
  • keywords (array) Array of strings, containing keywords commonly associated with the company and
  • traffic (object) Internet traffic data for the company

Locale record contains the following properties:

  • code (string) Locale code
  • name (string) Locale name

Category record contains the following properties:

  • code (string) Category code. Possible values are: 'Adult', 'Email Provider', 'Education', 'SMS', or 'Other'
  • name (string) Category name

Industry record contains the following properties:

  • type (string) The type of industry classification/code used. Possible values are 'NAICS' or 'SIC'
  • name (string) Industry classification name
  • code (string) Industry classification code

Email record contains the following properties:

  • label (string) Email address label or type (e.g. 'work', 'accounting'...)
  • value (string) Email address

Phone record contains the following properties:

  • label (string) Phone label or type (e.g. 'work', 'accounting'...)
  • value (string) Phone number

Profile record contains the following properties:

  • (platform).username (string) Profile username
  • (platform).userid (string) User ID associated with the profile
  • (platform).url (string) Social platform profile URL
  • (platform).bio (string) Social platform profile bio
  • (platform).service (string) Name of the social platform
  • (platform).followers (integer) Number of follows of the profile, if applicable
  • (platform).following (integer) Number of profiles or topics the user is following, if applicable

Location record contains the following properties:

  • label (string) Location label
  • addressLine1 (string) The first address line
  • addressLine2 (string) The second address line
  • city (string) City name
  • region (string) Region name (typically a state or province)
  • regionCode (string) Region code or abbreviation
  • postalCode (string) Postal or ZIP code
  • country (string) Country name
  • countryCode (string) Country code or abbreviation
  • formatted (string) The formatted address, based on location entry data

Images record contains the following properties:

  • url (string) URL of the photo/logo
  • label (string) The name or type of image

URL record contains the following properties:

  • value (string) The URL or website
  • label (string) The type or name of website

Traffic record contains the following properties:

  • countryRank.(region).rank (string) Company's web traffic rank for the given region
  • countryRank.(region).name (string) The name of the region for the traffic rank
  • localeRank.(locale).rank (string) Company's web traffic rank for the given locale
  • localeRank.(locale).name (string) The name of the locale for the traffic rank

Representations

{
  "name": "TouchBasePro Ltd",
  "location": "57 Buckingham Avenue, Craighall Park, Randburg  Johannesburg Gauteng, 2196 South Africa",
  "twitter": null,
  "linkedin": "https://www.linkedin.com/company/touchbasepro",
  "facebook": null,
  "bio": "TouchBasePro Ltd provides Email Marketing and SMS Marketing.",
  "logo": "https://api.touchbasepro.com/data/df927abe2890dd6d77d84cfe9f2b2946_349b55b91f35fa1d2a7d41cc8db8d29b0ff679d05fcb231ba22e476cdc264455",
  "website": "http://touchbasepro.com",
  "founded": 2004,
  "employees": 5,
  "locale": "en",
  "category": "Other",
  "details": {
    "locales": [
      {
        "code": "en",
        "name": "English"
      }
    ],
    "categories": [
      {
        "code": "OTHER",
        "name": "Other"
      }
    ],
    "industries": [
      {
        "type": "SIC",
        "name": "Computers, Peripherals, and Software",
        "code": "5045"
      },
      {
        "type": "SIC",
        "name": "Custom Computer Programming Services",
        "code": "7371"
      }
    ],
    "emails": [],
    "phones": [
      {
        "value": "(+27) 011 447 9716",
        "label": "other"
      }
    ],
    "profiles": {
      "linkedincompany": {
        "service": "linkedincompany",
        "username": "touchbasepro",
        "url": "https://www.linkedin.com/company/touchbasepro"
      }
    },
    "locations": [
      {
        "label": "work",
        "addressLine1": "57 Buckingham Avenue, Craighall Park, Randburg",
        "city": "Johannesburg",
        "region": "Gauteng",
        "postalCode": "2196",
        "country": "South Africa",
        "countryCode": "ZA",
        "formatted": "57 Buckingham Avenue, Craighall Park, Randburg  Johannesburg Gauteng, 2196 South Africa"
      },
      {
        "country": "south africa",
        "formatted": "     south africa"
      }
    ],
    "images": [
      {
        "value": "https://api.touchbasepro.com/data/df927abe2890dd6d77d84cfe9f2b2946_349b55b91f35fa1d2a7d41cc8db8d29b0ff679d05fcb231ba22e476cdc264455",
        "label": "other"
      }
    ],
    "urls": [
      {
        "value": "http://touchbasepro.com",
        "label": "website"
      }
    ],
    "keywords": [
      "Bulk Email",
      "Bulk Email Solutions",
      "Bulk Sms Solutions",
      "Email Campaigns",
      "Email Marketing Company",
      "Enterprise Email Software",
      "Sms Company",
      "Sms Marketing",
      "Sms Solutions"
    ],
    "keyPeople": [],
    "traffic": {
      "countryRank": {
        "global": {
          "rank": 590297,
          "name": "Global"
        }
      },
      "localeRank": {
        "za": {
          "rank": 5315,
          "name": "South Africa"
        }
      }
    }
  },
  "updated": "2019-03-07"
}
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "location": {
      "type": "string"
    },
    "twitter": {
      "type": "string"
    },
    "linkedin": {
      "type": "string"
    },
    "facebook": {
      "type": "string"
    },
    "bio": {
      "type": "string"
    },
    "logo": {
      "type": "string"
    },
    "website": {
      "type": "string"
    },
    "founded": {
      "type": "integer"
    },
    "employees": {
      "type": "integer"
    },
    "locale": {
      "type": "string"
    },
    "category": {
      "type": "string"
    },
    "details": {
      "type": "object",
      "properties": {
        "entity": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "founded": {
              "type": "integer"
            },
            "employees": {
              "type": "integer"
            }
          },
          "title": "Entity"
        },
        "locales": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            },
            "title": "Category"
          }
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            },
            "title": "Category"
          }
        },
        "industries": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "code": {
                "type": "string"
              }
            },
            "title": "Industry"
          }
        },
        "emails": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "value": {
                "type": "string"
              },
              "label": {
                "type": "string"
              }
            },
            "title": "Email"
          }
        },
        "phones": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "value": {
                "type": "string"
              },
              "label": {
                "type": "string"
              }
            },
            "title": "Email"
          }
        },
        "profiles": {
          "type": "object",
          "properties": {
            "twitter": {
              "type": "object",
              "properties": {
                "username": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "service": {
                  "type": "string"
                },
                "followers": {
                  "type": "integer"
                },
                "following": {
                  "type": "integer"
                }
              },
              "title": "Twitter"
            },
            "linkedin": {
              "type": "object",
              "properties": {
                "username": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "service": {
                  "type": "string"
                }
              },
              "title": "Linkedin"
            }
          },
          "title": "Profiles"
        },
        "locations": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string"
              },
              "addressLine1": {
                "type": "string"
              },
              "addressLine2": {
                "type": "string"
              },
              "city": {
                "type": "string"
              },
              "region": {
                "type": "string"
              },
              "regionCode": {
                "type": "string"
              },
              "postalCode": {
                "type": "string"
              },
              "country": {
                "type": "string"
              },
              "countryCode": {
                "type": "string"
              },
              "formatted": {
                "type": "string"
              }
            },
            "title": "Location"
          }
        },
        "images": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string"
              },
              "label": {
                "type": "string"
              }
            },
            "title": "Image"
          }
        },
        "urls": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "value": {
                "type": "string"
              },
              "label": {
                "type": "string"
              }
            },
            "title": "Email"
          }
        },
        "keywords": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "traffic": {
          "type": "object",
          "properties": {
            "countryRank": {
              "type": "object",
              "properties": {
                "global": {
                  "type": "object",
                  "properties": {
                    "rank": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    }
                  },
                  "title": "Global"
                },
                "us": {
                  "type": "object",
                  "properties": {
                    "rank": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    }
                  },
                  "title": "Global"
                }
              },
              "title": "CountryRank"
            },
            "localeRank": {
              "type": "object",
              "properties": {
                "in": {
                  "type": "object",
                  "properties": {
                    "rank": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    }
                  },
                  "title": "Global"
                },
                "gb": {
                  "type": "object",
                  "properties": {
                    "rank": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    }
                  },
                  "title": "Global"
                },
                "us": {
                  "type": "object",
                  "properties": {
                    "rank": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    }
                  },
                  "title": "Global"
                }
              },
              "title": "LocaleRank"
            }
          },
          "title": "Traffic"
        },
        "keyPeople": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "fullName": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "avatar": {
                "type": "string"
              }
            },
            "title": "KeyPerson"
          }
        }
      },
      "title": "Details"
    },
    "updated": {
      "type": "string"
    }
  }
}

202 Accepted

202 Response can include the following options:

  • If a webhook was included in the request, the response indicates that a response will be returned to the webhook URL.
  • If a webhook was not included, and the response is taking a longer time than expected, the 202 result indicates a successful submission was made, but can not be returned this time. In those cases, a webhook is recommended to receive results without having to resubmit them.

Representations

{
  "status": 202,
  "message": "Queued for search. Try back in a few minutes, or better yet, try using our webhook option by providing a webhookUrl to send results to. Find more info about webhooks here: https://tbp.portal.azure-api.net/docs/services/profile-enrichment/operations/post-enrichprofile?"
}

400 Bad Request

The request was not properly formatted. Please verify the domain name.

Representations

{
  "status": 400,
  "message": "Message not formerly formatted."
}

401 Unauthorized

The API key is invalid. Please verify it is correct and try again.

Representations

{
  "status": 401,
  "message": "API key is invalid."
}

403 Forbidden

Your account has been suspended. Please check with your account representative for more information.

Representations

{
  "status": 403,
  "message": "Your account has been suspended! Please contact our support for more information."
}

405 Method Not Allowed

There is not enough credits on your account

Representations

{
  "status": 405,
  "message": "There's not enough credits on your account"
}

429 Too many requests

The number of API calls has been exceeded. The return will include the number of seconds (represented by (number of seconds) in the example) until the API call can be tried again.

Representations

{
  "status": 429,
  "message": "Rate limit is exceeded.  Try again in {number of seconds} seconds."
}

500 Internal Server Error

Some error occurred in the processing request. Please try it again at a later time.

Representations

{
  "status": 500,
  "message": "An internal error has occurred. We have been notified about it and\nwill restore service functionality as soon as possible."
}

Code samples

@ECHO OFF

curl -v -X POST "https://api.touchbasepro.com/enrich/EnrichCompany"
-H "Authorization: Bearer API_KEY"
-H "Content-Type: application/json"

--data-ascii "{body}" 
using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
        static void Main()
        {
            MakeRequest();
            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }
        
        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);

            // Request headers
            client.DefaultRequestHeaders.Add("Authorization", "Bearer API_KEY");

            var uri = "https://api.touchbasepro.com/enrich/EnrichCompany?" + queryString;

            HttpResponseMessage response;

            // Request body
            byte[] byteData = Encoding.UTF8.GetBytes("{body}");

            using (var content = new ByteArrayContent(byteData))
            {
               content.Headers.ContentType = new MediaTypeHeaderValue("< your content type, i.e. application/json >");
               response = await client.PostAsync(uri, content);
            }

        }
    }
}	
// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample 
{
    public static void main(String[] args) 
    {
        HttpClient httpclient = HttpClients.createDefault();

        try
        {
            URIBuilder builder = new URIBuilder("https://api.touchbasepro.com/enrich/EnrichCompany");


            URI uri = builder.build();
            HttpPost request = new HttpPost(uri);
            request.setHeader("Authorization", "Bearer API_KEY");
            request.setHeader("Content-Type", "application/json");


            // Request body
            StringEntity reqEntity = new StringEntity("{body}");
            request.setEntity(reqEntity);

            HttpResponse response = httpclient.execute(request);
            HttpEntity entity = response.getEntity();

            if (entity != null) 
            {
                System.out.println(EntityUtils.toString(entity));
            }
        }
        catch (Exception e)
        {
            System.out.println(e.getMessage());
        }
    }
}

<!DOCTYPE html>
<html>
<head>
    <title>JSSample</title>
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>

<script type="text/javascript">
    $(function() {
        var params = {
            // Request parameters
        };
      
        $.ajax({
            url: "https://api.touchbasepro.com/enrich/EnrichCompany?" + $.param(params),
            beforeSend: function(xhrObj){
                // Request headers
                xhrObj.setRequestHeader("Authorization","Bearer API_KEY");
                xhrObj.setRequestHeader("Content-Type","application/json");
            },
            type: "POST",
            // Request body
            data: "{body}",
        })
        .done(function(data) {
            alert("success");
        })
        .fail(function() {
            alert("error");
        });
    });
</script>
</body>
</html>
#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
    NSString* path = @"https://api.touchbasepro.com/enrich/EnrichCompany";
    NSArray* array = @[
                         // Request parameters
                         @"entities=true",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];

    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"POST"];
    // Request headers
    [_request setValue:@"Bearer API_KEY" forHTTPHeaderField:@"Authorization"];
    [_request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
    // Request body
    [_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];

    if (nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if (nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];

    return 0;
}
<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';

$request = new Http_Request2('https://api.touchbasepro.com/enrich/EnrichCompany');
$url = $request->getUrl();

$headers = array(
    // Request headers
    'Authorization' => 'Bearer API_KEY',
    'Content-Type' => 'application/json',
);

$request->setHeader($headers);

$parameters = array(
    // Request parameters
);

$url->setQueryVariables($parameters);

$request->setMethod(HTTP_Request2::METHOD_POST);

// Request body
$request->setBody("{body}");

try
{
    $response = $request->send();
    echo $response->getBody();
}
catch (HttpException $ex)
{
    echo $ex;
}

?>
########### Python 2.7 #############
import httplib, urllib, base64

headers = {
    # Request headers
    'Authorization': 'Bearer API_KEY',
    'Content-Type': 'application/json',
}

params = urllib.urlencode({
})

try:
    conn = httplib.HTTPSConnection('api.touchbasepro.com')
    conn.request("POST", "/enrich/EnrichCompany?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
    # Request headers
    'Authorization': 'Bearer API_KEY',
    'Content-Type': 'application/json',
}

params = urllib.parse.urlencode({
})

try:
    conn = http.client.HTTPSConnection('api.touchbasepro.com')
    conn.request("POST", "/enrich/EnrichCompany?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################
require 'net/http'

uri = URI('https://api.touchbasepro.com/enrich/EnrichCompany')


request = Net::HTTP::Post.new(uri.request_uri)
# Request headers
request['Authorization'] = 'Bearer API_KEY'
# Request headers
request['Content-Type'] = 'application/json'
# Request body
request.body = "{body}"

response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body