What API do I use to bulk create/update Picklists?

Purpose

This API is used to create or update picklists in bulk within the Joyn FSM system. Each picklist defines a set of selectable options, typically used in form fields. The API supports full upserts: every request fully defines all the options for a picklist, and existing options not present in the request will be removed.

Highlights

Bulk creation or update of picklists and their options
Schema validation and entity resolution
Full-load operation: all existing options for a picklist are replaced by the provided list
Options referenced by id in a map/object structure for fast lookupAPI Endpoint

API End point

v1/api/picklist/bulk

Method

POST

Request Format

=>Accepts an array of picklist objects.

=> Payload size should not exceed 6MB

=>Each picklist object must contain:

name (string) – The display name for the picklist (required).
options (object) – Key-value map of picklist options, where the key must match the id of the option object (required).

=>Each option object must define at least:

id (string) – Unique identifier for the option (required; should also be the key in options)
name (string) – The display label for the picklist value (required)
isActive (boolean) – Whether the option is active (required)

=>Other fields like fdgId, sortOrder, value, and description are optional

Getting Started

Authentication
The client must generate and provide a valid authentication token (Cognito authorizer required).
reference

Request Example

CODE

https://kxdo3f1sfb.execute-api.us-west-2.amazonaws.com/v1/api/picklist/bulk

Request Body

CODE

[
  {
    "name": "API test 2",
    "displayName":"API test 2",
    "options": {
      "APITEST2option1": {
        "id": "APITEST2option1",
        "name": "option1",
        "isActive": true,
        "sortOrder": 1
      },
      "APITEST2option2": {
        "id": "APITEST2option2",
        "name": "option2",
        "isActive": true,
        "sortOrder": 3
      }
    }
  },
 {
    "name": "API test 3",
    "displayName":"API test 3",
    "options": {
      "APITEST3option1": {
        "id": "APITEST3option1",
        "name": "option1",
        "isActive": true,
        "sortOrder": 1
      },
      "APITEST3option2": {
        "id": "APITEST3option2",
        "name": "option2",
        "isActive": true,
        "sortOrder": 2
      }
    }
  }
]

Response body Example

CODE

{
  "success": true,
  "message": "Processed 2 items, Failed to process 0 items",
  "output": {
    "processedItems": [
      {
        "message": "Item got created with id= ad8c92dd-43f1-4e00-b111-96e2cff9b967",
        "record": {
          "name": "API test 2",
          "displayName": "API test 2",
          "tenantId": "5c7910e8-0d88-4242-9fc9-5e7daa4f8516",
          "globalAttributes": {},
          "id": "ad8c92dd-43f1-4e00-b111-96e2cff9b967",
          "createdOn": "2025-12-17T13:50:40.888Z",
          "createdBy": "location.tracker2@yopmail.com",
          "modifiedOn": "2025-12-17T13:50:40.888Z",
          "modifiedBy": "location.tracker2@yopmail.com",
          "optionsString": "G7QAgCwP6LF5DXXDTp0snolM2LI8hl+L7M3E7CCytDmpw9LXUFNUb1qmKIlKici1jEgMXZ3cnb+dKWtRoJE2bxHGgYes1AdmqugJlE6K+0iGe5wGQPTFIExZ5X9fhG2n0KFMCfIP"
        }
      },
      {
        "message": "Item got created with id= 08f31384-5844-4261-8f3f-d164ba1ef973",
        "record": {
          "name": "API test 3",
          "displayName": "API test 3",
          "tenantId": "5c7910e8-0d88-4242-9fc9-5e7daa4f8516",
          "globalAttributes": {},
          "id": "08f31384-5844-4261-8f3f-d164ba1ef973",
          "createdOn": "2025-12-17T13:50:40.894Z",
          "createdBy": "location.tracker2@yopmail.com",
          "modifiedOn": "2025-12-17T13:50:40.894Z",
          "modifiedBy": "location.tracker2@yopmail.com",
          "optionsString": "G7QAgByHsdvkRNMMO5G3EkENj/zA+oCCwXgBTtI1K3VY+grqTSd3529nyloUaKTNW4Rx4CEr9YGZKnqGsHOd9BR3w1AX3MNpABDVF4MwZRX9/X0RNjuFjpSpBKUe"
        }
      }
    ],
    "unProcessedItems": []
  }
}

Full-Load Behavior

This API performs a full load:

The request payload replaces the entire picklist on the backend.
Any existing options not included in the request will be removed

Existing Picklist

Picklist: Certifications

Option 1: id = "A", name = "L1"
Option 2: id = "B", name = "L2"
Option 3: id = "C", name = "L3"

Full-load Request Example

CODE

[
  {
    "name": "Certifications",
    "options": {
      "B": {
        "id": "testB",
        "name": "L2",
        "isActive": true,
        "sortOrder": 1
      },
      "D": {
        "id": "D",
        "name": "L4",
        "isActive": true,
        "sortOrder": 2
      }
    }
  }
]

Result After Update

The picklist Certifications will contain:

L2 (id: B)
L4 (id: D)

Options L1 and L3 will be removed.

Error Handling

Our API uses standard HTTP status codes to indicate the success or failure of a request.

**Common Error Codes:** -

Code	Description
400 Bad Request	The request was invalid.
401 Unauthorized	Authentication failed.
404 Not Found	The requested resource was not found.
500 Internal Server Error	An error occurred on the server.

Error Response:
{"success":false,"message":"Some error message"}

Sample Validation Errors in API Failure

Error Message	Potential Issue	Solution
SchemaError : "name" is required	The `name` property is missing in the picklist object.	Include the `name` field for every picklist in your request.
SchemaError : "options" is required	The `options` property is missing in the picklist object.	Include a non-empty `options` object for the picklist.
SchemaError : option key must match id	The key in the options object does not match the `id` field inside that option.	Ensure each option key exactly matches its corresponding `id`.
ValidationError : option id “...” already exists	An option with the provided `id` already exists elsewhere (duplicate id).	Use a unique `id` for each option in all picklists.
Failed to process Items	Internal processing error	Check record format and retry
SchemaError : Picklist name already exists	Attempted to create a picklist with a name that already exists.	Picklist names must be unique; choose a new name or update.