Adding a Domain

Add a single domain or business for monitoring.

Add a new domain

post

Register a new domain and start monitoring immediately. An initial web presence verification is attempted asynchronously. Verification may fail, timeout, or return incomplete data and does not affect the monitoring status of the domain.

Authorizations

AuthorizationstringRequired

JWT access token obtained from login endpoint

Body

domainstring · max: 255Optional

Domain name (required if name not provided)

Example: example.com

namestring · max: 255Optional

Business name (required if domain not provided)

Example: Bob's Burritos

descriptionstring · max: 1000Optional

Business description

Example: A family-owned burrito restaurant serving authentic Mexican cuisine

websitestring · uri · max: 500Optional

Full website URL

Example: https://bobsburritos.com

addressLine1string · max: 255Optional

Street address line 1

Example: 123 Main Street

addressLine2string · max: 255Optional

Street address line 2

Example: Suite 100

citystring · max: 100Optional

City

Example: San Francisco

stateProvincestring · max: 100Optional

State or province

Example: CA

postalCodestring · max: 20Optional

Postal/ZIP code

Example: 94102

countrystring · max: 100Optional

Country

Example: USA

emailstring · email · max: 255Optional

Contact email

Example: [e-mail]

phonestring · max: 50Optional

Contact phone number

Example: [phone]

fullNamestring · max: 255Optional

Contact person full name

Example: Bob Rodriguez

externalTrackingRefstring · max: 255Optional

External tracking reference ID

Example: MERCH-12345

checkFrequencystring · enum · nullableOptional

Monitoring frequency in days:

• '7': Weekly monitoring (every 7 days)
• '30': Monthly monitoring (every 30 days)
• '90': Quarterly monitoring (every 90 days)

If not provided (null/empty), no ongoing monitoring will be started - only a one-time domain/company check is performed. This value is sent to the monitoring provider to configure the monitoring package frequency.

Possible values:

Responses

201

Domain created successfully and initial verification attempted

application/json

messagestringOptionalExample: Domain created and verification initiated

400

Validation failed

application/json

401

Authentication required or token invalid

application/json

409

Domain already exists

application/json

post/api/v1/domains

POST /api/v1/domains HTTP/1.1
Host: uat-monitor.payshield.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 455

{
  "domain": "example.com",
  "name": "Bob's Burritos",
  "description": "A family-owned burrito restaurant serving authentic Mexican cuisine",
  "website": "https://bobsburritos.com",
  "addressLine1": "123 Main Street",
  "addressLine2": "Suite 100",
  "city": "San Francisco",
  "stateProvince": "CA",
  "postalCode": "94102",
  "country": "USA",
  "email": "[e-mail]",
  "phone": "[phone]",
  "fullName": "Bob Rodriguez",
  "externalTrackingRef": "MERCH-12345",
  "checkFrequency": "7"
}

{
  "message": "Domain created and verification initiated",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "example.com",
    "name": "My Business Website",
    "status": "active",
    "recommendation": "pass",
    "provider": "truebiz",
    "checkFrequency": "7",
    "lastCheckedAt": "2026-01-01T00:00:00.000Z",
    "nextCheckAt": "2026-01-01T00:00:00.000Z",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}

Since web presence verification is processed asynchronously, the initial POST /domains response may return with recommendation: null.

A Web Presence Check attempt is automatically triggered when the domain is created. If this attempt fails, times out, or returns incomplete data, you may manually retry verification using the Manually trigger Web Presence Check endpoint (see below).

Monitoring continues regardless of verification outcome.

Manually trigger Web Presence Check

post

Manually retry the web presence verification for an existing domain.

This endpoint is intended for cases where the initial verification failed, timed out, or returned incomplete data. It re-attempts verification only and does not affect monitoring status.

This operation may take up to 30–40 seconds depending on provider response times.

Authorizations

AuthorizationstringRequired

JWT access token obtained from login endpoint

Path parameters

idstring · uuidRequired

Domain ID

Responses

200

Web presence check completed successfully

application/json

messagestringOptionalExample: Web presence check completed successfully

401

Authentication required or token invalid

application/json

404

Resource not found

application/json

post/api/v1/domains/{id}/check

POST /api/v1/domains/{id}/check HTTP/1.1
Host: uat-monitor.payshield.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "Web presence check completed successfully",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "example.com",
    "name": "My Business Website",
    "status": "active",
    "recommendation": "pass",
    "provider": "truebiz",
    "checkFrequency": "7",
    "lastCheckedAt": "2026-01-01T00:00:00.000Z",
    "nextCheckAt": "2026-01-01T00:00:00.000Z",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}

Recommended Integration Pattern

1. POST /domains → Returns domain with recommendation: null
2. Poll GET /domains/{id}/check until recommendation is not null
3. Process the result (pass/fail/review)

Typical Processing Times

Scenario	Typical Time
Domain with existing data	2-5 seconds
New domain lookup	5-15 seconds
Business name search	5-20 seconds
Provider timeout/retry	Up to 30 seconds