DiscoverOrg API · Chapter 4. Caching Store API responses in your application or on your site if...

DiscoverOrg APIAn API provided to partners of DiscoverOrg in order to interact with the

DiscoverOrg platform.

Table of Contents1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1. Version information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2. URI scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2. Authentication on all endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

3. Rate Limiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3.1. API Rate Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3.2. HTTP Headers and Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

4. Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

5. Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

5.1. Retrieve a company by id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

5.2. Company Department Org Chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

5.3. Retrieve a person by id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

5.4. QuickSearch for a person . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

5.5. Search for companies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

5.6. Search for persons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

5.7. Get select option values by type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

6. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6.1. CompanyCriteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6.2. CompanyDepartmentResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6.3. CompanyNoteResource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

6.4. CompanyResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

6.5. CompanyTechnologyCategoryResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

6.6. DOrgSearchRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

6.7. LocationResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

6.8. NumericalRangeCriteria«long» . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

6.9. OrgChartNodeResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

6.10. OrgChartResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6.11. Page«CompanyResource» . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6.12. Page«PersonResource» . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6.13. PersonCriteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

6.14. PersonResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

6.15. SelectOptionResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6.16. TechnologyResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 1. OverviewThis document describes the REST API and resources provided by DiscoverOrg. The REST APIs arefor 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 RESTAPI, your application will make an HTTP request and parse the response. The response format isJSON. 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 toaccess the API.

1.1. Version informationVersion: 1.0

1.2. URI schemeBasePath: https://papi.discoverydb.com/papi/

1

https://papi.discoverydb.com/papi/

Chapter 2. Authentication on all endpointsWe require applications to authenticate all of their requests. This visibility allows us to preventabusive behavior, and it also help us to further understand how categories of applications are usingthe API. We apply this understanding to better meet the needs of partners as we continue to evolvethe platform.

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

POST the following to https://papi.discoverydb.com/papi/login

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

Authentication will be supported through the use of user access tokens that will be passed in theauthorization 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"

2

https://papi.discoverydb.com/papi/login

Chapter 3. Rate LimitingThe 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, peraccess token in your control. Each endpoint allows for a rate limit of 300 requests per 15 minutewindow.

3.2. HTTP Headers and Response CodesEnsure that you inspect the HTTP headers, as they provide pertinent data on where yourapplication 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 limitfor 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 APIwill now return an HTTP 429 “Too Many Requests” response code.

3

Chapter 4. CachingStore API responses in your application or on your site if you expect a lot of use. For example, don’ttry 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 loadthe cached version of the results.

4

Chapter 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


5.1.6. Tags

• Companies

5.2. Company Department Org Chart

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

5

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



PathParameter departmentId departmentId true integer (int32)

5.2.3. Responses


200 OK OrgChartResource


5.2.4. Consumes


5.2.5. Produces


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



6

5.3.3. Responses


200 OK PersonResource


5.3.4. Consumes


5.3.5. Produces


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 arelooked at for QuickSearch is the Persons Full Name

5.4.2. Parameters


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 stringarray

fullName

7

5.4.3. Responses


200 OK Page«PersonResource»


5.4.4. Consumes


5.4.5. Produces


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


BodyParameter searchRequest searchRequest true DOrgSearchRequest

QueryParameter


QueryParameter


QueryParameter


ASC

QueryParameter


name

5.5.3. Responses

8


200 OK Page«CompanyResource»

5.5.4. Consumes


5.5.5. Produces


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


BodyParameter searchRequest searchRequest true DOrgSearchRequest

QueryParameter


QueryParameter


QueryParameter


ASC

QueryParameter


fullName

5.6.3. Responses


200 OK Page«PersonResource»

9

5.6.4. Consumes


5.6.5. Produces


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

10


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

11


200 OK SelectOptionResource array


5.7.4. Consumes


5.7.5. Produces


5.7.6. Tags

• Search Criteria

12

Chapter 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

13


budget false integer (int64)

departmentLabel false string

departmentName false string

numEmployees false integer (int32)

6.3. CompanyNoteResource


id false integer (int32)

note false string

noteTimestamp false string (date-time)

6.4. CompanyResource


3YearEmployeesGrowthPercentage

false integer (int32)

3YearSalesGrowthPercentage


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


industry false string

14


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


categoryId false integer (int32)

categoryName false string

technologies false TechnologyResource array

6.6. DOrgSearchRequest


companyCriteria false CompanyCriteria

personCriteria false PersonCriteria

15

6.7. LocationResource


city false string

countryName false string


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»


empty false boolean

maxValue false integer (int64)

minValue false integer (int64)

6.9. OrgChartNodeResource


children false OrgChartNodeResource array

email false string


mobilePhoneNumber

false string

officePhoneNumber

false string

personId false integer (int64)

16


title false string

6.10. OrgChartResource


departmentId false integer (int32)

departmentName false string

nodes false OrgChartNodeResource array

6.11. Page«CompanyResource»


content false CompanyResourcearray

first false boolean

last false boolean

number false integer (int32)

numberOfElements


size false integer (int32)

sort false [Sort]

totalElements false integer (int64)

totalPages false integer (int32)

6.12. Page«PersonResource»


content false PersonResourcearray

first false boolean

last false boolean

number false integer (int32)

numberOfElements


17


size false integer (int32)

sort false [Sort]

totalElements false integer (int64)

totalPages false integer (int32)

6.13. PersonCriteria


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


company false CompanyResource

departments false SelectOptionResource array

18


email false string

firstName false string



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


description false string

displayName false string


6.16. TechnologyResource



technologyName false string

vendor false string

19

DiscoverOrg API · Chapter 4. Caching Store API responses in your application or on your site if...

Documents

Transcript of DiscoverOrg API · Chapter 4. Caching Store API responses in your application or on your site if...