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 Authentication header.
$ 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.
GraphQL Explorer¶
One of the many tools from the GraphQL ecosystem is graphiql which offers an interactive dashboard to assist you in developing against the Mattermark API. While you can follow the instructions in the previous link to get up and running, if you have access to a Docker environment, you can run the following to get a graphiql explorer instance running locally:
docker-machine start default eval $(docker-machine env default) docker run -it -p3000:3000 vitalcode/auth-graphiql or docker run -it -p=3000:3000 vitalcode/auth-graphiql
then open your browser to http://localhost:3000/graphql, set the Host field to https://eapi.mattermark.com and Token to your Enterprise API token.
Schema¶
Since GraphQL allows for static binding of your queries, many clients will consume the API schema to perform compile or runtime validations. You can query the API using the introspection query at runtime or can download the JSON response here
Note
For the latest schema, it is recommended running the introspection query against the API
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. |
Query types¶
There are four main query types you can run against the Mattermark API:
organizationandorganizationscontactDetailsfundingRoundSummaryQueryorganizationSummaryQueryviewer
organization¶
An organization query searches Mattermark for a company or investor by domain or id.
Lookups by id take the form organization(id: "c#146589") where c# indicates that the id is for a company (#i is used for investor).
A search by domain like organization(domain: "mattermark.com") will return null if the company is not found.
id will take precedence if both domain and id arguments are included in the query.
An organizations query accepts lists of ids and domains as arguments. The response will include a JSON array of organization elements in the same order that the ids and domains are specified. A null in the list indicates that the company / investor was not found.
Note
A single organizations query can mix both ids and domains arguments but there is a maximum of 5 organizations requested per query.
contactDetails¶
Given a full name and organization id, contactDetails will attempt to find the person’s email address.
For example:
{
contactDetails(name: "Danielle Morrill", orgId: "c#146589") {
name
email
}
}
A null email address indicates that contact information is unavailable.
fundingRoundSummaryQuery¶
Returns a history of funding rounds that can be filtered by various parameters including the date of funding, funding amount range, and investor slugs. This query allows for pagination and there’s a limit of 50 rounds returned per call.
The full list of query parameters are under fundingRoundSummaryQuery here.
Note that for parameters supporting lists like series, each one is OR’d together. So series:["seed","e"] would request funding rounds that are either series seed or e.
organizationSummaryQuery¶
This type is most useful to retrieve a list of companies when you do not already know the names of the companies you want, but instead want to query on other identifying characteristics like employee count, industry tags, funding date and location. See here for more details on what MSFL is and how it can be used to filter through companies and investors.
Note
An organizationSummaryQuery will return OrganizationSummary objects containing a brief snapshot of available information such as the id, name and description for the company or investor represented. An organization[s] query can then be used to return a full view of all Mattermark information on the organization.
Viewer¶
This query returns information on the current API account / user including quota information.
{
viewer {
email
company
quota {
remaining
}
id
fullName
}
}