openapi: 3.2.0
info:
  description: Mattermark REST API
  version: 1.0.0
  title: Mattermark REST Companies API
  contact:
    email: support@mattermark.com
servers:
- url: https://api.mattermark.com
security:
- APIKeyHeaderParam: []
tags:
- name: Companies
paths:
  /companies:
    get:
      tags:
      - Companies
      summary: Retrieve a list of companies
      operationId: get_companies
      description: The company list allows you to retrieve all companies, or a list of companies filtered by one or many parameters. For parameters marked as arrays, you can “OR” together different options with the pipe `|` operator.
      parameters:
      - in: query
        name: domain
        description: The domain of the company’s website.
        schema:
          type: string
      - in: query
        name: company_name
        description: The company’s name.
        schema:
          type: string
      - in: query
        name: added_date
        description: The date the company started being tracked by Mattermark. Supports a range operation by using the `~` character on either side of a single date value or between two values
        schema:
          type: string
          format: date_range
      - in: query
        name: mattermark_score
        description: The current Mattermark score of the company.
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: momentum_score
        description: The latest weekly momentum score of the company.
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: employees
        description: The number of employees currently at the company.
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: employees_month_ago
        description: Count of employees one month ago.
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: employees_added_in_month
        description: Count of employees added this month.
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: employees_mom
        description: The percent employee growth during that month.
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: cached_uniques
        description: The estimated monthly unique visitors to the company’s website.
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: cached_uniques_week_ago
        description: The estimated monthly unique visitors to the company’s website during the past 7 days.
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: uniques_wow
        description: The percent change in the estimated monthly unique visitors to the company’s website in the past 7 days.
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: cached_uniques_month_ago
        description: The estimated monthly unique visitors to the company’s website during the past month.
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: uniques_mom
        description: The percent change in the estimated monthly unique visitors to the company’s website in the past month.
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: cached_mobile_downloads
        description: The estimated monthly mobile downloads from the U.S. iTunes app store.
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: cached_mobile_downloads_week_ago
        description: The estimated monthly mobile downloads one week ago from the U.S. iTunes app store.
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: mobile_downloads_wow
        description: The change in the estimated monthly mobile downloads from the U.S. iTunes app store during the past week.
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: cached_mobile_downloads_month_ago
        description: The count of the estimated monthly mobile downloads from the U.S. iTunes app store during the past month.
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: mobile_downloads_mom
        description: The growth of the estimated monthly mobile downloads from the U.S. iTunes app store during the past month.
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: est_founding_date
        description: The estimated founding date of the company.
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - within 3 months
            - within 6 months
            - within 9 months
            - within 1 year
            - within 2 years
            - within 3 years
            - within 5 years
            - within 10 years
      - in: query
        name: stage
        description: The most recent funding round for the company.
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - Unknown
            - No Known Funding
            - Pre Series A
            - a
            - b
            - c
            - d
            - e
            - f
            - g
            - h
            - i
            - Late
            - Exited
      - in: query
        name: investors
        description: In order to filter a list of companies by investor, you'll need the `mm_slug` value for the specific investor(s). You can get the mm_slug value for any investor in our index by using the Investors endpoint.
        schema:
          type: string
      - in: query
        name: total_funding
        description: The total publicly reported money raised by the company. Only includes money raised in U.S. Dollars. Other currencies are returned in detail response, but not included in this total.
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: last_funding_date
        description: Date of last funding event.
        schema:
          type: array
          items:
            type: string
            enum:
            - not in past 3 months
            - not in past 6 months
            - not in past 9 months
            - not in past year
            - not in past 13 months
            - not in past 16 months
            - not in past 18 months
            - not in past 2 years
            - never raised
            - raised in past 3 months
            - raised in past 6 months
            - raised in past 9 months
            - raised in past year
            - raised in past 2 years
            - has ever raised
      - in: query
        name: last_funding_amount
        description: The amount of funding investment in the the most recent funding event
        schema:
          type: integer
          format: numeric_range
      - in: query
        name: location
        description: A pipe-delimited list of locations. This could be something like `Bay Area` or `San Francisco`
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: state
        description: State (location in the US) of the company’s headquarters.
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: has_google_play
        description: Companies that have a Google Play application.
        schema:
          type: string
          enum:
          - 0
          - 1
      - in: query
        name: has_itunes
        description: Companies that have an iTunes application.
        schema:
          type: string
          enum:
          - 0
          - 1
      - in: query
        name: play_category
        description: The Google Play store categories of applications associated with the company
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: itunes_category
        description: The iTunes store categories of applications associated with the company
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: business_models
        description: The business models employed by the company to generate revenue.
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: industries
        description: The industries the company operates within.
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: keywords
        description: Keywords associated with the company.
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/limitParam'
      responses:
        200:
          description: A company object
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/companies'
              example:
                meta:
                  total_record_count: 1
                  total_pages: 1
                  current_page: 1
                  per_page: 10
                companies:
                - company_name: Blue Smoke LLC
                  domain: bluesmokellc.net
                  id: '10808576'
                  url: https://api.mattermark.com/companies/10808576
        400:
          description: bad input parameter
  /companies/{id}:
    get:
      tags:
      - Companies
      summary: Retrieve a specific company
      operationId: get_company
      description: The company list allows you to retrieve all companies, or a list of companies filtered by one or many parameters. For parameters marked as arrays, you can “OR” together different options with the pipe `|` operator.
      parameters:
      - in: path
        name: id
        description: The ID of the company to retrieve
        required: true
        schema:
          type: string
      responses:
        200:
          description: A company object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyItem'
  /companies/{id}/stories:
    get:
      tags:
      - Companies
      summary: Retrieve company news articles
      operationId: get_company_stories
      description: The company stories endpoint retrieves the 50 latest news articles about the specified company
      parameters:
      - in: path
        name: id
        description: The ID of the company to retrieve news for
        required: true
        schema:
          type: string
      responses:
        200:
          description: A story object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyStory'
  /companies/{id}/similar:
    get:
      tags:
      - Companies
      summary: Retrieve similar companies
      operationId: get_similar_companies
      description: The similar companies endpoint returns up to 20 of the most similar companies ordered related to the specified company.
      parameters:
      - in: path
        name: id
        description: The ID of the company to retrieve similar companies for
        required: true
        schema:
          type: string
      responses:
        200:
          description: A similar company object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimilarCompany'
  /companies/{id}/people:
    get:
      tags:
      - Companies
      summary: Retrieve company employees
      operationId: get_company_personnel
      description: This endpoint allows you to retrieve key personnel for a specific company in our database.
      parameters:
      - in: path
        name: id
        description: The ID of the company to retrieve personnel for
        required: true
        schema:
          type: string
      responses:
        200:
          description: A company personnel object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PeopleItem'
