Pearl Diver REST API - Getting started

Pearl Diver REST API - Getting started

About

This is the reference for the Blackpearl Group Pearl Diver REST API. This API is the primary way to get Pearl Diver data outside of the web application. Use it to integrate your Pearl Diver data with CRMs, marketing automation tools, analytics and reporting tools, social media platforms and much more.

Authentication and authorization


Authentication

Authentication for the Blackpearl Group Pearl Diver REST API is implemented using OAuth 2.0, a widely adopted protocol for securing web APIs. OAuth 2.0 provides a secure and standardized way to allow third-party applications to access user data without exposing user credentials. The authentication process in OAuth 2.0 consists of a series of steps, often referred to as the "3-legged OAuth" process, which includes the following:

1. Authorization Request: The client application initiates the authentication process by requesting authorization from the user. This typically involves redirecting the user to the Blackpearl Group Pearl Diver authorization endpoint and specifying the desired scopes, including openid, profile, email, and offline_access.

Example Authorization Request (in your code, the actual URL and parameters may vary):

2. User Authentication: The user is presented with a login screen and is prompted to grant or deny access to their data. If the user grants access, they are redirected back to the client application's specified redirect URI with an authorization code.

Example Redirect URL:

  1. YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=csrf_token

3. Token Exchange: The client application exchanges the authorization code for an access token. This exchange is made directly with the Blackpearl Group Pearl Diver token endpoint.

Example Token Exchange Request:

  1. POST https://auth.pearldiver.io/oauth/token?audience=pearldiverapi
  2. Content-Type: application/x-www-form-urlencoded

  4. grant_type=authorization_code
  5. code=AUTHORIZATION_CODE
  6. client_id=YOUR_CLIENT_ID
  7. client_secret=YOUR_CLIENT_SECRET
  8. redirect_uri=YOUR_REDIRECT_URI

In this request, the client provides the authorization code received in step 2, along with its client ID and client secret for authentication.

4. Access API: With a valid access token, the client application can now access the Blackpearl Group Pearl Diver REST API on behalf of the user. Include the access token in the Authorization header of your API requests.

Example API Request (using the access token):

  1. GET https://api.pearldiver.io/v1/resource Authorization: Bearer ACCESS_TOKEN

5. Refreshing the Access Token: Access tokens may expire after a certain period. To maintain ongoing access without requiring the user to reauthenticate, the client can use the refresh token to obtain a new access token. This is done by making a request to the token endpoint with the refresh token.

Example Token Refresh Request:

  1. POST https://auth.pearldiver.io/oauth/token?audience=pearldiverapi
  2. Content-Type: application/x-www-form-urlencoded

  4. grant_type=refresh_token
  5. refresh_token=REFRESH_TOKEN
  6. client_id=YOUR_CLIENT_ID
  7. client_secret=YOUR_CLIENT_SECRET

The client provides the refresh token it obtained in step 3, along with its client ID and client secret. In response, it receives a new access token and, a new refresh token.

Remember to store the new access token and, the new refresh token securely for continued API access. The use of refresh tokens allows your application to maintain access without user intervention even when access tokens expire.

Please replace placeholders such as YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REDIRECT_URI, and desired_scope with your specific values when implementing OAuth 2.0 for the Blackpearl Group Pearl Diver REST API.

Authorization

Authorization is based on the user used in the authentication process. The user must have a valid Pearl Diver account to be authorized with the REST API.

Status codes

The Pearl Diver REST API uses the standard HTTP status codes. REST failures (400s, 500s) are returned without a response body.

Refresh Token Rotation

Refresh token rotation is a security measure used in authentication protocols, particularly OAuth 2.0, to enhance the security of long-lived refresh tokens. Refresh tokens are typically longer-lived and can be used to request new access tokens after the shorter-lived access tokens expire. With refresh token rotation, every time an application exchanges a refresh token to get a new access token, a new refresh token is also returned. Therefore, you no longer have a long-lived refresh token that, if compromised, could provide illegitimate access to resources. As refresh tokens are continually exchanged and invalidated, the threat is reduced.

Refresh Token Expiration

Refresh tokens can be a target for abuse if leaked because they can be used to acquire new access tokens. Refresh Token Rotation issues a refresh token that expires after a preset lifetime. After expiration, the user gets a new refresh token or a new access token/refresh token pair.
Pearl Diver rest API have the following refresh token expiration settings

  • Absolute Lifetime: Set a refresh token or refresh token family lifetime after which the user must re-authenticate before being issued a new access token.

Lifetime

