Get Specified Picklist Definition

Command

GET https://{server}/api/v1/{tenantId}/picklistDefns/{id}

Parameters

Name

Required

Data Type

Description

Parameter Type

tenantId

Yes

String

Unique identifier of the tenant.

Path

id

Yes

String

Unique identifier of the picklist definition.

Path

Responses

Status and Error Codes

See Common Status and Error Codes.

Successful Response Body

Field

Description

hostId

The identifier of the host instance that is returning the request.

status

The status of the request. Valid values:

  • SUCCESS - The operation was a success.

  • ERROR - A validation error occurred.

content

Returns an array of records.

Field

Description

pickListDefnId

The globally unique database-level identifier of the picklist definition.

name

Name of the picklist definition.

label

Label of the picklist definition.

description

A string describing the picklist definition.

tenantId

The tenant ID.

referenceType

Defines the type of a picklist definition. Valid values are:

  • API

  • OBJECT

  • STATIC

fields

Defines the key/value pairs.

Field

Description

key

An array of one or more key fields for the picklist.

value

An array of one or more value fields for the picklist.

Field

Description

expression

Used in the UI to display content based on the fields in the picklist.

title

The unique name for the expression. It's translated as a key that is used to display the expression in the UI.

reference

Refers to the source of the object, which can be an internal masterDataDefns object or an external API.

Field

Description

name

The name of an object definition. Not used if the referenceType is API or STATIC.

apiConnectionDefnId

The ID of an API definition. Not used if the referenceType is OBJECT or STATIC.

apiPath

The path in the API URL to the data. Not used if the referenceType is OBJECT or STATIC.

apiFormat

The API format type. Not used if the referenceType is OBJECT or STATIC.

data

The data for the picklist definition. Not used if the referenceType is OBJECT or API.

The data can be expressed in a flat or nested segmented list.

A flat segmented list is a simple array of objects with a list of key/value pairs for each record. There will be a line item for each key defined in the fields section. For example:

Key

Value

The name of the key.

The value of the key.

A nested segmented list organizes the keys and values based on the level of the segmentation. For example:

Field

Description

_k

The key for the segment level.

_v

The value for the segment level. Unless this is the final segment, the value consists of another array of keys and values. If this is the final segment, it contains an object with one or more key/value pairs.

Key

Value

The name of the key.

The value of the key.

createdTime

The date and timestamp when the picklist definition was created.

lastModifiedTime

The date and timestamp when the picklist definition was last modified.

createdBy

The ID the person who created the picklist definition.

lastModifiedBy

The ID of the person who last modified the picklist definition.

activeFlag

Indicates whether the picklist definition is active.

readOnly

Indicates whether the picklist definition is read-only. A read-only picklist definition can't be edited or deleted.

messages

If the status is SUCCESS, this field is always blank. If the status is ERROR, a validation error occurred. For example, the picklist definition ID in the URL is invalid.

count

The number of records returned.

Examples

Sample API Call

 
GET http://company.com/api/v1/pX3459712f8/picklistDefns/z22060618112573036186008
X-Application-Key: 30b5f27a684744116537882dda0e50efb8c5a6e26a7b7ad2f3fcb2c24436a840
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHB=

Successful Responses

Response Body Sample

 
{
    "hostId": "09071f29ceccd18667227a94122ba2f1",
    "status": "SUCCESS",
    "content": {
        "pickListDefnId": "z22060618112573036186008",
        "name": "re_assignments",
        "label": "RE Assignments",
        "description": "Picklist by API for FieldGlass company currencies",
        "tenantId": "pX2f8122a19",
        "referenceType": "API",
        "fields": {
            "key": [
                "assignmentId"
            ],
            "value": [
                "assignmentTitle",
                "assignmentRef"
            ]
        },
        "reference": {
            "apiConnectionDefnId": "z22060618112323535908009",
            "apiPath": "/resources/{resourceId}/assignments",
            "apiFormat": "Fieldglass"
        },
        "createdTime": "2022-06-06 18:11:25.787 +0000",
        "lastModifiedTime": null,
        "createdBy": "tenant_admin",
        "lastModifiedBy": null,
        "activeFlag": true,
        "readOnly": false
    },
    "messages": [],
    "count": 1
}

Error Responses

Response Body Error Sample - Invalid Picklist Definition ID in URL

 
{
    "hostId": "acfc5411b04391bc4ea4341cd20bc539",
    "status": "ERROR",
    "content": null,
    "messages": [
        {
            "type": "ERROR",
            "message": "Failed to Load Resource of Type PickListDefn with Arguments [z20041517331264945694a7]",
            "code": "error.resourceNotFound",
            "arguments": {
                "type": "PickListDefn",
                "id": "z20041517331264945694a7"
            },
            "key": "PickListDefn"
        }
    ],
    "count": -1
}
Related Information