Compliance URLs API

This section details the API endpoints for managing compliance URLs associated with your company.

Endpoint: /urls Base URL: https://app.integrishield.com/api

List Compliance URLs

• Method: GET
• Full Endpoint: https://app.integrishield.com/api/urls
• Description: Retrieves a paginated list of compliance URLs for your company. Supports filtering by status, affiliate, date range, and more.
• Authentication: Required (Bearer Token).

Query Parameters:

Parameter	Type	Required	Description
incident_status_id	integer	No	Filter by incident status ID.
distributor_id	integer	No	Filter by distributor/affiliate ID.
disabled	string	No	Filter by disabled status. Allowed values: yes, no.
discovery_after	date	No	Return URLs discovered on or after this date (format: YYYY-MM-DD).
discovery_before	date	No	Return URLs discovered on or before this date (format: YYYY-MM-DD).
sort_by	string	No	Field to sort by. Allowed values: id, discovery_dt, last_review_dt, last_seen. Default: id.
sort_dir	string	No	Sort direction. Allowed values: asc, desc. Default: desc.
per_page	integer	No	Number of results per page. Min: 1. Max: 200. Default: 100.
page	integer	No	Page number to retrieve. Default: 1.

Example Request:

GET /api/urls?incident_status_id=2&discovery_after=2024-01-01&per_page=50&sort_by=discovery_dt&sort_dir=desc

Success Response (200 OK):

Returns a JSON object containing the URL data and pagination metadata.

{
  "code": "1026",
  "status": "ok",
  "detail": {
    "msg": "URLs found"
  },
  "data": [
    {
      "id": 12345,
      "url": "https://example.com/page",
      "domain": "example.com",
      "discovery_date": "2024-03-15 10:30:00",
      "last_review_date": "2024-03-20 14:00:00",
      "last_crawl_date": "2024-03-22 08:00:00",
      "last_seen": "2024-03-22 08:00:00",
      "affiliate_name": "John Smith",
      "affiliate_id": "ABC123",
      "sub_affiliate_id": null,
      "incident_status": "Open",
      "disabled": "no",
      "false_positive": "no",
      "country": "United States",
      "owner_email": "owner@example.com",
      "social_one": "https://facebook.com/example",
      "social_two": null,
      "social_three": null,
      "phone_one": "555-123-4567",
      "phone_two": null,
      "landing_page": "https://example.com/landing",
      "case_id": 678,
      "note": "Flagged for review",
      "video_path": null,
      "transcription_text": null,
      "transcription_status": null,
      "infractions": [
        {
          "infraction_type": "Trademark Violation",
          "infraction_name": "Unauthorized Logo Usage",
          "created_date": "2024-03-15 10:30:00"
        }
      ]
    }
  ],
  "meta": {
    "total": 85,
    "per_page": 50,
    "current_page": 1,
    "last_page": 2
  }
}

---

Get Single Compliance URL

• Method: GET
• Full Endpoint: https://app.integrishield.com/api/urls/{id}
• Description: Retrieves detailed information for a specific compliance URL by its ID.
• Authentication: Required (Bearer Token).

Path Parameters:

Parameter	Type	Required	Description
id	integer	Yes	The unique identifier of the compliance URL.

Example Request:

GET /api/urls/12345

Success Response (200 OK):

Returns a JSON object containing the URL data.

{
  "code": "1026",
  "status": "ok",
  "detail": {
    "msg": "URL found"
  },
  "data": {
    "id": 12345,
    "url": "https://example.com/page",
    "domain": "example.com",
    ...
  }
}

Error Response (404 Not Found):

Returned if no URL exists with the specified ID, or the URL does not belong to your company.

{
  "code": "1025",
  "status": "error",
  "detail": {
    "msg": "URL not found."
  }
}

---

Add Compliance URL(s)

• Method: POST
• Full Endpoint: https://app.integrishield.com/api/urls
• Description: Adds one or more compliance URLs to be monitored by Integrishield for your company. If a submitted URL already exists for your company, it will be skipped during processing, and an appropriate status (code: 1023) will be returned for that specific URL in the response array. The overall HTTP status will still be 201 Created if the request format is valid, even if some URLs are skipped.
• Authentication: Required (Bearer Token).

Request Body:

The request body must be a JSON object containing a single key urls, which holds an array of URL objects. Each object inside the urls array must have a url key containing a complete and valid URL string.