31,557,600 seconds (1 year)

  • Inactivity Lifetime: Set the inactivity lifetime of issued refresh tokens to expire if the user is not active in your application during a specified period.

Lifetime

2,592,000 seconds (30 days)


Using the REST API

Audience

GET List Audiences

Returns all Audiences for an account
Permissions required: Authenticated

Request

Headers
Content-Type: application/json
The API only responds with JSON payloads

Accept: application/json
The API only accepts JSON body requests

Authorization: Bearer token  REQUIRED

Path parameters
No path parameters

Query parameters
No query parameters 

Responses

200 OK
Returned if the requested audiences are returned.
      application/json

      AudienceArray
      Properties
            audiences array<Audience>  REQUIRED
      
      Child properties
            key integer  REQUIRED

            name string. REQUIRED

400 Bad Request
Returned if the audience list could not be returned.





























GET /v1/audience

javascript

  1. // Make sure to install Axios if you haven't already.
  2. const axios = require('axios'); 

  4. const options = {
  5.   url: 'https://api.pearldiver.io/v1/audience',
  6.   method: 'GET',
  7.   headers: {
  8.     'Content-Type': 'application/json',
  9.     'Accept': 'application/json',
  10.     'Authorization': `Bearer ${access_token}`
  11.   }
  12. };

  14. axios(options)
  15.   .then((response) => {
  16.     if (response.status !== 200) {
  17.       throw new Error(`HTTP Error: ${response.status}`);
  18.     }
  19.     return response.data;
  20.   })
  21.   .then((results) => {
  22.     // You can do any parsing you need for results here before returning them
  23.     console.log(results);
  24.     return results;
  25.   })
  26.   .catch((error) => {
  27.     console.error(error);
  28.   });

200 Response

  1. {
  2.   "audiences": [
  3.     {
  4.       "key": 2,
  5.       "name": "Hot leads"
  6.     },
  7.     {
  8.       "key": 0,
  9.       "name": "Pearls"
  10.     }
  11.   ]
  12. }

GET Get Audience

Returns an audience. This includes information about the audience and the corresponding record data set.
Permissions required: Authenticated

Request

Headers
Content-Type: application/json
The API only responds with JSON payloads

Accept: application/json
The API only accepts JSON body requests

Authorization: Bearer token   REQUIRED

Path parameters
audienceKey: integer   REQUIRED
The key of the audience to be returned

Query parameters
range: integer   OPTIONAL
The period in days that the data will be retrieved against.
If the range parameter is not specified, record data for 90 days will be returned.

Default: 90

Minimun: 1
Maximum: 90

since: datetime   OPTIONAL
The datetime stamp that the data will be retrieved from. Cannot be used in combination with range parameter.
If the range and since parameters are not specified, record data for 90 days will be returned.

Default: date time 90 days ago

Maximum: date time 90 days ago 

Format: ISO 8601

pageToken string   OPTIONAL
The token for the next page of record data of the given audience. If the pageToken parameter is not specified, up to the first 1000 record data items will be returned.
The pageToken can be retrieved from the payload of the first and subsequent audience request that has more the 1000 data records.

Responses

200 OK
Returned if the requested audience is returned.
      application/json

      Audience
      Properties
           key integer  REQUIRED

           name string  REQUIRED

           pageToken string  OPTIONAL

           data array<Record>  OPTIONAL

      Child properties
         id integer   REQUIRED       

          firstName string   OPTIONAL

          lastName string   OPTIONAL

         email string    OPTIONAL

         jobTitle string   OPTIONAL

         seniorityLevel string   OPTIONAL

         department string.  OPTIONAL

         gender string.  OPTIONAL

         ageRange string.  OPTIONAL

         incomeRange string   OPTIONAL

         homeowner string   OPTIONAL

         married string   OPTIONAL

         children string   OPTIONAL

         netWorth string   OPTIONAL


         linkedIn string   OPTIONAL

         emailValidationStatus string.  OPTIONAL

         emailLastSeen datetime.  OPTIONAL

         count int   OPTIONAL

         latestActivityDate date.  OPTIONAL

         hotlistType string.  OPTIONAL

         phones array<Phone>   OPTIONAL

         addresses array<Address>   OPTIONAL

         company object   OPTIONAL

         websites array<string>   OPTIONAL

         sessions array<Session>   OPTIONAL


400 Bad Request
Returned if the audience list could not be returned.

404 Not Found
Returned if the specified audience key could not be found.




















































































GET /v1/audience/{audienceKey}