components:
  schemas:
    ItunesApps:
      type: object
      properties:
        developer_url:
          type: string
          format: url
          example: http:\/\/www.glide.me\/
        itunes_id:
          type: integer
          example: 588199307
        itunes_url:
          type: string
          format: url
          example: https:\/\/itunes.apple.com\/us\/app\/glide­video­texting\/id588199307?mt=8&uo=2
        app_name:
          type: string
          example: Glide  Video Texting
    ItunesUSAWeeklyDownloads:
      type: object
      properties:
        recorded_at:
          type: string
          example: 2014-08-09 00:00:00 UTC
        score:
          type: string
          example: 49745
    AlexaRank:
      type: object
      properties:
        recorded_at:
          type: string
          example: 2014-08-09 00:00:00 UTC
        score:
          type: string
          example: 126653
    EmployeeCount:
      type: object
      properties:
        recorded_at:
          type: string
          example: 2014-08-09 00:00:00 UTC
        score:
          type: string
          example: 16
    FacebookTalkingCount:
      type: object
      properties:
        recorded_at:
          type: string
          example: 2014-08-09 00:00:00 UTC
        score:
          type: string
          example: 3894
    GrowthSource:
      type: object
      properties:
        recorded_at:
          type: string
          example: 2014-08-09 00:00:00 UTC
        score:
          type: string
          example: 210
    companies:
      type: object
      required:
      - id
      - company_name
      - url
      - domain
      properties:
        id:
          type: string
          format: uuid
          example: 10808576
        company_name:
          type: string
          example: Blue Smoke LLC
        domain:
          type: string
          example: bluesmokellc.net
        url:
          type: string
          example: https://api.mattermark.com/companies/10808576
    Acquired_By:
      type: object
      required:
      - event_id
      - closed_date
      - company_id
      - company_name
      - company_domain
      properties:
        event_id:
          type: integer
          format: int64
          example: 15
        closed_date:
          type: string
          example: '2012-12-20'
        company_id:
          type: integer
          format: int64
          example: 1255
        company_name:
          type: string
          example: Oracle Corporation
        company_domain:
          type: string
          format: url
          example: oracle.com
    InboundLinks:
      type: object
      properties:
        recorded_at:
          type: string
          example: 2014-08-09 00:00:00 UTC
        score:
          type: string
          example: 1025
    CompanyItem:
      type: object
      required:
      - id
      - name
      properties:
        name:
          type: string
          example: Glide
        id:
          type: integer
          format: int64
          example: 10533813
        description:
          type: string
          example: Founded in May 2012, Glide is the world's only instant video messaging app.
        website:
          type: string
          example: glide.com
        mattermark_score:
          type: integer
          format: int64
          example: 241
        employees:
          type: integer
          format: int64
          example: 71
        employees_month_ago:
          type: integer
          format: int64
          example: 68
        employees_6_months_ago:
          type: integer
          format: int64
          example: 32
        website_uniques:
          type: integer
          format: int64
          example: 13568
        mobile_downloads:
          type: integer
          format: int64
          example: 5281
        stage:
          type: string
          example: b
        total_funding:
          type: integer
          format: int64
          example: 20000000
        last_funding_amount:
          type: integer
          format: int64
          example: 20000000
        last_funding_date:
          type: string
          format: date
          example: '2013-03-21'
        location:
          type: string
          example: Seattle
        city:
          type: string
          example: Seattle
        state:
          type: string
          example: WA
        zip:
          type: string
          example: 98155
        country:
          type: string
          example: USA
        twitter_handle:
          type: string
          example: GlideApp
        facebook_handle:
          type: string
          example: glideme
        linkedin_id:
          type: integer
          format: int64
          example: 3020582
        added_date:
          type: string
          format: date
          example: '2013-04-04 15:57:52'
        revenue_range:
          type: string
          example: $5M - $10M
        itunes_apps:
          type: array
          items:
            $ref: '#/components/schemas/ItunesApps'
        google_play_apps:
          type: array
          items:
            $ref: '#/components/schemas/GooglePlayApps'
        funding:
          type: array
          items:
            $ref: '#/components/schemas/Funding'
        acquired_by:
          type: array
          items:
            $ref: '#/components/schemas/Acquired_By'
        acquired_companies:
          type: array
          items:
            $ref: '#/components/schemas/Acquired_Companies'
        est_founding_date:
          type: string
          example: '1999-01-01'
        business_models:
          type: string
          example:
          - B2B
        industries:
          type: string
          example:
          - data storage
          - enterprise software
          - hardware
          - information security
          - network / hosting / infrastructure
          - security
          - storage
        stories:
          type: array
          items:
            $ref: '#/components/schemas/Stories'
        growth_scores:
          type: array
          items:
            $ref: '#/components/schemas/GrowthSource'
        mindshare_scores:
          type: array
          items:
            $ref: '#/components/schemas/MindshareScores'
        employee_count:
          type: array
          items:
            $ref: '#/components/schemas/EmployeeCount'
        alexa_rank:
          type: array
          items:
            $ref: '#/components/schemas/AlexaRank'
        facebook_talking_count:
          type: array
          items:
            $ref: '#/components/schemas/FacebookTalkingCount'
        facebook_like_count:
          type: array
          items:
            $ref: '#/components/schemas/FacebookLikeCount'
        twitter_follower_count:
          type: array
          items:
            $ref: '#/components/schemas/TwitterFollowerCount'
        twitter_mentions:
          type: string
          example: []
        linkedin_follower_count:
          type: array
          items:
            $ref: '#/components/schemas/LinkedinFollowerCount'
        itunes_usa_weekly_downloads:
          type: array
          items:
            $ref: '#/components/schemas/ItunesUSAWeeklyDownloads'
        inbound_links:
          type: array
          items:
            $ref: '#/components/schemas/InboundLinks'
        est_monthly_uniques:
          type: array
          items:
            $ref: '#/components/schemas/EstMonthlyUniques'
    Acquired_Companies:
      type: object
      required:
      - event_id
      - closed_date
      - company_id
      - company_name
      - company_domain
      properties:
        event_id:
          type: integer
          format: int64
          example: 10957519
        closed_date:
          type: string
          example: '2017-04-20'
        company_id:
          type: integer
          format: int64
          example: 61444
        company_name:
          type: string
          example: Moat
        company_domain:
          type: string
          example: moat.com
    SimilarCompany:
      type: object
      required:
      - company_name
      - description
      - description_plain_text
      - domain
      - id
      - probability
      - stage
      - total_funding
      properties:
        company_name:
          type: string
          example: Flipkart
        description:
          type: string
          example: Flipkart is an online shopping destination for electronics, books, music and movies.
        description_plain_text:
          type: string
          example: Flipkart is an online shopping destination for electronics, books, music and movies.
        domain:
          type: string
          example: flipkart.com
        id:
          type: integer
          format: int64
          example: 39279
        probability:
          type: string
          example: 1.0
        stage:
          type: string
          example: h
        total_funding:
          type: integer
          format: int64
          example: 3051140000
    FacebookLikeCount:
      type: object
      properties:
        recorded_at:
          type: string
          example: 2014-08-09 00:00:00 UTC
        score:
          type: string
          example: 168940
    EstMonthlyUniques:
      type: object
      properties:
        recorded_at:
          type: string
          example: 2015-10-17 04:31:27 +0000
        score:
          type: string
          example: 21543
    LinkedinFollowerCount:
      type: object
      properties:
        recorded_at:
          type: string
          example: 2014-08-09 00:00:00 UTC
        score:
          type: string
          example: 46
    GooglePlayApps:
      type: object
      required:
      - id
      - app_name
      - package_id
      - company_id
      - company_name
      - company_domain
      - play_url
      properties:
        id:
          type: integer
          example: 319510
        app_name:
          type: string
          format: Glide - Video Chat Messenger
        package_id:
          type: string
          example: com.glidetalk.glideapp
        company_id:
          type: integer
          format: int64
          example: 113022
        company_name:
          type: string
          example: Glide
        company_domain:
          type: string
          example: glide.me
        play_url:
          type: string
          format: url
          example: http://play.google.com/store/apps/details?id=com.glidetalk.glideapp
    Stories:
      type: object
      properties:
        title:
          type: string
          example: Israeli Glide introduces fast capture video and chat for Apple Watch
        url:
          type: string
          example: http://www.geektime.com/2016/11/13/israeli-glide-introduces-fast-capture-video-and-chat-for-apple-watch/
        date:
          type: string
          example: Nov 13 2016
        source:
          type: string
          example: Geek Time
    MindshareScores:
      type: object
      properties:
        recorded_at:
          type: string
          example: 2014-08-09 00:00:00 UTC
        score:
          type: string
          example: 210
    Funding:
      type: object
      required:
      - amount
      - currency
      - series
      - funding_date
      - news_url
      - source
      - investor_ids
      - investors
      properties:
        amount:
          type: integer
          example: 0
        currency:
          type: string
          example: USD
        series:
          type: string
          example: speed
        funding_date:
          type: string
          format: date
          example: '2013-03-21'
        news_url:
          type: string
          format: url
          example: http:\/\/www.finsmes.com\/2013\/03\/glide­raises­seven­figure­sum.html
        source:
          type: string
          example: derived
        investor_ids:
          type: array
          items:
            type: string
          example:
          - 1234
        investors:
          type: string
          example: Orey Gilliam,Philippe Schwartz
    CompanyStory:
      required:
      - id
      - title
      - url
      - published_at
      - source_title
      properties:
        id:
          type: integer
          example: 1426837
        title:
          type: string
          example: 'E-commerce roundup: Amazon India, Bata, FoodPanda & Snapdeal'
        url:
          type: string
          format: url
          example: http://feedproxy.google.com/~r/medianama/~3/pScV966Eya8/
        published_at:
          type: string
          example: 2014-12-18 01:16:25 UTC
        source_title:
          type: string
          example: MediaNama
    PeopleItem:
      type: object
      required:
      - name
      - title
      - path
      properties:
        name:
          type: string
          example: Ari Roisman
        title:
          type: string
          example: Co-Founder / CEO
        path:
          type: string
          example: https://il.linkedin.com/in/aroisman
    TwitterFollowerCount:
      type: object
      properties:
        recorded_at:
          type: string
          example: 2014-08-09 00:00:00 UTC
        score:
          type: string
          example: 10388
  parameters:
    pageParam:
      in: query
      name: page
      required: false
      description: The page of items from the result set to return.
      schema:
        type: integer
        minimum: 0
    limitParam:
      in: query
      name: per_page
      required: false
      description: The numbers of items to return per page.
      schema:
        type: integer
        default: 10
        maximum: 50
        minimum: 1
  securitySchemes:
    APIKeyHeaderParam:
      type: apiKey
      in: header
      name: Authorization