{
  "urls": [
    {
      "url": "https://www.yourcompany.com/compliance-policy"
    },
    {
      "url": "https://www.yourcompany.com/terms-of-service"
    }
  ]
}

Fields:

• urls (array, required): An array of URL objects.
  • url (string, required, valid URL): The full compliance URL (including http:// or https://) to add. Must be a properly formatted URL.

Success Response (201 Created):

Returns a JSON array. Each element in the array corresponds to a URL object submitted in the request, indicating the result of the operation for that specific URL.

• Example (All URLs Added Successfully):

[
  {
    "code": "1020",
    "status": "ok",
    "detail": {
      "url_id": 123,
      "msg": "https://www.yourcompany.com/compliance-policy added successfully."
    }
  },
  {
    "code": "1020",
    "status": "ok",
    "detail": {
      "url_id": 124,
      "msg": "https://www.yourcompany.com/terms-of-service added successfully."
    }
  }
]

• Example (Mixed Success / Duplicate Skipped):

[
  {
    "code": "1020",
    "status": "ok",
    "detail": {
      "url_id": 125,
      "msg": "https://new-url.com/privacy added successfully."
    }
  },
  {
    "code": "1023",
    "status": "error",
    "detail": {
      "msg": "https://www.yourcompany.com/compliance-policy already exists for this client.  Skipping."
    }
  }
]

Error Responses:

• 422 Unprocessable Entity: Returned if the request body validation fails. Common reasons include:
  • The urls key is missing or its value is not an array.
  • An object within the urls array is missing the required url key.
  • A value provided for a url key is not a valid URL format. The response body will contain a message summarizing the errors and an errors object detailing the specific fields and issues.

{
  "message": "Each `url` must be a valid URL (and 1 more error)",
  "errors": {
    "urls.0.url": [
      "Each `url` must be a valid URL"
    ],
    "urls.1": [
        "Each URL object must have a `url` field"
    ]
  }
}

---

URL Object Reference

Each URL object in the response contains the following fields:

Identity & Status

Field	Type	Description
id	integer	Unique identifier for the URL.
url	string	The full compliance URL.
domain	string|null	Domain name extracted from the URL.
incident_status	string|null	Current incident status name.
disabled	string	Whether the URL is disabled (yes or no).
false_positive	string|null	Whether the URL is marked as a false positive.
country	string|null	Country associated with the URL.

Dates

Field	Type	Description
discovery_date	datetime|null	When the URL was first discovered.
last_review_date	datetime|null	When the URL was last reviewed.
last_crawl_date	datetime|null	When the URL was last crawled.
last_seen	datetime|null	When the URL was last seen active.

Affiliate Information

Field	Type	Description
affiliate_name	string|null	Name of the associated affiliate/distributor.
affiliate_id	string|null	Client-assigned affiliate ID.
sub_affiliate_id	string|null	Sub-affiliate identifier, if applicable.

Contact & Social

Field	Type	Description
owner_email	string|null	Email of the URL owner.
social_one	string|null	Primary social media link.
social_two	string|null	Secondary social media link.
social_three	string|null	Third social media link.
phone_one	string|null	Primary phone number.
phone_two	string|null	Secondary phone number.
landing_page	string|null	Associated landing page URL.

Case & Notes

Field	Type	Description
case_id	integer|null	ID of the associated compliance case, if any.
note	string|null	Notes about the URL.

Video & Transcription

Field	Type	Description
video_path	string|null	Path to associated video content.
transcription_text	string|null	Transcribed text from video content.
transcription_status	string|null	Status of the transcription process.

Infractions

Field	Type	Description
infractions	array	Array of infraction objects associated with the URL.

Infraction Object:

Field	Type	Description
infraction_type	string|null	Category of the infraction (e.g., "Trademark Violation").
infraction_name	string|null	Specific name of the infraction (e.g., "Unauthorized Logo Usage").
created_date	datetime|null	When the infraction was created.

---

Common Error Responses

• 401 Unauthorized: If the Bearer token is missing, invalid, or expired.

• 429 Too Many Requests: If you exceed the API rate limit. Wait before retrying.

• 500 Internal Server Error: If an unexpected error occurs on the server during processing.

{
  "code": "500",
  "status": "error",
  "detail": {
    "msg": "Server error! Contact server admin."
  }
}