Create a List

Creates a new List with the given name and attributes.

This document describes for creating a new list for a shopper

Endpointrequest typeAPI Type
https://{{Swym API Endpoint }}/api/v3/lists/createPOSTshopper


user-agentYesUser-Agent header of the app used to access the API

Query Params

pidstring (Encoded)YesUnique identifier for the store available in Swym Admin
limitint64NoMaximum number of records to return
offsetint64NoNumber of records to skip

Form Data

lnamestringYesUnique name of the list to create
regidstringYesUnique identifier for the shopper generated by generate-regid
sessionidstringYesSession id generated with generate-regId endpoint which does not expire without manual intervention
lnotestringoptionalOptional note at list level
ltystringoptionalOptional list type
lpropsobjectoptionalList level object that can house custom properties
fromlidstringoptionalUnique identifier of the list to duplicate from
ldescstringoptionalList description

Example Curl

curl -X POST \
     --url '{{Swym API Endpoint }}/api/v3/lists/create?pid={{URL Encoded PID }}' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --header 'Accept: application/json' \
     --header 'user-agent: mobileApp' \
     --data-urlencode 'lname=My test list' \
     --data-urlencode 'sessionid={{sessionId}}' \
     --data-urlencode 'regid={{regid}}'


Curl Placeholders

Assuming these values are provided above, the curl command should work correctly. However, if there are any issues with the API endpoint or the data being passed in the request, there could still be errors that need to be resolved before you can test these APIS.

{{Swym API Endpoint}}This needs to be replaced with the actual Swym API endpoint URL.
{{URL Encoded PID}}This needs to be replaced with the actual PID value, URL-encoded.
{{regid}}This needs to be replaced with the actual regid value.
{{sessionid}}This needs to be replaced with the actual session ID value.
{{lid}}This needs to be replaced with the actual list ID value.

Success Response

The below responses are what you would get based on being logged in or an authenticated user.

    "di": "Z+/ywr3MW/NoY3W2jnNN5GRWUm9Ye/4/7DlUMYWCh60=-API", // Unique identifier for the device
    "userinfo": null, // User information associated with the list (not present in this example)
    "lty": "wl", // List type
    "cts": 1681110226853, // Creation timestamp (in milliseconds since epoch)
    "lname": "My test list", // List name
    "lid": "95cd0bcb-585f-436b-9141-dfa922ebf80c", // Unique identifier for the list.
    "pid": "1f0WvUYRaFyM6/cno5z1H2oAYI7tbUWbcGA1kY=", // Unique identifier for the store
    "st": 1, // List status (1 = active, 0 = inactive)
    "uts": 1681110226853, // Last update timestamp (in milliseconds since epoch)
    "lhash": "bXktdGVzdC1saXN0" // Base64-encoded hash of the list name and attributes

    "di": "91b43457-b092-46ca-bd6c-91ecc2f04dd5", // Unique Device Identifier tied to email
    "userinfo": {
        "sw_mkt": null, // Marketing Permissions True would mean subscribed.
        "uid": "uH7nZUNswsC6ejml9x7cZqDb1xgCMEqgds7jk+GIfrg=", user id 
        "em": "[email protected]", email address
        "cts": 1681408172605,
        "pid": "1f0WvUYRaFyM6/cno5z1H2oAYI7tbU76VY=", // Unique Merchant ID 
        "uts": 1681408172605, List created time stamp
        "acc_mkt": null, // Accept marketing - Same as sw_mkt however this is platform dependent 
        "prefs": null // user preferences. 
    "lty": "wl", // List type
    "uid": "uH7nZUNswsC6ejml9x7cZqDb1xgCMEqgds7jk+GIfrg=", // UID 
    "cts": 1681408180376, // List Created Time stamp 
    "lname": "My test list", // List name 
    "cby": "[email protected]", // Example email address 
    "lid": "f3c4a7bd-1fb7-4c85-8df9-73d1de186cfe", // List ID 
    "pid": "1f0WvUYRaFyM6/cno5z1H2oA1kY=", // Unique Merchant ID 
    "uts": 1681408180376, // User time stamp. 
    "_pkey": "uH7nZUNs",
    "uby": "[email protected]", // List created by email. 
    "cfor": "[email protected]" // List Created For Email

Error Response:

If the request is unsuccessful, the API will return a JSON response with an error message and an HTTP status code indicating the type of error that occurred.

Status CodeTypeDescription
400Bad RequestYour request is invalid, change your request params and query and try again.
401UnauthorisedYou are performing an action on a resource that is not granted to the current logged-in user. Additionally, for REST APIs, this could mean your API key is wrong.
403ForbiddenYou are not allowed to request this data.
404Not FoundThe specified requested data could not be found.
429Too Many RequestsYou're raising too many requests! Slow down!
500Internal Server Error --We had a problem with our server. Try again later.
503Service UnavailableWe're temporarily offline for maintenance. Please try again later.