Skip to content

Limited
Create folder

Request

Creates a folder in preparation, private until it is shared. Folders are flat (no hierarchy) and hold food-family specifications only. Specifications are placed in it via the create payload's folderId or the move endpoint while it is in preparation; sharing the folder (POST .../share) starts it and hands it over — after that its specification set is sealed.

Security
oauth2(Required scopes: t1_api)
Bodyapplication/jsonrequired
ownerUserIdstring or null, (uuid)

The user of your company who owns the folder and becomes its retailer contact. Optional when your credentials identify a user: that user is taken, and a person may only name themselves (naming anyone else is a 403). Required when your credentials carry no user. The company always binds from your credentials, never from the payload.

namestringrequired
templateIdstring, (uuid)required

Your company's published food-family specification template, on which the folder's specifications are based — communicated at onboarding by Professional Services (same value as on specification creates). It must be owned by your company, published and in its active version; anything else is a 422 naming this field. Determines the folder's template family; packaging templates are rejected (422) — folders hold food-family specifications only.

descriptionstring or null
targetDateUtcstring, (date-time)required

Must not be in the past.

specificationNotestring or null

Default note carried to specifications created in this folder

languageCodestringrequired
Example:"en-US"
contactsArray of objects or null

The folder's contacts: users of your company who work on it, addressed by userId as discoverable through the CUMD public API. The folder's owner is always a contact and needs no entry here; omit the property for the owner alone. A userId that is not a user of your company is a 422 reported on contacts - the first refused entry stops the request and nothing is created.

curl -i -X POST \
  https://apis.traceone.com/spec/v2/folders \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",
    "name": "string",
    "templateId": "196100ac-4eec-4fb6-a7f7-86c8b584771d",
    "description": "string",
    "targetDateUtc": "2019-08-24T14:15:22Z",
    "specificationNote": "string",
    "languageCode": "en-US",
    "contacts": [
      {
        "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b"
      }
    ]
  }'

Responses

The folder was created

Bodyapplication/json
folderIdstring, (uuid)
Response
{
  "folderId": "5b6379a4-2a6c-4085-b184-45838a3b8e7e"
}