NAV Navbar
cURL
  • REST API Reference
  • Authentication
  • Rate Limiting
  • Versioning
  • Error Codes
  • Store-Pages API
  • REST API Reference

    API Endpoint:

    http://api.precisetarget.com/v1
    

    The PreciseTarget API was designed to surface customized online retail stores and products created by PreciseTarget's deal engine to end users. The API uses HTTP methods and is organized with a RESTful endpoint structure. Requests are formatted in JSON, and the API returns JSON-encoded objects for all routes, including errors.

    Authentication

    To authenticate, pass an api-key header with each request using the -H option:

    # Replace `abcdefgh-1234-5678-9012-ijklmnopqrst` with your personal API key.
    curl "http://api.precisetarget.com/v1" \
      -H "api-key: abcdefgh-1234-5678-9012-ijklmnopqrst"
    

    The PreciseTarget API uses API keys to authenticate all requests. Users can request PreciseTarget API keys by contacting an administrator.

    The API expects the API key to be included in all requests to the server, using an api-key header. Any unauthenticated requests will return an HTTP 400 response.

    Rate Limiting

    Users can make up to 300 requests per minute to each API. Check the HTTP headers of any API request to see your current rate limit status. If you think you will need a higher rate limit, feel free to contact us.

    Versioning

    All PreciseTarget APIs operate under Version 1.0. Versioning is included in the endpoint path. Debugging and minor feature improvements to an endpoint may be made without a change to the version number, and would not be reflected in the endpoint's path.

    Error Codes

    The PreciseTarget API uses the following error codes:

    Error Code Meaning
    400 Bad Request / Invalid API Key
    404 Not Found
    500 Internal Server Error

    Store-Pages API

    PreciseTarget offers a variety of cultivated online retail stores, created using different combinations of retailers and brands, called store-pages. Store-pages allow customers to easily find and purchase retail products that are on sale.

    The Store-Pages API allows users to access the PreciseTarget store-pages. The Store-Pages API is currently under limited release.

    Store Route

    Example Request:

    # Replace `abcdefgh-1234-5678-9012-ijklmnopqrst` with your personal API key
    curl "http://api.precisetarget.com/v1/store-pages/apipublisher/exampleapistore" \
      -H "api-key: abcdefgh-1234-5678-9012-ijklmnopqrst"
    

    Example Response:

    {
        "branding": {
            "backUrl": "https://www.google.com/",
            "logoUrl": "",
            "name": "Example Store",
            "powered_by": false,
            "tagLine": "Your store here"
        },
        "header_categories": [
            {
                "count": 6970,
                "id": "Products/Women's",
                "label": "Women's",
                "leaves": [
                    {
                        "count": 10,
                        "id": "Products/Women's/Clothing",
                        "label": "Clothing"
                    },
                    {
                        "count": 2,
                        "id": "Products/Women's/Shoes",
                        "label": "Shoes"
                    },
                    {
                        "count": 98,
                        "id": "Products/Women's/Bags",
                        "label": "Bags"
                    },
                    {
                        "count": 6860,
                        "id": "Products/Women's/Jewelry",
                        "label": "Jewelry"
                    }
                ]
            },
            {
                "count": 2,
                "id": "Products/Beauty",
                "label": "Beauty",
                "leaves": [
                    {
                        "count": 2,
                        "id": "Products/Beauty/Fragrance",
                        "label": "Fragrance"
                    }
                ]
            },
            {
                "count": 6,
                "id": "Products/Kids' & Baby",
                "label": "Kids' & Baby",
                "leaves": []
            },
            {
                "count": 13,
                "id": "Products/Home",
                "label": "Home",
                "leaves": [
                    {
                        "count": 1,
                        "id": "Products/Home/Furniture & Décor",
                        "label": "Furniture & Décor"
                    },
                    {
                        "count": 12,
                        "id": "Products/Home/Kitchen & Dining",
                        "label": "Kitchen & Dining"
                    }
                ]
            }
        ],
        "id": "534db18285163bdf26dd1d583f9c6c70",
        "product_count": 6991,
        "publisher": {
            "branding": {
                "copyright": "© 2017 PreciseTarget. All rights reserved.",
                "home": "https://www.google.com/",
                "logoUrls": {
                    "mono": "https://s3.amazonaws.com/assets.precisetarget.com/logos/api_publisher_logo.png",
                    "normal": "https://s3.amazonaws.com/assets.precisetarget.com/logos/api_publisher_logo_colored.png"
                },
                "privacyPolicy": "",
                "style": {
                    "colors": {
                        "accent": "#007488",
                        "link": "#5a0027",
                        "sale": "#FF1F4E"
                    }
                },
                "termsOfUse": ""
            },
            "id": "1ad8c1d79dcf57cdee3426c70128bd60",
            "name": "API Publisher",
            "stem": "apipublisher"
        },
        "stem": "exampleapistore"
    }
    

    The Store-Pages API store route accepts a publisher and store-page name, and returns metadata of the requested store-page for the publisher.

    HTTP Request

    GET http://api.precisetarget.com/v1/store-pages/{publisher-name}/{store-name}

    HTTP Response

    STORE-PAGE

    Attribute Type Description
    branding object An object containing store-level branding details
    header_categories array of objects An object containing the top-level categories for the store-page
    publisher object An object containing metadata for the publisher of the store-page (see Publisher sub-object)
    id string The ID of the store-page
    stem string A 'slug' value for the store-page which is used in URLs
    product_count number The total number of products in the store

    BRANDING

    The branding sub-object holds store-level branding detail.

    Attribute Type Description
    backUrl string A link that can be used to navigate to the referring page
    logoUrl string A link to a logo for the store
    name string A name for the store
    tagLine string A tag line describing the store
    powered_by boolean True if PreciseTarget is the store publisher; False otherwise

    HEADER CATEGORIES

    The header_categories sub-object holds an array of top-level categories and their children, which can be used to render a menu UI. Each header_categories sub-object has the following attributes:

    Attribute Type Description
    id string The ID of the top-level category
    label string The label of the top-level category
    count number The total number of products in the top-level category
    leaves array of objects An array of category objects which are the immediate children of this category

    PUBLISHER

    Each publisher sub-object has the following attributes:

    Attribute Type Description
    id string The ID of the publisher
    name string The name of the publisher
    stem string A 'slug' value for the publisher which is used in URLs
    branding object A sub-object holding branding details (see Publisher Branding below)

    PUBLISHER.BRANDING

    Each publisher.branding sub-object has the following attributes:

    Attribute Type Description
    home string A link that can be used to navigate to the publisher's home page
    logoUrls object Links to the publisher logo in monochrome and color
    style.colors object The branded colors of the publisher
    copyright string The publisher-specific copyright policy
    privacyPolicy string The publisher-specific privacy policy
    termsOfUse string The publisher-specific terms of use

    RESPONSE TYPES

    Code Description
    200 Response Successful
    400 Bad Request / Invalid API Key
    404 Publisher or Store Not Found
    500 Internal Server Error

    Facets Route

    Example Request:

    # Replace `abcdefgh-1234-5678-9012-ijklmnopqrst` with your personal API key
    curl "http://api.precisetarget.com/v1/store-pages/ \
          apipublisher/exampleapistore/facets?c=Products%2FWomen%27s%2FClothing" \
      -H "api-key: abcdefgh-1234-5678-9012-ijklmnopqrst"
    

    Example Response:

    {
        "filters": {
            "categories": {
                "ancestors": [
                    {
                        "count": 6970,
                        "id": "Products/Women's",
                        "isSelected": false,
                        "label": "Women's"
                    },
                    {
                        "count": 10,
                        "id": "Products/Women's/Clothing",
                        "isSelected": true,
                        "label": "Clothing"
                    }
                ],
                "leaves": [
                    {
                        "count": 10,
                        "id": "Products/Women's/Clothing/Tops & Tees",
                        "isSelected": false,
                        "label": "Tops & Tees"
                    }
                ]
            },
            "colors": [
                {
                    "count": 3,
                    "hex": "#000000",
                    "id": "col013blck",
                    "isSelected": false,
                    "label": "Black"
                },
                {
                    "count": 1,
                    "hex": "#0191EC",
                    "id": "col005blue",
                    "isSelected": false,
                    "label": "Blue"
                },
                {
                    "count": 1,
                    "hex": "#F933D6",
                    "id": "col007pink",
                    "isSelected": false,
                    "label": "Pink"
                },
                {
                    "count": 1,
                    "hex": "#980AFC",
                    "id": "col006purp",
                    "isSelected": false,
                    "label": "Purple"
                },
                {
                    "count": 1,
                    "hex": "#D80303",
                    "id": "col001red",
                    "isSelected": false,
                    "label": "Red"
                },
                {
                    "count": 1,
                    "hex": "#FFFFFF",
                    "id": "col010whit",
                    "isSelected": false,
                    "label": "White"
                },
                {
                    "count": 1,
                    "hex": "#FCE204",
                    "id": "col003yell",
                    "isSelected": false,
                    "label": "Yellow"
                }
            ],
            "sizes": [
                {
                    "count": 39,
                    "label": "Standard",
                    "regions": [
                        {
                            "count": 39,
                            "facets": [
                                {
                                    "count": 10,
                                    "id": "STD_US_3000_Standard_US_S",
                                    "isSelected": false,
                                    "label": "S"
                                },
                                {
                                    "count": 10,
                                    "id": "STD_US_4000_Standard_US_M",
                                    "isSelected": false,
                                    "label": "M"
                                },
                                {
                                    "count": 10,
                                    "id": "STD_US_5000_Standard_US_L",
                                    "isSelected": false,
                                    "label": "L"
                                },
                                {
                                    "count": 9,
                                    "id": "STD_US_6000_Standard_US_XL",
                                    "isSelected": false,
                                    "label": "XL"
                                }
                            ],
                            "label": "US"
                        }
                    ]
                }
            ]
        },
        "maxDiscount": {
            "boundary": 0,
            "isSelected": false,
            "label": 0
        },
        "maxPrice": {
            "boundary": 3000,
            "isSelected": false,
            "label": 3000
        },
        "minDiscount": {
            "boundary": 0,
            "isSelected": false,
            "label": 0
        },
        "minPrice": {
            "boundary": 1500,
            "isSelected": false,
            "label": 1500
        },
        "onSale": {
            "count": 0,
            "isRequiredByStore": false,
            "isSelected": false
        },
        "q": "",
        "sort": [
            {
                "id": "relevance",
                "isSelected": false,
                "label": "Relevance"
            },
            {
                "id": "price_low_to_high",
                "isSelected": false,
                "label": "Price (Low to High)"
            },
            {
                "id": "price_high_to_low",
                "isSelected": false,
                "label": "Price (High to Low)"
            },
            {
                "id": "popularity",
                "isSelected": true,
                "label": "Popularity"
            },
            {
                "id": "super_sales",
                "isSelected": false,
                "label": "Super Sales"
            }
        ],
        "total": 10
    }
    

    The Store-Pages API facets route accepts store-page filters and returns the metadata of the set of products that surface when the filters are applied to the store-page.

    HTTP Request

    GET http://api.precisetarget.com/v1/store-pages/{publisher-name}/{store-name}/facets

    HTTP Response

    FACETS

    The facet response has the following attributes:

    Attribute Type Description
    filters object The filters object holds the state of the filters used to generate the facet metadata (see Filters object)
    maxDiscount object The price filter sub-object for the maximum discount percent (see Price Filtering)
    maxPrice object The price filter sub-object for the minimum price, including sale price (see Price Filtering)
    minDiscount object The price filter sub-object for the minimum discount percent (see Price Filtering)
    minPrice object The price filter sub-object for the minimum price, including sale price (see Price Filtering)
    onSale object Any free text search query params used to generate the facet set
    q string Any free text search query params used to generate the facet set
    sort array of objects An array of sort ordering sub-objects available for products (see Orders sub-object)
    total number The total number of products in the facet set

    FILTERS

    The filters attribute holds the different types of filters used to generate the facet metadata, and have the following attributes:

    Attribute Type Description
    brands array of objects An array of brands sub-objects to filter by
    categories.ancestors array of objects An array of ancestor categories sub-objects to filter by
    categories.leaves array of objects An array of children categories sub-objects to filter by
    colors array of objects An array of color sub-objects to filter by
    merchants array of objects An array of merchant sub-objects to filter by
    sizes array of objects An array of size sub-objects to filter by

    PRICE FILTERING

    The maxDiscount, maxPrice, minDiscount, and minPrice objects each have the following attributes:

    Attribute Type Description
    boundary number The outer limit of the price filter
    isSelected boolean True if there is an enforced price filter; False otherwise
    label number The currently enforced filter value, if isSelected is True; the value for boundary otherwise

    ORDERS

    The sort attribute holds the types of sorting available for the surfaced products. Each sort type is an order sub-object with the following attributes:

    Attribute Type Description
    id string The ID of the sort order
    isSelected boolean True if this sort order is selected; False otherwise
    label number The label of the sort order

    Response Codes

    Code Description
    200 Response Successful
    400 Bad Request / Invalid API Key
    404 Publisher or Store Not Found
    500 Internal Server Error

    Products Route

    Example Request:

    # Replace `abcdefgh-1234-5678-9012-ijklmnopqrst` with your personal API key
    curl "http://api.precisetarget.com/v1/store-pages/apipublisher/exampleapistore/products" \
      -H "api-key: abcdefgh-1234-5678-9012-ijklmnopqrst"
    

    Example Response:

    {
        "data": [
            {
                "brand": "Macy's",
                "buyUrl": "http://products.precisetarget.com/eyJsaW5rIjoiaHR0cDovL2NsaWNrLmxpbmtzeW5lcmd5LmNvbS9saW5rP2lkPUo3Zm91VWU2QWlFJm9mZmVyaWQ9NDg2MTA5Ljk2MzAzMTg0NjkxJnR5cGU9MTUmbXVybD1odHRwcyUzQSUyRiUyRnd3dy5tYWN5cy5jb20lMkZzaG9wJTJGcHJvZHVjdCUyRnN3YXJvdnNraS16aXJjb25pYS1yb3VuZC1zdHVkLWVhcnJpbmdzLWluLTE0ay1nb2xkLTItY3QuLXQudy4lM0ZJRCUzRDE0Njk0ODQlMjZQYXJ0bmVySUQlM0RMSU5LU0hBUkUlMjZjbV9tbWMlM0RMSU5LU0hBUkUtXy0xLV8tMzUtXy1NUDEzNSZVMT1QVFNJRE1ENUgwYTZjMjkwY2UwZTUzMWY4YTRjOWY0MzI0YjcxZTJiMyJ9",
                "id": "4fc33fc11e815c1d0f966f3ec9fae406",
                "imageUrl": "https://slimages.macysassets.com/is/image/MCY/products/0/optimized/2091250_fpx.tif?wid=300&fmt=jpeg&qlt=100",
                "name": "Swarovski Zirconia Round Stud Earrings in 14k (2 ct. t.w.)",
                "onSale": false,
                "price": 10000,
                "salePrice": null
            },
            {
                "brand": "Macy's",
                "buyUrl": "http://products.precisetarget.com/eyJsaW5rIjoiaHR0cDovL2NsaWNrLmxpbmtzeW5lcmd5LmNvbS9saW5rP2lkPUo3Zm91VWU2QWlFJm9mZmVyaWQ9NDg2MTA5LjYzMDM2NTEyMjcxMiZ0eXBlPTE1Jm11cmw9aHR0cHMlM0ElMkYlMkZ3d3cubWFjeXMuY29tJTJGc2hvcCUyRnByb2R1Y3QlMkZtZW5zLWRpYW1vbmQtc3F1YXJlLWNsdXN0ZXItc3R1ZC1lYXJyaW5ncy0zLTQtY3QuLXQudy4taW4tc3Rlcmxpbmctc2lsdmVyJTNGSUQlM0QzNzQ5MTQ2JTI2UGFydG5lcklEJTNETElOS1NIQVJFJTI2Y21fbW1jJTNETElOS1NIQVJFLV8tMS1fLTM1LV8tTVAxMzUmVTE9UFRTSURNRDVIMGE2YzI5MGNlMGU1MzFmOGE0YzlmNDMyNGI3MWUyYjMifQ",
                "id": "81c7385350f6ccd40b0068c31ac36d76",
                "imageUrl": "https://slimages.macysassets.com/is/image/MCY/products/0/optimized/8225660_fpx.tif?wid=300&fmt=jpeg&qlt=100",
                "name": "Diamond Square Cluster Stud Earrings (3/4 ct. t.w.) in Sterling",
                "onSale": false,
                "price": 150000,
                "salePrice": null
            },
            "...": "..."
        ],
        "limit": 10,
        "offset": 0,
        "total": 6991
    }
    

    The Store-Pages API products route accepts a publisher and store-page name, and returns the products that surface in the requested store-page for the publisher.

    HTTP Request

    GET http://api.precisetarget.com/v1/store-pages/{publisher-name}/{store-name}/products

    HTTP Response

    PRODUCTS

    The products response has the following attributes:

    Attribute Type Description
    data array of objects An array of all products in the requested store-page (see Product object)
    limit number The number of products to return
    offset number The starting number of products to count from
    total number The total number of products in the facet set

    PRODUCT

    Each product sub-object has the following attributes:

    Attribute Type Description
    total number The total number of products in the facet set
    brand string The brand of the product
    buyUrl string The URL link to merchant site
    id string The unique ID of the product
    imageUrl string The URL link to product image
    name string The name of the product
    onSale boolean True if the product is on sale; False otherwise
    price int The original price in cents (ex. 3999 -> $39.99)
    salePrice int The sale price in cents (ex. 3999 -> $39.99)

    RESPONSE TYPES

    Code Description
    200 Response Successful
    400 Bad Request / Invalid API Key
    404 Publisher or Store Not Found
    500 Internal Server Error

    Recommendations Route

    Example Request:

    # Replace `abcdefgh-1234-5678-9012-ijklmnopqrst` with your personal API key
    curl "http://api.precisetarget.com/v1/store-pages/ \
          apipublisher/exampleapistore/recommendations/6b6162ab1ac9c8e584e432dd292abf57" \
      -H "api-key: abcdefgh-1234-5678-9012-ijklmnopqrst"
    

    Example Response:

    [
      {
        "store_url":"http://offers.network/test_publisher/macys?p1=3000",
        "products": [
          {
            "id": "37a6848904dc82fae7e66083ea439c12",
            "name": "Style & Co Petite Performance Jeans",
            "onSale": true,
            "price": 5950,
            "salePrice": 2999,
            "imageUrl": "https://slimages.macysassets.com/is/image/MCY/products/0/optimized/3860180_fpx.tif",
            "brand": "Style & Co",
            "buyUrl": "https://www.macys.com/shop/product/tommy-hilfiger-frank-slip-on-sneakers"
          },
          {
            "id": "7d13dfb1a9be7b378a84566cf9b8bfe2",
            "name": "Calvin Klein Jupa Lace-Up Platform Flats",
            "onSale": true,
            "price": 199.00,
            "salePrice": 71.40,
            "imageUrl": "https://slimages.macysassets.com/is/image/MCY/products/8/optimized/8468779_fpx.tif",
            "brand": "Calvin Klein",
            "buyUrl": "https://www.macys.com/shop/product/calvin-klein-womens-jupa-lace-up-platform-flats"
          },
          "...": "..."
        ]
      }
    ]
    

    The Store-Pages API Recommendations route allows access to targeted store-page filters and products using PreciseTarget's proprietary recommendation engine. The route returns filters for the selected store-page, along with up to five products from within those recommended filters. Requests must include an MD5-hashed email address, publisher name, and store-page name.

    The targeted product and store-page recommendations span a wide variety of retailers, and are generated by processing an incoming hashed email and retailer name through PreciseTarget's proprietary targeting engine.

    HTTP Request

    GET http://api.precisetarget.com/v1/store-pages/{publisher-name}/{store-name}/recommendations/{email-hash}

    HTTP Response

    RECOMMENDATION

    The recommendation response has the following attributes:

    Attributes Type Description
    store_url string The link to a custom store-page recommended for the user
    products array of objects An array of up to five products from the recommended store-page

    PRODUCT

    Each product sub-object has the following attributes:

    Attributes Type Description
    id string The unique ID of the product
    name string The name of the product
    onSale boolean True if the product is on sale; False otherwise
    price int The original price of the product, in cents (ex. 3999 -> $39.99)
    salePrice int The sale price of the product, in cents (ex. 3999 -> $39.99)
    imageUrl string The URL link to the product image
    brand string The brand of the product
    buyUrl string The URL link to the product on the merchant's website

    RESPONSE TYPES

    Code Description
    200 Recommendation Successful
    400 Bad Request / Invalid API Key
    404 Publisher or Store Not Found
    500 Internal Server Error