javascript

  1. const axios = require('axios'); // Make sure to install Axios if you haven't already.

  3. const options = {
  4.   url: `https://api.pearldiver.io/v1/audience/${audienceKey}`,
  5.   method: 'GET',
  6.   headers: {
  7.     'Content-Type': 'application/json',
  8.     'Accept': 'application/json',
  9.     'Authorization': `Bearer ${access_token}`
  10.   },
  11.   params: {}
  12. };

  14. let results = {};
  15. let nextPage = null; // Initialize the page number or pagination token

  17. async function fetchPage() {
  18.   if (nextPage !== null) {
  19.     // Include the 'pageToken' parameter in the URL if 'nextPage' is not null
  20.     options.params.pageToken = nextPage;
  21.   }

  23.   try {
  24.     const response = await axios(options);
  25.     
  26.     if (response.status !== 200) {
  27.       throw new Error(`HTTP Error: ${response.status}`);
  28.     }

  30.     const data = response.data;

  32.     // Process the data from the API response
  33.     // Add the relevant data to the 'results' object
  34.     if (nextPage === null) {
  35.       results = data;
  36.     } else {
  37.       results.data.push(...data.data);
  38.     }

  40.     if (data.pageToken) {
  41.       nextPage = data.pageToken;
  42.       await fetchPage();
  43.     }
  44.   } catch (error) {
  45.     console.error(error);
  46.   }
  47. }

  49. await fetchPage();

  51. // You can do any parsing you need for results here before returning them
  52. console.log(results);
  53. return results;

200 Response

  1. {
  2.   "name": "All Leads",
  3.   "key": 345,
  4.   "pageToken": "6AMAAA"
  5.   "data": [
  6.     {
  7.       "id": 21152,
  8.       "firstName": "Anthony",
  9.       "lastName": "Everett",
  10.       "email": "aeverett776@yahoo.com",
  11.       "gender": "M",
  12.       "ageRange": "35-44",
  13.       "incomeRange": "$150,000 to $199,999",
  14.       "homeowner": "Y",
  15.       "married": "Y",
  16.       "children": "Y",
  17.       "netWorth": "$75,000 to $99,999",
  18.       "phones": [
  19.         {
  20.           "type": "Mobile",
  21.           "number": "2954183224",
  22.           "order": 1
  23.         }
  24.       ],
  25.       "addresses": [
  26.         {
  27.           "type": "Personal",
  28.           "city": "Jonesfurt",
  29.           "state": "NJ",
  30.           "zip": "91424",
  31.           "zip4": "2705"
  32.         }
  33.       ],
  34.       "count": 3,
  35.       "latestActivityDate": "2023-09-14",
  36.       "hotlistType": "Visitor",
  37.       "sessions": [
  38.       {
  39.             "site": "sunsmart.com",
  40.             "referer": "https://l.facebook.com/",
  41.             "device": "Desktop",
  42.             "utm": {
  43.                   "medium": "abc",
  44.                   "campaign": "testing",
  45.                   "term": "hats",
  46.                   "content": "video-sunscreen",
  47.                   "source": "meta"
  48.             },
  49.             "visits": [
  50.             {
  51.                   "time": "2024-06-19T17:57:05Z",
  52. "pageUrl": "https://sunsmart.com/sunny/?utm_source=meta&utm_medium=abc&utm_campaign=testing&utm_content=video-sunscreen&utm_term=hat
  53.                   "path": "/sunny/",
  54.                   "host": "sunsmart.com",
  55. "queryString": "?utm_source=meta&utm_medium=abc&utm_campaign=testing&utm_content=video-sunscreen&utm_term=ha
  56.             },
  57.             {
  58.                   "time": "2024-06-19T17:57:05Z",
  59. "pageUrl": "https://sunsmart.com/sunny/?utm_source=meta&utm_medium=abc&utm_campaign=testing&utm_content=video-sunscreen&utm_term=hats",
  60.                   "path": "/sunny/",
  61.                   "host": "sunsmart.com",
  62. "queryString": "?utm_source=meta&utm_medium=abc&utm_campaign=testing&utm_content=video-sunscreen&utm_term=hats"
  63.             },
  64.             {
  65.                   "time": "2024-06-19T17:57:05Z",
  66. "pageUrl": "https://sunsmart.com/sunny/?utm_source=meta&utm_medium=abc&utm_campaign=testing&utm_content=video-sunscreen&utm_term=hats",
  67.                   "path": "/sunny/",
  68.                   "host": "sunsmart.com",
  69. "queryString": "?utm_source=meta&utm_medium=abc&utm_campaign=testing&utm_content=video-sunscreen&utm_term=hats"
  70.             }
  71.             ]
  72.       }]
  73.     },
  74.     {
  75.       "id": 21833,
  76.       "email": "afleming@andrade.com",
  77.       "phones": [],
  78.       "addresses": [],
  79.       "count": 3,
  80.       "latestActivityDate": "2023-09-10",
  81.       "hotlistType": "Visitor",
  82.       "sessions": [
  83.       {
  84.             "site": "sunsmart.com",
  85.             "referer": "https://l.facebook.com/",
  86.             "visits": [
  87.             {
  88.                   "time": "2024-06-19T17:45:05Z",
  89.                    "pageUrl": "https://sunsmart.com/sunny/?hd-gh=Fun"
  90.                   "path": "/sunny/",
  91.                   "host": "sunsmart.com",
  92.                   "queryString": "?hd-gh=Fun"
  93.             }]
  94.       },
  95.        {
  96.             "site": "sunsmart.com",
  97.             "referer": "https://l.facebook.com/",
  98.             "visits": [
  99.             {
  100.                   "time": "2024-06-19T17:48:05Z",
  101.                    "pageUrl": "https://sunsmart.com/sunny/?hd-gh=Fun"
  102.                   "path": "/sunny/",
  103.                   "host": "sunsmart.com",
  104.                   "queryString": "?hd-gh=Fun"
  105.             }]
  106.       }]
  107.     },
  108.     {
  109.       "id": 27779,
  110.       "email": "ahartman@yahoo.com",
  111.       "phones": [],
  112.       "addresses": [],
  113.       "count": 2,
  114.       "latestActivityDate": "2023-09-01",
  115.       "sessions": [
  116.       {
  117.             "site": "sunsmart.com",
  118.             "referer": "https://l.facebook.com/",
  119.             "visits": [
  120.             {
  121.                   "time": "2024-06-19T17:45:05Z",
  122.                    "pageUrl": "https://sunsmart.com/"
  123.                   "path": "/",
  124.                   "host": "sunsmart.com"
  125.             }]
  126.       }]
  127.     }
  128.   ]
  129. }

