Update Lists

Use Case Example - Steps to update lists using the Pick List API

This guide is designed for Claravine administrators and developers to be quickly set-up and enabled with the Pick List API for their account instance, to upload values to Pick Lists from an external source. While this example doesn’t go into each possibility, it will provide a foundation from where further development may be built upon.

Claravine API endpoints used in this use case:

• GET /v1/lists/ – Retrieve all Pick Lists in an account
• GET /v1/lists/{listId} – Export a specific Pick List
• POST /v1/lists/{listId} – Update a Pick List (non-powered lists only)

Workflow Overview

1. Find a Pick List ID
   1. Optionally, gather List IDs with GET /v1/lists/
   2. See List Pick Lists
2. Ensure that the script includes:
   1. Completed URL with List ID
   2. API Key and Secret
3. Edit Pick List values outside of Claravine (e.g., in Excel)
4. Attach the contents for the script to receive
5. Send the updated list back using POST /v1/lists/{listId}

Technical Solution

The following script takes the contents of Pick List values that are defined in an Excel document and uploads to a Claravine Pick List. Please be aware that UPLOAD will refresh the entire list contents.

• Ensure that you have installed the necessary libraries
• Define:
  • Excel file path
    • Optional: Sheet
  • Account API key and secret
  • Account URL and Pick List ID

Example Python Script

import requests
import json
import io
import pandas as pd


# === Configuration ===
excel_path = "file_path"
sheet_name = 0  # or the name of the sheet
url = "https://{your_account}.claravine.com/v1/lists/{your_listId}"
headers = {
   "accept": "application/json",
   "x-claravine-key": "your_key",
   "x-claravine-secret": "your_secret"
}
notes = "description_"


# === Read Excel ===
df = pd.read_excel(excel_path, sheet_name=sheet_name)


# === Create Contents ===
json_content = {
   "notes": notes,
   "headers": [{"name": col} for col in df.columns],
   "rows": [
       {
           "row_number": idx,
           "row_data": [{"value": str(cell) if pd.notna(cell) else ""} for cell in row]
       }
       for idx, row in df.iterrows()
   ]
}


# === Create in-memory JSON file ===
json_bytes = json.dumps(json_content).encode('utf-8')
file_obj = io.BytesIO(json_bytes)


files = {
   'file': ('updated_list.json', file_obj, 'application/json')
}


# === Send to Claravine ===
response = requests.post(url, headers=headers, files=files)


print(response.status_code)
print(response.text)