1. Overview

This document describes the REST API and resources provided by DiscoverOrg. The REST APIs are for developers who want to integrate DiscoverOrg’s platform into their application.

DiscoverOrg’s REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. The response format is JSON. Your methods will be the standard HTTP methods like GET, PUT, POST and DELETE.

Because the REST API is based on open standards, you can use any web development language to access the API.

1.1. Version information

Version: 1.0

1.2. URI scheme

2. Authentication on all endpoints

We require applications to authenticate all of their requests. This visibility allows us to prevent abusive behavior, and it also help us to further understand how categories of applications are using the API. We apply this understanding to better meet the needs of partners as we continue to evolve the platform.

To authenticate and retrieve the authorization token for consecutive requests you will post a JSON string containing the DOrg username and password, as well as your DOrg API Partner Key, to the /login URI.

{ "username": "<DOrg username>", "password": "<DOrg password>", "partnerKey": "<DOrg API partner key>" }

Authentication will be supported through the use of user access tokens that will be passed in the authorization header of each request.

X-AUTH-TOKEN: <token value>

Some example cURL commands:

curl -X GET -H "X-AUTH-TOKEN: <token value>" -H "Cache-Control: no-cache" "https://phoenix.discoverydb.com/papi/v1/quicksearch/persons?searchString=Robert Gabaree"

3. Rate Limiting

The DiscoverOrg API has rate limiting applied to all requests.

3.1. API Rate Limits

3.1.1. Per Partner

Rate limiting of the API considered on a per-partner basis — or more accurately described, per access token in your control. Each endpoint allows for a rate limit of 300 requests per 15 minute window.

3.2. HTTP Headers and Response Codes

Ensure that you inspect the HTTP headers, as they provide pertinent data on where your application is at for a given rate limit on the method that you just utilized.

Note that the HTTP headers are contextual. When using app-only auth, they indicate the rate limit for the application context. When using user-based auth, they indicate the rate limit for that user-application context.

  • X-Rate-Limit-Limit: the rate limit ceiling for that given request

  • X-Rate-Limit-Remaining: the number of requests left for the 15 minute window

  • X-Rate-Limit-Reset: the remaining window before the rate limit resets in UTC epoch seconds

When an application exceeds the rate limit for a given API endpoint, the DiscoverOrg Partner API will now return an HTTP 429 “Too Many Requests” response code.

4. Caching

Store API responses in your application or on your site if you expect a lot of use. For example, don’t try to call the DiscoverOrg Partner API on every page load of your website landing page. Instead, call the API infrequently and load the response into a local cache. When users hit your website load the cached version of the results.

5. Paths

5.1. Retrieve a company by id

GET /v1/companies/{id}

5.1.1. Description

Retrieves a company by the provided id value.

5.1.2. Parameters

Type Name Description Required Schema Default

PathParameter

id

id

true

integer (int32)

QueryParameter

includeTechnologies

includeTechnologies

false

boolean

false

5.1.3. Responses

HTTP Code Description Schema

200

OK

CompanyResource

500

500 message

[Error]

5.1.4. Consumes

  • application/json

5.1.5. Produces

  • application/json

5.1.6. Tags

  • Companies

5.2. Company Department Org Chart

GET /v1/companies/{id}/orgchart/{departmentId}

5.2.1. Description

Retrieve Org Chart related to a particular Company (specified by its id) and particular Department (specified by its id).

5.2.2. Parameters

Type Name Description Required Schema Default

PathParameter

id

id

true

integer (int32)

PathParameter

departmentId

departmentId

true

integer (int32)

5.2.3. Responses

HTTP Code Description Schema

200

OK

OrgChartResource

500

500 message

[Error]

5.2.4. Consumes

  • application/json

5.2.5. Produces

  • application/json

5.2.6. Tags

  • Companies

5.3. Retrieve a person by id

GET /v1/persons/{id}

5.3.1. Description

Retrieves a person by the provided id value.

5.3.2. Parameters

Type Name Description Required Schema Default

PathParameter

id

id

true

integer (int32)

5.3.3. Responses

HTTP Code Description Schema

200

OK

PersonResource

500

500 message

[Error]

5.3.4. Consumes

  • application/json

5.3.5. Produces

  • application/json

5.3.6. Tags

  • Persons

5.4. QuickSearch for a person

GET /v1/quicksearch/persons

5.4.1. Description

Retrieve a list of persons based on string value sent to QuickSearch. The following properties are looked at for QuickSearch is the Persons Full Name

5.4.2. Parameters

Type Name Description Required Schema Default

