API Reference

Skrapp API is built around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors.

API Main URL

All of our API endpoints are HTTPS secured. HTTP requests are rejected.

https://api.skrapp.io

Authentication

In order to reach our API endpoints, you need to authenticate using your API key {Your API Key goes here} which you must include in your HTTP request header "X-Access-Key".

Authentication to the API is performed via HTTP Basic Auth.

Your API key serves for authentication and identification, you should keep it secret.

Simple HTTP request with API key

curl https://api.skrapp.io/api/v2/account \
       --header "X-Access-Key={Your API Key goes here}"
    

If you are logged in, your API key is included in all the examples on this page, so you can test any example right away. Only you can see this value.

Account Data

The account data enpoint allows you to retrieve your account data programmatically. Your account data contains your name, email, social accounts, package, package expiry date, email credits and your lists names and IDs.

HTTP Headers
  • X-Access-Key

    Your API key.

JSON Response
  • package

    Your current plan or package.

  • packageRDate

    Your monthly subscription renewal date OR your package expiry date. This depends on your type of enrollment (Monthly OR One Time Purchase).

  • credit

    Your current credits. Used credits and total quota.

  • options

    Your account privileges and options.

  • lists

    Your lists information. This attribute does not return your lists data. Another resource is dedicated to this.

Account request example

curl https://api.skrapp.io/api/v2/account \
          --header "X-Access-Key={Your API Key goes here}"
          

Account JSON Response

{
    "name": "John Doe",
    "email": "john.doe@skrapp.io",
    "package": "Enterprise plan",
    "packageRDate": 1507089600000,
    "credit":{
        "email":{
            "quota":20000,
            "used":1000
        }
    },
    "options":{
        "csv_import":true
    },
    "lists":[
        {
            "id":1,
            "name":"List 1",
            "path":"/app/list/1"
        },
        {
            "id":2,
            "name":"List 2",
            "path":"/app/list/2"
        }
    ]
 }

List Data

The list data API endpoint allows you to access your stored leads programmatically. All you need to provide is the list id in the URL parameter. Lists ids are exposed on the account data endpoint.

URL Parameters
  • listId (/:listId/)

    The id of the list from where you want to retrieve leads.

URL Query Attributes
  • emailOnly optional

    If you want to retrieve only leads with emails, set this query attribute to true. The default value is false.

HTTP Headers
  • X-Access-Key

    Your API key.

List data request example

curl https://api.skrapp.io/api/v2/list/:listId/data?emailOnly=true \
          --header "X-Access-Key={Your API Key goes here}"
          

List data JSON Response

[
        {
            "first_n":"John",
            "last_n":""Doe",
            "email":"john.doe@skrapp.io",
            "title":"Product Manager",
            "location":"Paris, France.",
            "company":"Skrapp",
            "domain":"skrapp.io",
            "company_industry":"Internet",
            "linkedin_url":"in/john-doe/"
        }
        {...}
 ]

Status Codes

Skrapp uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the 5xx range indicate an error with Skrapp's servers.

HTTP status code summary

200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
402 - Request Failed The parameters were valid but the request failed.
404 - Not Found The requested resource doesn't exist.
409 - Conflict The request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors