Skip to content

GET /api/v3/campaigns/{lcuid}/pull/{boardIdentifier}

Summary

GET campaigns/{id}/pull/{boardIdentifier}

Description

An endpoint for digital signage player software to retrieve a creative for a campaign/board combination

This endpoint is designed to be used by digital signage players that are running single Lucit campaigns as part of their loop, mixed in with other campaigns or content.

Using your internal vendor id for your screen boardIdentifier and the lcuid for the campaign, you can fetch the create for that screen from this specific campaign.

Every pull to this endpoint may result in a new creative being returned depending on the campaign setup the user has created in Lucit

This endpoint also returns a pingback_url that is the reporting url for this specific creative and board.

If you are building a player implementation that utilizes Lucit as your content source for all plays on the screen, please use the Playlist Endpoint for each of your screens.

Tags: campaign_puller

Parameters

Header Parameters

Name Type Required Description Example
Authorization string ✓ Yes Bearer {AuthToken}
Content-Type string ✓ Yes application/json
Accept string ✓ Yes application/json
AppIdV3 string ✓ Yes LCUID-LAP-********-****-****-****-************

Responses

Response: 200

Description: Sample Response

Content Type: application/json

Schema

Type: object

Properties:

  • format (string): The format of the response - Should always be v3
  • creative (object) Type: object

Properties:

  • account (string): The name of the account that owns the campaign
  • campaign_hash_id (string): The encoded hashid for the campaign (Legacy)
  • campaign_lcuid (string): lcuid for the campaign See Campaign Object
  • campaign_build_id (string): The build id for the campaign This number increases when new creative builds happen and can indicate that some state of the campaign has changed (new creatives, changed creatives, etc.) - This is not guaranteed to be the case and generally should be ignored
  • board_identifier (string): The vendor id for the screen See Digital Board Object This is the board_identifier param on the digital_board object
  • board_lcuid (string): The lcuid for the digital board
  • board_name (string): The name for the screen - Name of the digital board object
  • lucit_digital_board_id (string): Internal integer id for the board in Lucit - Supplied for rendering pingback urls
  • item_count (string): The total number of items in the campaign
  • item_selected_index (string): The index of the item that was selected for this pull
  • creative_name (string): The name of the creative that was selected for this pull
  • creative_slug (string): The slug of the creative that was selected for this pull
  • creative_id (string): The composite id for the campaign/creative This id encodes both the campaign ID and the creative id into a single composite id for the playback reporting url. The format of this ID may change, and the version of this ID is in the prefix (e.g. C1- is version 1)
  • play_duration (integer)
  • id (string): The internal integer id for the creative - Here for legacy reasons
  • lcuid (string): the creative lcuid
  • approval_status (string): The lucit approval status for the creative See Creative Approval Statuses
  • src (string): The url to the creative image
  • hash (string): The hash of the creative image Useful for players who want to validate that the contents of the image url have not been altered
  • hash_algo (string): The algorithm used to generate the hash
  • width (string): The width of the creative image in pixels
  • height (string): The height of the creative image in pixels
  • creative_datetime (string): The date/time the creative was created
  • pingback_url (string): The url to pingback to when the creative is played to provide proof of play reporting. Pinging this URL once, will record a single play. Do not ping this url multiple times for the same play. This url will contain the following 3 self-explanatory macros
  • ${PLAY_DATETIME_UTC}
  • ${PLAY_DURATION_SECONDS}
  • ${API_TOKEN}
Example Response
{
    "format": "v3",
    "creative": {
        "account": "Blue River Real Estate",
        "campaign_hash_id": "lch-4CPh",
        "campaign_lcuid": "LCUID-LE-c6ff8717-5e7a-4afd-b6a9-d8f05b59953d",
        "campaign_build_id": "866",
        "board_identifier": "1234-SF",
        "board_lcuid": "LCUID-LB-e2eeac8a-82af-4be2-9688-448e39c0fd08",
        "board_name": "North Washington St, SF",
        "lucit_digital_board_id": "21974",
        "item_count": "10",
        "item_selected_index": "9",
        "creative_name": "Some Item 9",
        "creative_slug": "some_item_9",
        "creative_id": "C1-4CPh-LP-4D2Z",
        "play_duration": 0,
        "id": "3443",
        "lcuid": "LCUID-LP-782ffcc9-fd8f-4bc9-a23a-9fb3e791983f",
        "approval_status": "0",
        "src": "http://localhost:8080/storage/13/3303/img_695da4985bed2_d206fa68717f3906bd43.png",
        "hash": "bd041677a6d1a9c776a4f6edbc0ecedb",
        "hash_algo": "md5",
        "width": "1024",
        "height": "768",
        "creative_datetime": "2026-01-07T00:11:04+00:00",
        "pingback_url": "http://localhost:8080/api/v1/analytics/track/lucit-drive-play?creative_id=C1-4CPh-LP-4D2Z&lucit_layout_digital_board_id=21974&play_datetime=${PLAY_DATETIME_UTC}&play_duration=${PLAY_DURATION_SECONDS}&api_token=${API_TOKEN}"
    }
}

Example Implementations

Bash (cURL)

curl --request GET \
  --url "https://api.lucit.app/api/v3/campaigns/{lcuid}/pull/{boardIdentifier}" \
  --header "Authorization: Bearer {AuthToken}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "AppIdV3: LCUID-LAP-********-****-****-****-************"

JavaScript (Fetch API)

const url = "https://api.lucit.app/api/v3/campaigns/{lcuid}/pull/{boardIdentifier}";

const headers = {
  "Authorization": "Bearer {AuthToken}",
  "Content-Type": "application/json",
  "Accept": "application/json",
  "AppIdV3": "LCUID-LAP-********-****-****-****-************"
};

fetch(url, {
  method: "GET",
  headers: headers
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

PHP (Guzzle)

<?php

require_once 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.lucit.app/api/v3/campaigns/{lcuid}/pull/{boardIdentifier}', [
  'headers' => [
    'Authorization' => 'Bearer {AuthToken}',
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'AppIdV3' => 'LCUID-LAP-********-****-****-****-************',
  ]
]);

$body = $response->getBody();
$data = json_decode($body, true);
print_r($data);

Python (Requests)

import requests
import json

url = "https://api.lucit.app/api/v3/campaigns/{lcuid}/pull/{boardIdentifier}"

headers = {
  "Authorization": "Bearer {AuthToken}",
  "Content-Type": "application/json",
  "Accept": "application/json",
  "AppIdV3": "LCUID-LAP-********-****-****-****-************"
}

response = requests.get(url, headers=headers)
print(response.json())

← Back to campaigns index | Back to main index