QueryParameter

searchString

searchString

true

string

QueryParameter

pageNumber

pageNumber

false

integer (int32)

0

QueryParameter

pageSize

pageSize

false

integer (int32)

50

QueryParameter

direction

direction

false

enum (ASC, DESC)

ASC

QueryParameter

properties

properties

false

multi string array

fullName

5.4.3. Responses

HTTP Code Description Schema

200

OK

Page«PersonResource»

500

500 message

[Error]

5.4.4. Consumes

  • application/json

5.4.5. Produces

  • application/json

5.4.6. Tags

  • Quick Search

5.5. Search for companies

POST /v1/search/companies

5.5.1. Description

Retrieve a list of companies based on the values in a SearchRequest

5.5.2. Parameters

Type Name Description Required Schema Default

BodyParameter

searchRequest

searchRequest

true

DOrgSearchRequest

QueryParameter

pageNumber

pageNumber

false

integer (int32)

0

QueryParameter

pageSize

pageSize

false

integer (int32)

50

QueryParameter

direction

direction

false

enum (ASC, DESC)

ASC

QueryParameter

properties

properties

false

multi string array

name

5.5.3. Responses

HTTP Code Description Schema

200

OK

Page«CompanyResource»

5.5.4. Consumes

  • application/json

5.5.5. Produces

  • application/json

5.5.6. Tags

  • Search

5.6. Search for persons

POST /v1/search/persons

5.6.1. Description

Retrieve a list of persons based on the values in a SearchRequest

5.6.2. Parameters

Type Name Description Required Schema Default

BodyParameter

searchRequest

searchRequest

true

DOrgSearchRequest

QueryParameter

pageNumber

pageNumber

false

integer (int32)

0

QueryParameter

pageSize

pageSize

false

integer (int32)

50

QueryParameter

direction

direction

false

enum (ASC, DESC)

ASC

QueryParameter

properties

properties

false

multi string array

fullName

5.6.3. Responses

HTTP Code Description Schema

200

OK

Page«PersonResource»

5.6.4. Consumes

  • application/json

5.6.5. Produces

  • application/json

5.6.6. Tags

  • Search

5.7. Get select option values by type

GET /v1/searchcriteria/selectoptions/{type}

5.7.1. Description

Get the available select option values for the given type

5.7.2. Parameters

Type Name Description Required Schema Default

PathParameter

type

type

true

enum (EXTERNAL_ROLE, INTERNAL_ROLE, PERMISSION, DEPARTMENT, JOB_FUNCTION, SENIORITY_LEVEL, SENIORITY_LEVEL_GROUP, INDUSTRY, OWNERSHIP_TYPE, BUSINESS_MODEL_TYPE, FIXIT_REQUEST_CATEGORY, INTEL_CATEGORY, INTEL_REPORT_TYPE, SCOOP_TYPE, SCOOP_TOPIC, LEGACY_SCOOP_TOPIC, DATA_SOURCE, SUBSCRIPTION_TYPE, SCHEDULE_TYPE, TECHNOLOGY_PRODUCT, TECHNOLOGY_CATEGORY, OPPALERT_CATEGORY, MARKETING_REGION, USAGE_REPORT_FREQUENCY_TYPE, OPEN_BANNER_OPTION)

5.7.3. Responses

HTTP Code Description Schema

200

OK

SelectOptionResource array

500

500 message

[Error]

5.7.4. Consumes

  • application/json

5.7.5. Produces

  • application/json

5.7.6. Tags

  • Search Criteria

6. Definitions

6.1. CompanyCriteria

Name Description Required Schema Default

duns

false

string array

emailDomains

false

string array

employeeGrowthRange

false

NumericalRangeCriteria«long»

fortuneRankRange

false

NumericalRangeCriteria«long»

ids

false

integer (int32) array

industryIds

false

integer (int32) array

otherDomains

false

string array

ownershipTypeIds

false

integer (int32) array

parentDuns

false

string array

queryString

false

string

queryStringApplication

false

enum (NAME, FULL_NAME, WEBSITE_URL, DESCRIPTION, OTHER_NAMES, NOTES, EMAIL_DOMAIN, TECHNOLOGY) array

revenueRange

false

NumericalRangeCriteria«long»

salesGrowthRange

false

NumericalRangeCriteria«long»

totalEmployeesRange

false

NumericalRangeCriteria«long»

websiteUrls

false

string array

6.2. CompanyDepartmentResource

Name Description Required Schema Default

budget

false

integer (int64)

departmentLabel

false

string

departmentName

false

string

