get-subjects

Specification Version

Version: "1"

Context and rules

Required for the SubjectRead capability.

Returns details of subjects when an array of ExternalSubjectIds is passed in.

Endpoint specification

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

Input

• Format: JSON
• Schema:

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"title": "get-subjects-input",
	"type": "object",
	"properties": {
		"Lookups": {
			"type": "array",
			"items": {
				"required": [
					"ExternalSubjectId",
					"LookupExpression"
				],
				"properties": {
					"ExternalSubjectId": {
						"type": "string"
					},
					"LookupExpression": {
						"type": ["string", "null"]
					}
				}
			}
		}
	},
	"required": [
		"Lookups"
	]
}

• Example:

{
	"Lookups": [
		{
			"ExternalSubjectId": "subj-145",
			"LookupExpression": null
		}
	]
}

• Explanation of properties: Lookup expression will always be null currently as the AireGlu data provider does not require subject mapping.

Response

• Format: JSON
• Schema:

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"title": "get-subjects-response",
	"type": "object",
	"properties": {
		"Subjects": {
			"type": "array",
			"items": {
				"required": [
					"ExternalId",
					"AvatarHash",
					"CustomFieldValues"
				],
				"properties": {
					"ExternalId": {
						"type": "string"
					},
					"AvatarHash": {
						"type": ["null", "string"]
					},
					"CustomFieldValues": {
						"type": "array",
						"items": {
							"required": [
								"Value",
								"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": [
		"Subjects"
	]
}

• Example

{
	"Subjects": [			
		{
			"ExternalId": "subj-145",
			"AvatarHash": null,
			"CustomFieldValues": [
				{
					"Value": "990122269",
					"CustomField": {
						"Key": "campaign_no",
						"DataType": "String"
					},
					"Value": "532",
					"CustomField": {
						"Key": "highest_daily_sales",
						"DataType": "Integer"
					}
				}
			]
		}
	]
}

• 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