/customSource/schemas

Add or update a custom data source JSON schema.

Resource URL

/v2/applications/{communityApiKeyName}/customSource/schemas
Note:

Use the appropriate regional endpoint to ensure that you comply with your organization's privacy policy, and applicable laws and regulations. For details about the available regional endpoints, and how to identify your organization's region, see API Access.

Available methods

Method Description
1. POST Upload a new schema.
2. GET List all uploaded schemas.

Available fields for 1. POST

Element Description
id

A string GUID of the new schema.

Example
{
    "id": "524a1214-31af-4eac-892e-7a616132f765"
}

Parameters for 1. POST

The request body must include a JSON block defining the JSON schema. The following key-value pairs must be included in the schema definition.

$schema The URI the schema being defined must adhere to. It must be set to the following: "$schema": "https://json-schema.org/draft/2020-12/schema"
$id The unique identifier for the schema preceded by the /schemas/ path. For example: "$id": "/schemas/policy"
type Specify object. The schema defines an unordered collection of key-value pairs.
properties An object containing an object for each field definition for the data the schema describes.
required An array identifying the required fields.

The following custom keywords are used to define the properties that map to fields in the data the schema describes.

isID When set to true, identifies the property that serves as the unique identifier for the data the schema describes. Identifying at least one field where isID is true is required. For example: 
"Transaction ID": {
            "type": "string",
            "isID": true
        }
isSensitive When set to true, identifies that the property is associated with a field that contains sensitive data. For example, a property that maps to a Community profile variable where the sensitive data option is selected.
singleChoice Specifies that the property represents a single choice question, where one answer is recorded from a list of possible answers.
multiChoice Specifies that the property represents a multiple choice question, where one or more answer is recorded from a list of possible answers.
customType Specifies a custom property type. Supported custom types include NPS℠1 and CSATScore.
isSourceCommitTimestamp Specifies that the date field is a commit timestamp in the source data. This property is important to set to preserve timeseries data.
Example POST body
[
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "/schemas/policy",
    "type": "object",
    "properties": {
        "Transaction ID": {
            "type": "string",
            "isID": true
        },
        "Transaction Date": {
            "type": "string",
            "format": "date",
            "isSourceCommitTimestamp": true
        },
        "Policy Number": {
            "type": "string"
        },
        "Product Name": {
            "type": "string"
        },
        "Premium Currency": {
            "type": "string"
        },
        "Premium Amount": {
            "type": "number"
        },
        "Payment Mode": {
            "enum": ["Monthly", "Annual", "Semi-Annual", "Quarterly", "Single Pay"],
            "singleChoice": true
        },
        "Sum Insured": {
            "type": "number"
        },
        "Owner First Name": {
            "type": "string"
        },
        "Owner Last Name": {
            "type": "string"
        },
        "Email": {
            "type": "string",
            "format": "email",
            "isSensitive": true
        }
    },
    "required": ["Transaction ID", "Owner First Name", "Owner Last Name", "Email"]
}
]

Available fields for 2. GET

Element Description
$id The unique identifier for the schema definition. For example: "$id": "/schemas/call_center_2022"
$schema The URI the schema being defined must adhere to. It must be set to the following: "$schema": "https://json-schema.org/draft/2020-12/schema"
Id The string GUID for the schema. Use this identifier with endpoints that require you to pass in an ID:
OP The last operation performed.
application_id The unique identifier for the application associated with the item.
commit_timestamp The timestamp of the most recent change, indicating when the schema was created or last updated.
properties An object containing an object for each field definition for the data the schema describes. The following data types are supported:
  • string
  • number
  • integer
  • object
  • array
  • boolean
  • null
2. GET response structure
{
    "meta": {
        "offset": 0,
        "limit": 0,
        "count": 2
    },
    "items": [
        {
            "$id": "/schemas/call_center_2021",
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "Id": "be1428ff-c03c-4713-846a-88c6dcdc789e",
            "OP": "U",
            "application_id": "f71d059f-2f08-4964-8710-ad4f011efa28",
            "commit_timestamp": "2021-01-01T08:04:07Z",
            "properties": {
                "agent": {
                    "type": "string"
                },
                "agt_no": {
                    "type": "number"
                },
               ...........
        },
        {
            "$id": "/schemas/call_center_2022",
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "Id": "b1dfd24e-75e5-417f-97ac-f5ce1c738e2c",
            "OP": "U",
            "application_id": "f71d059f-2f08-4964-8710-ad4f011efa28",
            "commit_timestamp": "2022-01-01T07:38:52Z",
            "properties": {
                "agent": {
                    "type": "string"
                },
                "agt_no": {
                    "type": "number"
                },
               ...........
        }
    ]
}
1 Net Promoter, NPS, and the NPS-related emoticons are registered U.S. trademarks, and Net Promoter Score and Net Promoter System are service marks, of Bain & Company, Inc., NICE Systems, Inc. and Fred Reichheld.