Phone

phoneType string  OPTIONAL

number string  OPTIONAL

validationStatus string  OPTIONAL

lastSeen datetime  OPTIONAL

extension string  OPTIONAL

order integer  OPTIONAL

Address

addressType string  OPTIONAL

address1 string  OPTIONAL

address2 string  OPTIONAL

city string  OPTIONAL

state string  OPTIONAL

zip string  OPTIONAL

zip4 string  OPTIONAL

Company

name string  OPTIONAL

domain string  OPTIONAL

industry string  OPTIONAL

sic1 string  OPTIONAL

sic2 string  OPTIONAL

sic3 string  OPTIONAL

companyCount integer  OPTIONAL

linkedIn string  OPTIONAL

revenue string  OPTIONAL

employeeCount string  OPTIONAL

Session

site string  OPTIONAL

device string  OPTIONAL

referer string  OPTIONAL

utm object  OPTIONAL

visits array<visit>  OPTIONAL

Utm

medium string  OPTIONAL

campaign string  OPTIONAL

term string  OPTIONAL

content string  OPTIONAL

source string  OPTIONAL


Visit

time datetime  OPTIONAL

pageUrl string  OPTIONAL

path string  OPTIONAL

host string  OPTIONAL

queryString string  OPTIONAL






    • Related Articles

    • Pearl Diver REST API - FAQ

      What is an API? An API, or Application Programming Interface, is like a middleman between different software programs, helping them communicate with each other. It takes requests from one program, tells another program what to do, and brings back the ...

    • Getting Started with Pearl Diver

      Welcome to the exciting world of Pearl Diver, an advanced website visitor tracking tool designed to help you see who’s behind the clicks on your website and how to connect with them, and make informed decisions. This guide will help you get started ...

    • Why you need an Ideal Customer Profile (ICP) and how to get it with Pearl Diver

      Building an Ideal Customer Profile is an integral part of any successful sales strategy, but it’s also a great way to bring focus to your marketing efforts and understand who your best customers are. What is an Ideal Customer Profile (ICP) ICP, or ...

    • Cancel your Pearl Diver Subscription

      We understand that circumstances change, and you may be considering canceling your Pearl Diver subscription. Before you proceed, we want to ensure that you have all the information you need to make an informed decision. In this article, we'll guide ...

    • Understanding your Pearl Diver data

      Understanding your data Recent statistics reveal a stark reality: between 50-75% of site visits are bots. Consequently, the actual number of identified visitors amounts to only 20-25% of your Google Analytics report. *Google Analytics filters known ...