OAuth2 Token Authentication

The ZoomInfo Partner API consists of the following web services with associated URLs using OAuth2 token authentication to access ZoomInfo data.

API
URL
Person Search
http://partnerapi.zoominfo.com/partnerapi/v4/person/search?
Person Detail
http://partnerapi.zoominfo.com/partnerapi/v4/person/detail?
Person Match
http://partnerapi.zoominfo.com/partnerapi/v4/person/match?
Enhanced Person Match
http://partnerapi.zoominfo.com/partnerapi/v4/enhanced/person/match?
Company Search
http://partnerapi.zoominfo.com/partnerapi/v4/company/search?
Company Detail
http://partnerapi.zoominfo.com/partnerapi/v4/company/detail?
Company Match
http://partnerapi.zoominfo.com/partnerapi/v4/company/match?              
Usage Query
http://partnerapi.zoominfo.com/partnerapi/v4/usage/query?


1. The partner must first be provisioned properly.

2. The partner needs to create a JWT using their partner code (and optionally their contact email address), and the libraries we have approved:


Steps to create a JSON Web Token (JWT)


Creating a JWT using Java

This example uses jsontoken-1.1.jar ( https://code.google.com/p/jsontoken/) to create a JWT token using Java. Partners are free to choose any JWT library to create their JWT tokens. But, they must strictly follow the JSON schema we publish for the Partner API application. See the Partner API JWT schema below. For more details about JWT tokens, see https://scotch.io/tutorials/the-anatomy-of-a-json-web-token. If you choose to use a different library to create your JWT tokens, then please refer to the documentation for that JWT library, which will show you how to create your JWT tokens and how to add the required fields.

To start, you will need your PartnerCode(PC, password, and, if you desire, the email assigned to your partnercode with ZoomInfo.

1. Create the signer. This will encrypt the entire payload using the secret key. For Partner API partners, the secret key will be their partner password. Only Zoominfo and the partner should know this password and it should be protected to prevent security issues. We are using the HmacSHA256Signer class. For example:

signer = new HmacSHA256Signer(ISSUER, keyID, secret value in bytes); //The ISSUER is "zoominfo", the keyID is null, and the "secret value in bytes" is the partner password.

2. The JWT token should contain issuedAt and expiration time. The issuedAt and the expiration time will be in seconds. We allow an expiration time up to 1 hour. For ex.

token.setIssuedAt(new Instant(issuedTimeInMillis)); //Current time in milliseconds
token.setExpiration(new Instant(issuedTimeInMillis + 3600000)); // current time + 1 hour is the expiration time.

Note: Refer to your JWT library for setting time. The JSON Token-1.1.jar sets the time in seconds. In this example, I am setting the value in milliseconds, because the "Instant" object expects the value to be in milliseconds. Internally, the "setIssuedAt" and the "setExpiration" calls convert the value to seconds. So when the ZoomInfo OAuth web server receives this value, it will treat the issued at and the expiration time as if they are in seconds. There is no way for the ZoomInfo OAuth web server to know whether the incoming 'issued at' and 'expiration' values sent in from the partner are set in seconds or milliseconds. So you MUST set the expiration time and the issued time in seconds.

3. Create the "jti" attribute and set the value to a random UUID. The "jti" attribute is used to determine whether the JWT is being used again in a second request. ZoomInfo will use the "jti" attribute to prevent all JWT tokens from being used more than once. For example:

token.setParam("jti", UUID.randomUUID().toString());

4. Create the JSON object for the payload. Please refer to the JWT schema's ziPayLoad section below for the parameters which should be set. In the example below, the addProperty() calls set the payload's attributes and values. Example:

JsonObject infoObject = new JsonObject();
infoObject.addProperty("ziPartnerCode", "Your Partner Code");
infoObject.addProperty("ziPartnerContactEmail", "Your contact email address"); //Optional!
JsonObject payload = token.getPayloadAsJsonObject();
payload.add("ziPayLoad", infoObject);

5. Finally sign the token. Example:

token.serializeAndSign();

This will give you a JWT token as a String.

The JWT token is used to get the OAuth Access token. To get the access token you should send the JWT token to the https://partnerapi.zoominfo.com/partnerapi/v2/token endpoint and ZoomInfo will decrypt the token, check the values in the payload, and make sure the token is not expired and not being re-used. See below for more details.

Creating a JWT using C#

This example uses JWT version 1.3.4 ( https://github.com/jwt-dotnet/jwt) to create a JWT token using C#. Partners are free to choose any JWT library to create their JWT tokens. But, they must strictly follow the JSON schema we publish for the Partner API application. See the Partner API JWT schema below. For more details about JWT tokens, see: https://scotch.io/tutorials/the-anatomy-of-a-json-web-token. If you choose to use a different library to create your JWT tokens, then please refer the documentation for that JWT library which will show you how to create your JWT tokens and add the required fields. To start, you will need your PartnerCode(PC), password, and, if you desire, the email assigned to your partnercode with ZoomInfo.

1. Declare a Dictionary with Zoom Specific fields:

var ziPayLoad = new Dictionary()
 {
 {"ziPartnerCode",pc }
 };

 //Add email, if set, to ziPayLoad
 if (email.Length > 0)
 {
 ziPayLoad.Add("ziPartnerContactEmail", email);
 }

2. Set the creation date and the expiration date. We allow an expiration time up to 1 hour. You may create your JWT to be valid for shorter than that if you desire.

var utc0 = new DateTime(1970, 1, 1, 0, 0, 0, 0, DateTimeKind.Utc);
 var issueTime = DateTime.UtcNow;

 //Set creation Time for token
 var iat = (int)issueTime.Subtract(utc0).TotalSeconds;
 //Set Expire time for token
 var exp = (int)issueTime.AddMinutes(55).Subtract(utc0).TotalSeconds;

3. Create new Dictionary. This will contain all the required payload information.

var payload = new Dictionary()
 {
 {"iss","zoominfo" }, //Issuer
 {"iat", iat}, //Issue time
 {"exp",exp},// Expire time
 {"jti",Guid.NewGuid().ToString() }, //JTI - random ID
 { "ziPayLoad", ziPayLoad } //ziPayLoad - Dict created previously
 };

4. Finally, Encode the data and generate the JWT:

string token = JsonWebToken.Encode(payload, your password, JWT.JwtHashAlgorithm.HS256);

Creating a JWT using Python

Required Libraries: 

1. This example uses JWT library from https://github.com/jpadilla/pyjwt. There are instructions in the link to     create a JWT token using Python.

 2. You also need datetime and uuid libraries. But these are Python native libraries so you do not need to download them.

 Note: Partners are free to choose any JWT library to create their JWT tokens. But, they must strictly follow the JSON schema we publish for the Partner API application. See the Partner API JWT schema below. For more details about JWT tokens, see https://scotch.io/tutorials/the-anatomy-of-a-json-web-token. If you choose to use a different library to create your JWT tokens, then please refer to the documentation for that JWT library, which will show you how to create your JWT tokens and how to add the required fields.

To start, you will need your PartnerCode(PC, password, and, if you desire, the email assigned to your partnercode with ZoomInfo.

1. Import libraries and declare a Dictionary with Zoom Specific fields: 

import jwt
from datetime import datetime, date, time, timedelta
import uuid

pc ='type your partner code here'
 zipayload = {
'ziPartnerCode':pc
 }

2. Set the creation date and the expiration date. We allow an expiration time up to 1 hour. You may create your JWT to   be valid for shorter than that if you desire.

utc0 = datetime(1970,1,1)
 issueTime = datetime.utcnow()
 iat = issueTime - utc0
 iat = int(iat.total_seconds())
 exp = issueTime - utc0
 exp = exp + timedelta(minutes=60)
 exp = int(exp.total_seconds())

3. Create new Dictionary. This will contain all the required payload information

payload = {
 'iss':'zoominfo',\
 'iat': iat,\
 'jti': str(uuid.uuid4()),\
 'ziPayLoad':zipayload,\
 'exp': exp
 }

4. Finally, Encode the data and generate the JWT:

password = 'type your password here'
encoded = jwt.encode(payload, password, algorithm='HS256')

** encoded will have the value of JWT Token.

Creating a JWT using Node.js

This example uses JWT library 'jsonwebtoken'.Partners are free to choose any JWT library to create their JWT tokens. But, they must strictly follow the JSON schema we publish for the Partner API application. See the Partner API JWT schema below. For more details about JWT tokens, see https://scotch.io/tutorials/the-anatomy-of-a-json-web-token. If you choose to use a different library to create your JWT tokens, then please refer to the documentation for that JWT library, which will show you how to create your JWT tokens and how to add the required fields.

To start, you will need your PartnerCode(PC, password, and, if you desire, the email assigned to your partnercode with ZoomInfo.

1. Import libraries and Declare a Dictionary with Zoom Specific fields:

var jwt = require('jsonwebtoken');

ziPayload = {
 ziPartnerCode : pc
 };

2. Set the creation date and the expiration date. We allow an expiration time up to 1 hour. You may create your JWT to be valid for   shorter than that if you desire.

var ISSUER = "zoominfo";
 var pc = "enter your pc code here";

 var d = new Date();
 var n = d.getTime();
 iat = Math.round(n/1000);
 exp = Math.round(n/1000) + 60 * 60;

3. Create new Dictionary. This will contain all the required payload information.

payload= {
 iss :ISSUER,
 iat : iat,
 exp : exp ,
 jti : guid(),
 ziPayload :payload
 };

4. Finally, Encode the data and generate the JWT:

var password = "enter your password here";
var token = jwt.sign(payload, password);

** token will have the value of JWT Token.

Partner API JWT Schema:

You can access different types ofJWT libraries here: http://jwt.io/im

{
 "$schema": "http://json-schema.org/draft-04/schema#",
 "type": "object",
 "properties": {
 "iss": { //JWT standard. Issuer- Whoever is issuing this token. 
 "type": "string",
 "maximum":1
 },
 "iat": { //JWT standard. Issued at. Contains the value of the time the token was created in seconds.
 "type": "long"
 "maximum":1
 },
 "exp": { //JWT standard. Token life time in seconds. The value will be current time in seconds + 3600. We at Zoominfo can set the maximum life time, to 1hr (minimum expiration time will be 5 minutes) and let the partner know to set this field within the time range of 5minutes – 1 hr.
 "type": "long"
 "maximum":1
 },
 "jti": { //JWT standard. JSON Token ID. This is a UUID. Useful to enforce the number of times the token can be requested. Usually, one time token request.
 "type": "string",
 "minimum":0,
 "maximum":1
 },
 "ziPayLoad": { //This entry will be specific to the Zoom Info Partner API. In the JWT world, it is called private claim.
 "type": "object",
 "maximum":1,
 "properties": {
 "ziPartnerCode": { //The partner code
 "type": "string",
 "minimum":1,
 "maximum":1
 },
 "ziPartnerContactEmail": { //The partner's contact email. If this is set, then it must be one of the contact email that Zoom Info knows about (i.e. the email to which Zoom Info sends daily usage emails).
 "type": "string",
 "minimum":0,
 "maximum":1
 }
 }
 }
 },
 "required": [
 "iss",
 "iat",
 "jti",
 "exp",
 "ziPayLoad"
 ]
}

Request an Access Token based on your JWT

This must be an HTTPS POST request: Method: POST 

Then under Headers, do Custom Header twice for: 

Accept: application/xml 

Content-Type: application/xml

 Body: 

<?xml version="1.0" encoding="utf-8"?>
<TokenPostInput xmlns="http://partnerapi.zoominfo.com/partnerapistatic/xsd/V1/TokenPostInput.xsd">
<pc>PartnerCode</pc>
<ziToken>PARTNER GENERATED JWT GOES HERE</ziToken>
</TokenPostInput>

Example Responses from https://partnerapi.zoominfo.com/partnerapi/v2/token request:

<TokenResponse xmlns="http://partnerapi.zoominfo.com/partnerapistatic/xsd/V1/TokenResponse.xsd">
<token>89e967f5-d637-4cdf-9f72-453dedb65dfc</token>
</TokenResponse>
Error response:
<TokenResponse xmlns="http://partnerapi.zoominfo.com/partnerapistatic/xsd/V1/TokenResponse.xsd">
<tokenError>
<errorCode>9001</errorCode>
<errorMessage>Invalid token request</errorMessage>
</tokenError>
</TokenResponse>

The partner should then call the PartnerAPI (parameter values below are just examples using enhanced person match). The input parameters are all the same as they are for a normal API request, except that the key will be an OAuth access token rather than the normal MD5 encrypted key: https://partnerapi.zoominfo.com/partnerapi/v3/enhanced/person/match? firstName=jon&lastName=smith&emailAddress=jsmith@leonardinsurance.com&pc=PartnerCode&outputType=xml&key=ACCESSTOKENRETURNEDFROMCALLABOVE&echoInput=true &outputFieldOptions=companyEmployeeCount,companyRevenueNumeric,jobfunction,managementlevel&numMatches=10  

Access tokens expire every 6 hours, so the partner will have to create a mechanism for generating new access tokens every 6 hours to continue calling the Enhanced API person match request.

Example- Person Search with OAuth2 Token Authentication

The following example shows a Person Search query. The input parameters include:

  • Vice President for Person Title
  • 200714 for IndustryClassification (Search Engines & Internet Portals)
  • California for State

You will need to get an access token first. Instructions can be found here:

http://help.zoominfo.com/18440-partners/oauth2-token-authentication

The URL for the Person Search query using an OAuth Token would look like this:

http://partnerapi.zoominfo.com/partnerapi/v4/person/search?PersonTitle=VicePresident&IndustryClassification=200714&state=California&pc=PartnerCode&key=OAuthAccessToken

Note:The OAuth access token is valid for six hours and you can keep using the same access token no matter what parameters you are using, as long as the OAuth access token is valid.


Was this article helpful?

Can’t find what you’re looking for?

Contact our award-winning customer care team.