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

1. The partner needs to create a JSON Web Token (JWT) using their partner code (and optionally their contact email address), using libraries we have approved.
2. The partner must pass the JWT into the body of the “…v2/token” request to generate an OAuth access token.
3. The partner must pass the OAuth access token returned from the “…v2/token” request into an API Search, Detail, or Match request as the value of the “key” input parameter.

1. 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#

To create a JWT token using C# please visit https://github.com/jwt-dotnet/jwt for the latest code and an example of how to use it.

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;
 var uuid = require("uuid");

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

payload= {
 iss :ISSUER,
 iat : iat,
 exp : exp ,
 jti : uuid(),
 ziPayLoad :zipayload
 };

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.

Creating a JWT using PHP

This example uses JWT library from: https://github.com/firebase/php-jwt.

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 setup: 

require_once dirname(__FILE__) . '/vendor/autoload.php';
use \Firebase\JWT\JWT;

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.

$iatOri = time();
$iat = $iatOri;
$expOri = $iatOri + 3600;
$exp = $expOri;
$jti = uuidv4();
 
// Function to create unique key
function uuidv4() {
 
  $str = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx';
 
  //assert(strlen($str) == 16);
 
 $str[6] = chr(ord($str[6]) & 0x0f | 0x40); // set version to 0100
 $str[8] = chr(ord($str[8]) & 0x3f | 0x80); // set bits 6-7 to 10
 
  return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($str), 4));
}

3. 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.

$payload = array(
  'iss'=> 'zoominfo',
  'iat'=> $iat,
  'jti'=> $jti,
  'exp'=> $exp,
  'ziPayLoad'=> array(
      'ziPartnerCode'=>'YOUR PARTNER CODE'
  )
);

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

$jwt = JWT::encode($payload, 'YOUR PASSWORD');
** $jwt will contain the 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"
 ]
}

2. Request an Access Token based on your JWT:

https://partnerapi.zoominfo.com/partnerapi/v2/token

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>

3. Make a Partner API Search, Detail, or Match Request:

The partner should then call the PartnerAPI (parameter values below are just examples using enhanced person match). The key will be an OAuth access token: https://partnerapi.zoominfo.com/partnerapi/v4/enhanced/person/match? firstName=jon&lastName=smith&[email protected]&pc=PartnerCode&outputType=xml&key=ACCESSTOKENRETURNEDFROMCALLABOVE&echoInput=true &outputFieldOptions=companyEmployeeCount,companyRevenueNumeric,jobfunction,managementlevel&numMatches=10

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:

https://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.

*Troubleshooting Tips*

1. Confirm that your partner code (often called “pc”) and password are correct in your JSON Web token (JWT) creation code. 
2. Confirm that your partner code and password are referenced in the proper places in your JWT creation code. We have seen cases where customers have switched their partner code for their password.
3. Confirm that there are no typos in your JWT creation code – it is very important that you match the case in our examples above.  
4. Make sure that you specify the JWT issued at time (usually called “iat”) and JWT expiration time (usually called “exp”) in seconds.
5. Confirm there are no other deviations from our examples above.  Any slight deviation may be the source of a problem.
6. Finally, we have found that some of our customers pass their JWT directly into an API search/detail/match request as the value of the “key” parameter.  This is incorrect.  The JWT must be passed into a “…v2/token” request first, in order to generate an OAuth access token.  This OAuth access token should then be used as the value of the “key” parameter in API search/detail/match requests.