page-subjects

Specification Version

Version: "1"

Context and rules

Required for the SubjectRead capability.

Return paged subjects based on structural entity keys, a search term, or custom field values.

Endpoint specification

• Name: endpoint-prefix-aireframe-page-subjects
• Verb: POST
• Authentication: Client credentials

Input

• Format: JSON
• Schema:

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"title": "page-subjects-input",
	"type": "object",
	"properties": {
		"Filter": {
			"type": "object",
			"properties": {
				"StructuralEntities": {
					"type": "array",
					"items": {
						"required": [
							"Key"
						],
						"properties": {
							"Key": {
								"type": "string"
							}
						}
					}
				},
				"SearchTerm": {
					"type": ["string", "null"]
				},
				"CustomFieldValues": {
					"type": ["array", "null"],
					"items": {
						"properties": {
							"CustomField": {
								"type": "object",
								"properties": {
									"Key": {
										"type": "string"
									},
									"DataType": {
										"type": "string",
										"enum": [
											"String",
											"Decimal",
											"Integer",
											"DateTime",
											"Date",
											"Time",
											"Boolean"
										]
									}
								},
								"required": [
									"Key",
									"DataType"
								]
							},
							"Value": {
								"type": "string"
							}
						}	
					},
					"required": [
						"CustomField",
						"Value"
					]
				}
			},
			"required": [
				"StructuralEntities",
				"SearchTerm",
				"CustomFieldValues"
			]
		},
		"PagingRequest": {
			"type": "object",
			 "properties": {
				"After": {
				"type": [
					"null",
					"string"
				],
				"description": "Request items after the node with provided cursor"
				},
				"Before": {
					"type": [
						"null",
						"string"
					],
					"description": "Request items before the node with provided cursor"
				},
				"First": {
					"type": [
						"integer",
						"null"
					],
					"description": "Request the first x items",
					"format": "int32"
				},
				"Last": {
					"type": [
						"integer",
						"null"
					],
					"description": "Request the last x items.",
					"format": "int32"
				},
				"OrderBy": {
					"type": [
						"null",
						"string"
					],
					"description": "Gets the key of the field to order by."
				},
				"OrderDirection": {
					"description": "Gets the direction to order by.",
					"oneOf": [
						{
							"type": "null"
						},
						{
							"type": "string",
							"enum": [
								"Ascending",
								"Descending"
							]
						}
					]
				}
			},
			"required": [
				"First"
			]
		}
	},
	"required": [
		"Filter",
		"PagingRequest"
	]
}

• Example:

{
	"Filter": {
		"StructuralEntities": [
			{"Key": "AAC"}
		],
		"SearchTerm": "",
		"CustomFieldValues": [
		    {
    			"CustomField": {
    				"Key": "key",
    				"DataType": "String"
    			},
			    "Value": "value"
		    }
		]
	},
	"PagingRequest": {
		"After": null,
		"Before": null,
		"First": 5,
		"Last": null,
		"OrderBy": null,
		"OrderDirection": null
	}
}

Response

• Format: JSON
• Schema:

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"title": "page-subjects-response",
	"type": "object",
	"properties": {
		"PageInfo": {
			"type": "object",
			"properties": {
				"HasNextPage": {
					"type": "boolean"
				},
				"HasPreviousPage": {
					"type": "boolean"
				},
				"StartCursor": {
					"type": "string"
				},
				"EndCursor": {
					"type": "string"
				},
				"TotalCount": {
					"type": "number"
				}
			},
			"required": [
				"HasNextPage",
				"HasPreviousPage",
				"TotalCount"
			]
		},
		"Edges": {
			"type": "array",
			"items": {
				"required": [
					"Cursor"
				],
				"properties": {
					"Node": {
						"type": "object",
						"properties": {
							"ExternalId": {
								"type": "string"
							},
							"AvatarHash": {
								"type": [
									"null",
									"string"
								]
							},
							"CustomFieldValues": {
								"type": "array",
								"items": {
									"required": [
										"CustomField"
									],
									"properties": {
										"Value": {
											"type": ["string", "null"]
										},
										"CustomField": {
											"type": "object",
											"properties": {
												"Key": {
													"type": "string"
												},
												"DataType": {
													"type": "string",
													"enum": [
														"String",
														"Decimal",
														"Integer",
														"DateTime",
														"Date",
														"Time",
														"Boolean"
													]
												}
											},
											"required": [
												"Key",
												"DataType"
											]
										}
									}
								}
							}
						},
						"required": [
							"ExternalId",
							"CustomFieldValues"
						]
					},
					"Cursor": {
						"type": "string",
						"description": "Gets a unique identifier for this node."
					}
				}
			}
		}
	},
	"required": [
		"PageInfo",
		"Edges"
	]
}

• Example

{
	"PageInfo": {
		"HasNextPage": false,
		"HasPreviousPage": false,
		"StartCursor": "subj-145",
		"EndCursor": "subj-145",
		"TotalCount": 1
	},
	"Edges": [
		{
			"Node": {
				"ExternalId": "subj-145",
				"AvatarHash": null,
				"CustomFieldValues": [
					{
						"Value": "Campaign A",
						"CustomField": {
							"Key": "name",
							"DataType": "String"
						}
					}
				]
			},
			"Cursor": "subj-145"
		}
	]
}

• Explanation of properties: Value should either be null or string regardless of its corresponding CustomField DataType property. If the Value is not null, the following C# format should be used within the string depending on the DataType property:
  • String - string
  • Integer - int32
  • Decimal - double
  • Boolean - bool
  • DateTime - DateTime
  • Date - DateOnly
  • Time - TimeOnly

AvatarHash

AvatarHash is a nullable string data type and should only change when the subject avatar changes.

When AvatarHash changes, it will trigger a call to the get-subject-avatar endpoint. For more information on this endpoint, please refer to the Get Subject Avatar Documentation.

If you are not using the subject avatar functionality, you can set AvatarHash to null.

Previous versions

None