Skip to content
Raise a Ticket
Contact us
  • There are no suggestions because the search field is empty.

How to Integrate REST API with Pearl Diver

Pearl Diver's REST API allows you to access your Pearl Diver data outside the web app, enabling seamless integrations with CRMs, marketing automation platforms, analytics tools, reporting systems, social platforms, and more.

Authentication

Authentication for the 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.

 
 

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

 
 
Using the REST API
 

Headline notes:

To use the REST API, the audience must be connected to the REST API integration within your Pearl Diver account. If the audience is not connected, the API will not be able to return its data.

The REST API only two endpoints :
 

1. List all audiences

 

2. Retrieve the records (leads) for a specific audience

 
Before calling the audience detail endpoint, please fetch the list of available audiences using:
GET /v1/audience
 
This will show you the exact audienceKey values your account is connected to access. Only those keys can be used with: GET /v1/audience/{audienceKey}
 
If you receive 400 responses, it typically means that the audience key being used does not exist or is not connected to the REST API for the account associated with your access token.
 

Full technical details:

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

Modal references

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