Table of contents

Custom Fields API

The Custom Fields API is a way to attach custom data to items. This API provides means to manage your custom fields.

Listing custom fields

GET /api/data/v3/fields?page-token={page-token}&limit={limit}

Optional Query Parameters:

• page-token - (string) A page token to fetch an additional or previous page of results
• limit - (int) How many results to return. Minimum: 1, Maximum: 1000, Default: 20

Response:

{
    "fields": [
        {
            "id": "5de700b219b0e84945469242fa23b6f4",
            "name": "thename",
            "description": "some description",
            "display_order": 1,
            "data_type": "string",
            "created_at": "2019-12-04T00:41:22.416234Z",
            "updated_at": "2019-12-04T00:41:22.416234Z"
        }
    ],
    "next_page": "",
    "previous_page": ""
}

• fields - (array) An array of field objects:
  • id - (string) The id of the field
  • name - (string) The name of the field
  • description - (string) The description of the field
  • display_order - (integer) The order the field will display on item detail and search results pages
  • data_type - (string) The data type of the field
  • created_at - (string) The timestamp when the field was created
  • updated_at - (string) The timestamp when the field was last updated
• next_page - A page token that can be used to retrieve the next page of fields. If this is an empty string, there are no additional results to return.
• previous_page - A page token that can be used to retrieve the previous page of fields. If this is an empty string, there are no earlier results available.

Status codes:

• 200 (success)
• 500 (unexpected error)

Creating a new field

POST /api/data/v3/fields

{
    "description": "The description",
    "name": "The name",
    "data_type": "string"
}

• name - (string) The name of the field
• description - (string) The description of the field
• data_type - (string) The data type of the field. One of bool, date, number, string

Response:

{
    "id": "5de700b219b0e84945469242fa23b6f4",
    "name": "thename",
    "description": "some description",
    "display_order": 1,
    "data_type": "string",
    "created_at": "2019-12-04T00:41:22.416234Z",
    "updated_at": "2019-12-04T00:41:22.416234Z"
}

• id - (string) The id of the field
• name - (string) The name of the field
• description - (string) The description of the field
• display_order - (integer) The order the field will display on item detail and search results pages
• data_type - (string) The data type of the field
• created_at - (string) The timestamp when the field was created
• updated_at - (string) The timestamp when the field was last update

Status codes:

• 201 (success)
• 500 (unexpected error)

Updating a field

PATCH /api/data/v3/fields/{id}

{
    "description": "The description",
    "name": "The name",
}

• name - (string) Optional. The name of the field
• description - (string) Optional. The description of the field

NOTE: Only the name and description of a field are mutable.

Response:

{
    "id": "5de700b219b0e84945469242fa23b6f4",
    "name": "thename",
    "description": "some description",
    "display_order": 1,
    "data_type": "string",
    "created_at": "2019-12-04T00:41:22.416234Z",
    "updated_at": "2019-12-04T00:41:22.416234Z"
}

• id - (string) The id of the field
• name - (string) The name of the field
• description - (string) The description of the field
• display_order - (integer) The order the field will display on item detail and search results pages
• data_type - (string) The data type of the field
• created_at - (string) The timestamp when the field was created
• updated_at - (string) The timestamp when the field was last update

Status codes:

• 200 (success)
• 500 (unexpected error)

Getting a specific field

GET /api/data/v3/fields/{id}

Response:

{
    "id": "5de700b219b0e84945469242fa23b6f4",
    "name": "thename",
    "description": "some description",
    "display_order": 1,
    "data_type": "string",
    "created_at": "2019-12-04T00:41:22.416234Z",
    "updated_at": "2019-12-04T00:41:22.416234Z"
}

• id - (string) The id of the field
• name - (string) The name of the field
• description - (string) The description of the field
• display_order - (integer) The order the field will display on item detail and search results pages
• data_type - (string) The data type of the field
• created_at - (string) The timestamp when the field was created
• updated_at - (string) The timestamp when the field was last update

Status codes:

• 200 (success)
• 404 (field not found)
• 500 (unexpected error)

Deleting a field

DELETE /api/data/v3/fields/{id}

Status codes:

• 200 (success)
• 500 (unexpected error)

Setting the display order of fields

PUT /api/data/v3/fields/order

{
    "fields": [
        { "id": "field3", "order": 1 },
        { "id": "field2", "order": 2 },
        { "id": "field1", "order": 3 }
    ]
}

Optional Query Parameters:

• page-token - (string) A page token to fetch an additional or previous page of results
• limit - (int) How many results to return. Minimum: 1, Maximum: 1000, Default: 20

Response:

{
    "fields": [
        { "id": "field3", "order": 1 },
        { "id": "field2", "order": 2 },
        { "id": "field1", "order": 3 }
    ]
}

• fields - (array) An array of field objects:
  • id - (string) The id of the field
  • order - (integer) The order the field should display on item detail and search results pages

Status codes:

• 200 (success)
• 500 (unexpected error)

This documentation is generated from the latest version of GrayMeta Platform. For documentation relevant to your own deployed version, please use the documentation inside the application.

© 2021 GrayMeta, Inc.