Many data requests will need to specify some common attributes. Here is a list of attributes that may or may not apply to various requests. It is recommended that all parameters be specified so that changes to default values do not change future results.

All data requests sent to the Placewise API require three fields: a timestamp, the requester’s account id or email, and a hash of the timestamp and the authentication_token retrieved from the accounts/login endpoint (see below).

To initiate a session, POST your email and your password to /accounts/login, formatted in JSON:

    {
      "data": {
        "type": "accounts",
        "attributes": {
          "email": "example@email.com",
          "password": "foobarbaz"
        }
      }
    }
  

If the credentials are valid, the data returned will include an authentication_token. This token should be stored locally so that successive requests can incorporate it.

    {
      "data": {
        "id": 1,
        "type": "accounts",
        "attributes": {
          "email": "example@email.com",
          "authentication_token": "c5Do0Qmas7sY42_PysZf"
        }
      }
    }
  

Once you have your authentication_token, you can mint an auth_token on each subsequent request. The auth_token is an MD5 hash of the current timestamp (ten digits, UTC Unix timestamp) concatenated with a colon and the authentication_token for the session.

md5(timestamp + ":" + authentication_token)

For example:

md5("1414677461:c5Do0Qmas7sY42_PysZf")

Resulting in:

d702c5a012d4db205f070d830ce2e9e1

The final request will include something like:

?auth_id=456789&auth_token=0c428b4c3f0e808d0a7d9973c07f9b99&auth_timestamp=1431975251

Note:

• The timestamp helps protect against anyone intercepting the request and re-playing it.
• The timestamp must be accurate. It must be within several seconds of UTC. A handy site to see the current Unix epoch time is www.epochconverter.com.
• The timestamp of every request will be different, and therefore so will the auth_token. It must be re-hashed for each data request.
• If more than one system makes valid login requests using the same account credentials, they will all get the same authentication_token. If one of those systems logs out, all the sessions will be ended, and a new authentication_token will need to be requested from accounts/login.
• Any request that is missing any of these fields, or has a timestamp that is too old, or has a malformed auth_token will receive a 401 Unauthorized.

For more information and examples, see the accounts documentation.

Most of the Placewise API endpoints offer associated images. In order to sideload a model that has associated images, use the

include=images

query parameter in your request.

Sample response:

GET /deals/123456

