Planogram Submission API

To let retailers make planogram submissions, you can implement the Planogram Submission API on whichever digital touchpoint they already use, whether that's your own mobile app, your website, or a third-party field survey tool.

Making a submission takes three calls: create the case, upload the shelf image as an attachment, then submit the assignment with the attachment attached. We'll walk through each below.

All requests are made against your Planogram Compliance environment's base URL, for example:

https://<your-instance>.app.fielo.com/dx/api/application/v2

Each call requires a valid Authorization: Bearer <ACCESS_TOKEN> header.

Step 1: Create the case

Every planogram submission starts its life as a case. Creating one kicks off the PlanogramSubmissionWorkflow and opens the first assignment, where the shelf image will be collected.

curl 'https://<your-instance>.app.fielo.com/dx/api/application/v2/cases' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "caseTypeID": "PlanogramSubmissionWorkflow",
    "content": {
      "MemberExternalID": "94672281-8145-af2b-6bca-1c72faf6278c",
      "StoreExternalID": "ratadeep",
      "Planogram": {
        "ID": "STE6UGxhbm9ncmFtQ29tcGxpYW5jZV9fUGxhbm9ncmFtRGVmaW5pdGlvbkRhdGFfNmE3OWRhZWVhMjRlZDhjNjUyMGZiYTk4"
      }
    }
  }'

• caseTypeID: Always PlanogramSubmissionWorkflow for a planogram submission.
• MemberExternalID: The external ID of the member submitting on behalf of the store.
• StoreExternalID: The storeExternalId of the retail outlet making the submission, as set when the retail outlet was registered.
• Planogram.ID: The ID of the planogram definition being submitted against. Only submissions for the outlet's own retail segment are accepted.

The response includes the new case's ID — this is the case ID you'll use as the contextID in the next step — along with nextAssignmentInfo.ID, the assignment ID you'll submit against in Step 3.

Step 2: Upload the shelf image

With the case created, upload the shelf image as an attachment against it. This is a separate call from the case submission itself; the upload just returns a temporary attachment ID that you'll bind to the case in the next step.

curl 'https://<your-instance>.app.fielo.com/dx/api/application/v2/attachments/upload' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  --data-raw $'------WebKitFormBoundary7MA4YWxkTrZu0gW\r\nContent-Disposition: form-data; name="appendUniqueIdToFileName"\r\n\r\ntrue\r\n------WebKitFormBoundary7MA4YWxkTrZu0gW\r\nContent-Disposition: form-data; name="file"; filename="ideal-coca-cola-bottles.png"\r\nContent-Type: image/png\r\n\r\n<BINARY_FILE_CONTENT>\r\n------WebKitFormBoundary7MA4YWxkTrZu0gW\r\nContent-Disposition: form-data; name="contextID"\r\n\r\n<CASE_ID>\r\n------WebKitFormBoundary7MA4YWxkTrZu0gW--\r\n'

• appendUniqueIdToFileName: Set to true so the uploaded file doesn't collide with another submission using the same filename.
• file: The shelf image itself, as binary form data.
• contextID: The case ID returned in Step 1.

The response returns the attachment's temporary ID:

{
  "ID": "STE6UGVnYVBsYXRmb3JtX19BdHRhY2htZW50XzZhODQzYTRiZDVhYzlhYzdhODhkYTY1ZA"
}

Hang on to this — it's what you'll reference as ShelfImages when submitting the assignment.

Step 3: Submit the assignment

Finally, submit the CollectShelfImageAndData assignment (its ID came from nextAssignmentInfo in Step 1) with the attachment ID bound to ShelfImages.

curl 'https://<your-instance>.app.fielo.com/dx/api/application/v2/assignments/<ASSIGNMENT_ID>/actions/CollectShelfImageAndData?viewType=page&outcome=Submit' \
  -X 'PATCH' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: w/"1"' \
  --data-raw '{
    "content": {
      "ShelfImages": [
        { "ID": "<ATTACHMENT_ID>" }
      ]
    },
    "pageInstructions": []
  }'

• ASSIGNMENT_ID in the URL: The assignment ID from nextAssignmentInfo.ID in Step 1.
• If-Match: The assignment's current eTag. Fetch this beforehand with GET /assignments/{assignmentID}?viewType=form.
• ShelfImages: An array containing the attachment ID from Step 2.

Once submitted, the case moves through its remaining stages automatically:

You don't need to make any further calls — the shelf image is picked up and scored automatically, and the results are available as described in Planogram Submission Feedback.