Getting Started

You’ll need an active Mattermark account to make API requests. Start your free trial or contact sales@mattermark.com.

Authentication

In order to make calls to our API you need to include your API key along with the request. You can obtain your API key from your API settings page.

We look for your API key in the key query parameter or the Authentication header.

$ curl "https://api.mattermark.com/companies?key=[YOUR KEY]"

$ curl "https://api.mattermark.com/companies"
  -H "Authorization: Bearer [YOUR KEY]"

It is very important to store your API key in a private and secure location. Sharing your API key is strictly prohibited.

Example Request

If you want to make a call to our companies listing endpoint: https://api.mattermark.com/companies you simply adjust the URL to include your API key like so:

$ curl "https://api.mattermark.com/companies"
    -H "Authorization: Bearer [YOUR KEY]"

Note

You must replace [YOUR KEY] with your Mattermark Enterprise API key.

Limits and Paging

Requests that return more than a single result will often times be “paged” such that we return a limited number of records for each request. Endpoints that support paging will be noted in their respective documentation sections.

How many pages or results are there for my request?

Endpoints that support paging will have a special section in the response body. The section to pay attention to for paging information is in the “meta” portion of the response body. Below is an example meta section:

{
  "meta": {
    "total_record_count": 605,
    "total_pages": 13,
    "current_page": 1,
    "per_page": 50
  }
}

How do I page through my results?

The following table shows you the two url query parameters that you can tweak to page through results.

Parameter Default Value Description
per_page 10 You can adjust this value to receive more or less records per request.
page 1 If the response says there are more results than the number returned. You change this value to read more records from result set.

Example Request

The best example of where paging can be useful is when using the Companies List endpoint. It is quite common that you will issue a query and it will match a significant number of records. For example, when you ask for Series A companies in the Bay Area, there are more than 850 results. To keep things speedy, we will only return 50 results at a time. The following example will show you how to read subsequent pages of results.

$ curl "https://api.mattermark.com/companies?stage=a&location=bay%20area&page=2&per_page=50"
    -H "Authorization: Bearer [YOUR KEY]"

Quota & Usage

Each request will return your current usage in the response headers.

Header Description
X-Quota-Limit Your current request limit
X-Quota-Remaining Number of remainging requests in the current period
X-Quota-Reset The unix timestamp (seconds, UTC) of the start of the next quota period.

You can check your quota any time by making a call to the usage endpoint: https://api.mattermark.com/ratelimit/usage. Requests to this endpoint don’t count against your quota.

$ curl "https://api.mattermark.com/ratelimit/usage"
  -H "Authorization: Bearer [YOUR KEY]"  
[
  {
    "quota_limit":10000,
    "quota_remaining":9999,
    "quota_reset":1498694400,
    "quota_period":1498694400
  }
]

Rate Limiting

In order to assure high quality of service to all our customers our API enforces rate limiting rules. If you have exceeded your account’s rate limit we will return a 429 status code.

Response Codes and Errors

The Mattermark API will send responses back to your requests using one of the following HTTP codes:

Response Code Meaning
200 Ok – Everything worked great!
400 Bad Request – Your request was not properly sent.
403 Unauthorized – Your API key is wrong, is no longer valid, or you do not have access to the given resource.
404 Not Found – The specified endpoint could not be found
429 Rate Limit Exceeded – You have temporarily exceeded your rate limit. Refer to Rate Limits for more details.
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Example Request/Response Handling

require 'httparty'
begin
  response = HTTParty.get("https://api.mattermark.com/companies/74910?key=[YOUR KEY]")
  if response.code == 200
    # hurray, request succeeded. Read a value from the response.
    company = {
      name: response['name'],
      website: response['website']
    }
    puts company.inspect
  else
    # oh no, the request failed, read the status code to determine why
    case request.code
      when 500, 503
        puts 'The Mattermark API is offline. Try again later.'
      when 403
        puts 'Access was denied to the Mattermark API'
      when 404
        puts 'Not Found. The resource you are accessing does not exist.'
      when 400
        puts 'Bad Request. Your request was improperly formatted or attempts to perform an unsupported operation.'
      end
  end
rescue SocketError => e
  # This catches cases when the network connection fails during the request.
  puts "Connection failed: #{e.message}"
end