# Adding a Domain
## Add a new domain
> 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.
```json
{"openapi":"3.0.3","info":{"title":"Domain Monitor API - Merchant Portal","version":"1.0.0"},"tags":[{"name":"Domains","description":"Domain monitoring and management"}],"servers":[{"url":"https://uat-monitor.payshield.ai","description":"Uat server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT access token obtained from login endpoint"}},"schemas":{"Domain":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid","description":"ID of the user (merchant) who owns this domain."},"domain":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]},"recommendation":{"type":"string","enum":["pass","fail","review"],"nullable":true,"description":"Verification recommendation from the most recent web presence check. A null value indicates that verification has not completed or failed. Monitoring may still be active when this value is null.\n"},"provider":{"type":"string"},"checkFrequency":{"type":"string","enum":["7","30","90"],"description":"Monitoring frequency in days:\n- '7': Weekly monitoring (every 7 days)\n- '30': Monthly monitoring (every 30 days)\n- '90': Quarterly monitoring (every 90 days)\n\nThis value is sent to the monitoring provider (e.g., TrueBiz) to configure the monitoring package frequency.\n"},"lastCheckedAt":{"type":"string","format":"date-time","nullable":true},"nextCheckAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"details":{"type":"object"}}}},"responses":{"ValidationError":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnauthorizedError":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/domains":{"post":{"tags":["Domains"],"summary":"Add a new domain","description":"Register a new domain and start monitoring immediately. \nAn 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.\n","operationId":"createDomain","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","maxLength":255,"description":"Domain name (required if name not provided)"},"name":{"type":"string","maxLength":255,"description":"Business name (required if domain not provided)"},"description":{"type":"string","maxLength":1000,"description":"Business description"},"website":{"type":"string","format":"uri","maxLength":500,"description":"Full website URL"},"addressLine1":{"type":"string","maxLength":255,"description":"Street address line 1"},"addressLine2":{"type":"string","maxLength":255,"description":"Street address line 2"},"city":{"type":"string","maxLength":100,"description":"City"},"stateProvince":{"type":"string","maxLength":100,"description":"State or province"},"postalCode":{"type":"string","maxLength":20,"description":"Postal/ZIP code"},"country":{"type":"string","maxLength":100,"description":"Country"},"email":{"type":"string","format":"email","maxLength":255,"description":"Contact email"},"phone":{"type":"string","maxLength":50,"description":"Contact phone number"},"fullName":{"type":"string","maxLength":255,"description":"Contact person full name"},"externalTrackingRef":{"type":"string","maxLength":255,"description":"External tracking reference ID"},"checkFrequency":{"type":"string","enum":["7","30","90"],"nullable":true,"description":"Monitoring frequency in days:\n- '7': Weekly monitoring (every 7 days)\n- '30': Monthly monitoring (every 30 days)\n- '90': Quarterly monitoring (every 90 days)\n\nIf not provided (null/empty), no ongoing monitoring will be started - only a one-time domain/company check is performed.\nThis value is sent to the monitoring provider to configure the monitoring package frequency.\n"}}}}}},"responses":{"201":{"description":"Domain created successfully and initial verification attempted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Domain"}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"409":{"description":"Domain already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
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
> 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.
```json
{"openapi":"3.0.3","info":{"title":"Domain Monitor API - Merchant Portal","version":"1.0.0"},"tags":[{"name":"Domains","description":"Domain monitoring and management"}],"servers":[{"url":"https://uat-monitor.payshield.ai","description":"Uat server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT access token obtained from login endpoint"}},"schemas":{"Domain":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid","description":"ID of the user (merchant) who owns this domain."},"domain":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]},"recommendation":{"type":"string","enum":["pass","fail","review"],"nullable":true,"description":"Verification recommendation from the most recent web presence check. A null value indicates that verification has not completed or failed. Monitoring may still be active when this value is null.\n"},"provider":{"type":"string"},"checkFrequency":{"type":"string","enum":["7","30","90"],"description":"Monitoring frequency in days:\n- '7': Weekly monitoring (every 7 days)\n- '30': Monthly monitoring (every 30 days)\n- '90': Quarterly monitoring (every 90 days)\n\nThis value is sent to the monitoring provider (e.g., TrueBiz) to configure the monitoring package frequency.\n"},"lastCheckedAt":{"type":"string","format":"date-time","nullable":true},"nextCheckAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"details":{"type":"object"}}}},"responses":{"UnauthorizedError":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFoundError":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/domains/{id}/check":{"post":{"tags":["Domains"],"summary":"Manually trigger Web Presence Check","description":"Manually retry the web presence verification for an existing domain.\n\nThis endpoint is intended for cases where the initial verification failed,\ntimed out, or returned incomplete data. It re-attempts verification only and\ndoes not affect monitoring status.\n\nThis operation may take up to 30–40 seconds depending on provider response times.\n","operationId":"recheckDomain","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Domain ID"}],"responses":{"200":{"description":"Web presence check completed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Domain"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"}}}}}}
```
#### 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 |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.payshield.ai/merchant-monitoring-api/adding-a-domain.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.