Compliance Display Ads API

This section details the API endpoints for retrieving compliance display ad data associated with your company.

Endpoint: /display-ads Base URL: https://app.integrishield.com/api

List Display Ads

  • Method: GET
  • Full Endpoint: https://app.integrishield.com/api/display-ads
  • Description: Retrieves a paginated list of compliance display ads for your company. Supports filtering by status, affiliate, ad network, and date range.
  • 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.
ad_network integer No Filter by ad network ID.
discovery_after date No Return ads discovered on or after this date (format: YYYY-MM-DD).
discovery_before date No Return ads discovered on or before this date (format: YYYY-MM-DD).
sort_by string No Field to sort by. Allowed values: id, discovery_dt, review_dt. 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/display-ads?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 display ad data and pagination metadata.

{
  "code": "1026",
  "status": "ok",
  "detail": {
    "msg": "Display ads found"
  },
  "data": [
    {
      "id": 5678,
      "discovery_date": "2024-03-15 10:30:00",
      "review_date": "2024-03-20 14:00:00",
      "landing_page_link": "https://example.com/landing",
      "screenshot_links": "https://storage.example.com/screenshots/5678.png",
      "intermediate_links": "https://example.com/redirect",
      "ad_network": "Facebook",
      "ad_campaign": "Spring Promo 2024",
      "social_handle": "@example_handle",
      "affiliate_name": "John Smith",
      "affiliate_id": "ABC123",
      "affiliate_manager_name": "Jane Doe",
      "sub_affiliate_id": null,
      "incident_status": "Open",
      "country": "United States",
      "case_id": 678,
      "note": "Flagged for misleading claims",
      "video_path": null,
      "transcription_text": null,
      "transcription_status": null,
      "infractions": [
        {
          "infraction_id": 42,
          "infraction_type": "Income Claims",
          "infraction_name": "Unsubstantiated Earnings",
          "infraction_status": "Open",
          "created_date": "2024-03-15 10:30:00",
          "resolved_date": null
        }
      ]
    }
  ],
  "meta": {
    "total": 42,
    "per_page": 50,
    "current_page": 1,
    "last_page": 1
  }
}

Get Single Display Ad

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

Path Parameters:

Parameter Type Required Description
id integer Yes The unique identifier of the display ad.

Example Request:

GET /api/display-ads/5678

Success Response (200 OK):

Returns a JSON object containing the display ad data.

{
  "code": "1026",
  "status": "ok",
  "detail": {
    "msg": "Display ad found"
  },
  "data": {
    "id": 5678,
    "discovery_date": "2024-03-15 10:30:00",
    "review_date": "2024-03-20 14:00:00",
    ...
  }
}

Error Response (404 Not Found):

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

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

Display Ad Object Reference

Each display ad object in the response contains the following fields:

Identity & Dates

Field Type Description
id integer Unique identifier for the display ad.
discovery_date datetime|null When the ad was first discovered.
review_date datetime|null When the ad was last reviewed.
Field Type Description
landing_page_link string|null URL of the ad's landing page.
screenshot_links string|null URL(s) of ad screenshots.
intermediate_links string|null Intermediate/redirect URLs associated with the ad.

Ad Details

Field Type Description
ad_network string|null Name of the ad network (e.g., "Facebook", "Google Display").
ad_campaign string|null Campaign name or identifier.
social_handle string|null Social media handle associated with the ad.

Affiliate Information

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

Status & Location

Field Type Description
incident_status string|null Current incident status name.
country string|null Country associated with the ad.

Case & Notes

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

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

Infraction Object:

Field Type Description
infraction_id integer Unique identifier for the infraction.
infraction_type string|null Category of the infraction (e.g., "Income Claims").
infraction_name string|null Specific name of the infraction (e.g., "Unsubstantiated Earnings").
infraction_status string|null Current status of the infraction.
created_date datetime|null When the infraction was created.
resolved_date datetime|null When the infraction was resolved, if applicable.

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