numEmployees

false

integer (int32)

6.3. CompanyNoteResource

Name Description Required Schema Default

id

false

integer (int32)

note

false

string

noteTimestamp

false

string (date-time)

6.4. CompanyResource

Name Description Required Schema Default

3YearEmployeesGrowthPercentage

false

integer (int32)

3YearSalesGrowthPercentage

false

integer (int32)

companyDepartments

false

CompanyDepartmentResource array

companyTechnologies

false

CompanyTechnologyCategoryResource array

description

false

string

dorgCompanyUrl

false

string

duns

false

string

emailDomain

false

string

fiscalYearEnd

false

string

fortuneRank

false

integer (int32)

fullName

false

string

global200Rank

false

integer (int32)

hospitalBeds

false

string

id

false

integer (int32)

industry

false

string

linkedinUrl

false

string

location

false

LocationResource

logoFilename

false

string

mainPhoneNumber

false

string

myNotes

false

CompanyNoteResource array

naics

false

object array

name

false

string

notes

false

string

numEmployees

false

integer (int32)

numberOfLocations

false

string

otherNames

false

string array

ownershipType

false

string

parentDuns

false

string

revenue

false

integer (int64)

sic

false

object array

websiteUrl

false

string

6.5. CompanyTechnologyCategoryResource

Name Description Required Schema Default

categoryId

false

integer (int32)

categoryName

false

string

technologies

false

TechnologyResource array

6.6. DOrgSearchRequest

Name Description Required Schema Default

companyCriteria

false

CompanyCriteria

personCriteria

false

PersonCriteria

6.7. LocationResource

Name Description Required Schema Default

city

false

string

countryName

false

string

id

false

integer (int32)

isoCountryCode

false

string

latitude

false

number (double)

longitude

false

number (double)

metroArea

false

string

metroSystem

false

string

postalCode

false

string

stateProvinceRegion

false

string

streetAddress1

false

string

streetAddress2

false

string

6.8. NumericalRangeCriteria«long»

Name Description Required Schema Default

empty

false

boolean

maxValue

false

integer (int64)

minValue

false

integer (int64)

6.9. OrgChartNodeResource

Name Description Required Schema Default

children

false

OrgChartNodeResource array

email

false

string

fullName

false

string

mobilePhoneNumber

false

string

officePhoneNumber

false

string

personId

false

integer (int64)

title

false

string

6.10. OrgChartResource

Name Description Required Schema Default

departmentId

false

integer (int32)

departmentName

false

string

nodes

false

OrgChartNodeResource array

6.11. Page«CompanyResource»

Name Description Required Schema Default

content

false

CompanyResource array

first

false

boolean

last

false

boolean

number

false

integer (int32)

numberOfElements

false

integer (int32)

size

false

integer (int32)

sort

false

[Sort]

totalElements

false

integer (int64)

totalPages

false

integer (int32)

6.12. Page«PersonResource»

Name Description Required Schema Default

content

false

PersonResource array

first

false

boolean

last

false

boolean

number

false

integer (int32)

numberOfElements

false

integer (int32)

size

false

integer (int32)

sort

false

[Sort]

totalElements

false

integer (int64)

totalPages

false

integer (int32)

6.13. PersonCriteria

Name Description Required Schema Default

departmentIds

false

integer (int32) array

emails

false

string array

firstNames

false

string array

hasEmail

false

boolean

hasOfficePhone

false

boolean

ids

false

integer (int32) array

jobFunctionIds

false

integer (int32) array

queryString

false

string

queryStringApplication

false

enum (FULL_NAME, SUR_NAME, TITLE, NOTES, EMAIL, TECHNOLOGY) array

reportsToCLevel

false

boolean

seniorityIds

false

integer (int32) array

surNames

false

string array

6.14. PersonResource

Name Description Required Schema Default

company

false

CompanyResource

departments

false

SelectOptionResource array

email

false

string

firstName

false

string

fullName

false

string

id

false

integer (int64)

jobFunctions

false

SelectOptionResource array

linkedInUrl

false

string

location

false

LocationResource

middleName

false

string

mobileTelNumber

false

string

notes

false

string

officeTelNumber

false

string

portraitFileName

false

string

seniorityLevel

false

SelectOptionResource

surName

false

string

title

false

string

twitterHandle

false

string

6.15. SelectOptionResource

Name Description Required Schema Default

description

false

string

displayName

false

string

id

false

integer (int32)

6.16. TechnologyResource

Name Description Required Schema Default

id

false

integer (int32)

technologyName

false

string

vendor

false

string