{
  "data": {
    "id": "123456",
    "type": "deals",
    "attributes": {
      ...
    },
    "relationships": {
      "images": {
        "links": {
          "self": "https://api.placewise.com/deals/123456/relationships/images",
          "related": "https://api.placewise.com/deals/123456/images"
        },
        "data": [
          {
            "type": "images",
            "id": "654321"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "654321",
      "type": "images",
      "attributes": {
        "url": "https://bass.shoptopia.com/mcache/{size}/sales/1234/imagename.jpg",
        "size_parameter": "{size}",
        "created_at": "2024-09-28T21:45:57Z",
        "updated_at": "2024-09-28T21:45:57Z"
      }
    }
  ]
}

Some records may return an empty array for the resource's images property. This is normal, and means that the record has no images associated with it.

The URL provided will have a token parameter, whose format is provided with the request in the "size_parameter" field. The that token must be replaced within the URL. Acceptable image size formats are:

• widthxheight (width and height), e.g. 100x100
• width (width only), e.g. 100

Dates are in ISO8601, UTC, format: YYYY-MM-DDTHH:mm:ss.SSSZ

Date Ranges

Resources can be filtered by specifying a date range using the following query parameter:

?filter[updated_at][lte]=2016-04-01

Valid parameters include less than (lt), less than or equal to (lte), greater than (gt), and greater than or equal to (gte). This type of filtering can be done on any date field, including updated_at and created_at. Dates are formatted in ISO 8601, UTC:

YYYY-MM-DDTHH:mm:ss.SSSZ

Dates can also be abbreviated to:

YYYY-MM-DD

The API uses two kinds of timestamps, UTC or relative.

Absolute Time

UTC timestamps, such as created_at, are formatted in ISO 8601 with the time zone designator Z:

2024-09-28T21:45:57Z

Relative Time

Relative timestamps, such as start_at, are formatted in ISO 8601 with no time zone designator:

2024-09-28 15:45:57

Webhooks will proactively alert your system whenever an event, such as a deletion or update happens, letting you keep your data as accurate as possible. Allowing for differential update requests to be made to the API resulting in faster requests for everyone.

At the most basic level, webhooks are POST requests sent out by our API to your server to notify you of an event such as an update or a deletion. To receive webhooks you will need to have a server with a publicly accessible endpoint that will respond to the incoming webhook with a successful HTTP status code (2XX). The following steps describe how to subscribe to webhook notifications for a specific resource and what to expect from an incoming request.

How to Subscribe

To subscribe to webhooks for a particular topic, send a POST request to https://api.placewise.com/webhooks with the following payload. The callback_url and topic attributes will be unique to your application's needs. For example, if you wanted to be sent notifications of any changes to articles at https://api.yoururl.com/webhooks.

    {
      "data": {
        "type": "webhooks",
        "attributes": {
          "callback_url": "https://api.yoururl.com/webhooks",
          "topic": "articles"
        }
      }
    }
  

Once you are subscribed to a topic, you will receive notifications about that topic when there is new activity. For example, when an article is updated or created, a POST request will be sent to the provided callback_url with the following data:

    {
      "data": [
        {
          "type": "updates",
          "attributes": {
            "resource_type": "articles",
            "resource_id": 5
          }
        },
        {
          "type": "deletions",
          "id": 10
          "attributes": {
            "resource_type": "articles",
            "resource_id": 8
          }
        }
      ]
    }
  

Responding to a Webhook

Your server must respond to the incoming POST request with an HTTP status code in the success range (2XX) to keep the subscription alive. The Placewise API will attempt to send a notification up to 5 times before the topic is automatically unsubscribed.

Mulitple Updates

Multiple events will be batched together in a single notification if they occur close together. When this happens, the payload will be an array of data objects with each resource_type and resource_id specified.

In order to see a list of your webhook subscriptions, send a GET request to /webhooks.

How to Unsubscribe

To unsubscribe from a webhook, send a DELETE request with the webhook ID.

In order to ensure the highest request performance, it is important to use the filter parameters to limit your requests to only include changes made since your last request. For example, to pull deals that have been created or updated in the last hour, include the following query parameter in your request.

https://api.placewise.com/mall/1066/deals?filter[updated_at][gte]=2024-09-28 20:45:57

There are two strategies that Placewise recommends for accessing data through the API. By using these strategies, we can ensure the fastest responses possible for all users of the API.

Event Driven Strategy

The Event Driven Strategy relies heavily on the usage of webhooks. By using this strategy, API requests are only made when data is created or updated. Consider the following scenario: As a Deal Channel client, I want to receive webhook notifications for all deals that are relevant to my mall. The steps needed to implement this strategy are as follows:

1. Setup a webhook with topic: 'deals'
2. A deal is created or updated and a notification is then sent to your server with the deal ID
3. Make a request to the API filtering by ID (or multiple IDs if there were multiple creations/updates)

   https://api.placewise.com/deals?filter[id]=12,13,14

   This request will only get deals 12, 13, and 14 from the API.
4. If a deal is deleted, your server will be notified, and you can delete your copy of the data locally.

Whenever a deal is created or updated, a notification will be sent to my server with the ID of the deal or deals. With these ID's, I can then make a request to the Placewise API requesting the attributes for the created or updated deals.

Scheduled Requeset Strategy

The Scheduled Request Strategy relies heavliy on the usage of Differential Updates and the deletions feed. Consider the following scenario: as a Deal Channel client, I want to make a request to the Placewise API every 2 hours to keep my deal feed up to date. The steps needed to implement this strategy are as follows:

1. Make a request to the deletions feed to see what deals have been deleted

   https://api.placewise.com/deletions?filter[resource_type]=deals

2. Delete the locally stored deals with this information
3. Pull deals that have been created or updated in the last 2 hours:

   https://api.placewise.com/deals?filter[updated_at][gte]=2024-09-28 19:45:57