Domain Authorization API

As part of the security process defined for the PII Leaks API, Webhose requires approval from the domain owner in order to allow query-visibility to the domain using PII Leaks.

Authorization Process

The following diagram illustrates the main steps in the process.

Domain authorization process

Domain authorization process

Step 1 - Submit Domain for authorization

  • Initiator: Customer
  • Description: The customer initiates a call to the Webhose API to approve a domain
  • How: Using API (see below API Details)
  • Response: Immediate

Step 2 - Email Sent to Domain Admin

  • Initiator: Webhose
  • Description: Webhose sends an email to the domain owner to approve customer's request
  • How: Using automatic Email Request that includes the link to approve (see below API Details)
  • Response: depends on the admin owner time to respond (we expect hours to days)

Step 3 - Domain Activation

  • Initiator: Admin Owner
  • Description: Admin Owner activates the domain
  • How: Using the link provided in the email, Admin Owner can approve the customer PII Leaks searches on the domain (see below API Details)
  • Response: Immediate

API Requests

Submit Domain for authorization (Step 1)

GET
https://webhose.io/pii/api/addDomain

PARAMS:
token=<USER_API_KEY>
email=admin@<REQUESTED_DOMAIN>

  • Email should be one of the following: [admin, administrator, webmaster]

Endpoint example:

https://webhose.io/pii/api/addDomain?token=<YOUR_API_KEY>&email=admin@webhose.io

JSON Response:
"success": "An activation email has been sent to your domain administrator (admin@webhose.io)"

Domain Activation (Step 3)

GET
https://webhose.io/pii/api/activateDomain

PARAMS
confirmationToken=<UNIQUE_DOMAIN_TOKEN>

JSON Response
SUCCESS:
"success": true

ERRORS:

  • confirmationToken is required
  • invalid confirmationToken

What's Next

GET Parameters