Data Specifications

Define the shape of your data using a Data Specification. Specify the properties available including their data type, whether they are required, and validation. You can think of a Data Specification as a blueprint for an instance of some data.

Property Types

There are a number of data types available for each property in a Data Specification:

Type	Options	Description
`Name`	Title Required? First Name Required? Last Name Required?	A person's name, including their title. An implied gender, based on the title, can also be generated
`Email`	-	An e-mail address
`Address`	Line 1 Required? Line 2 Required? Town / City Required? Region Required? Postal Code Required? Allowed Countries?	A physical address
`Boolean`	-	A `true` or `false` value
`Text`	Minimum Length Maximum Length Regular Expression Format	A text string, containing a sequence of characters, including whitespace
`Integer`	Minimum Value Maximum Value	A whole number that can be positive, negative or zero. Range from `-2147483647` to `2147483647`
`BigInteger`	Minimum Value Maximum Value	A whole number that can be positive, negative or zero. Range from `-9,223,372,036,854,775,808` to `9,223,372,036,854,775,807`
`Decimal`	Minimum Value Maximum Value Rounding Decimal Places	A fractional number that contains a decimal point. Range from `±1.0 x 10^-²⁸` to `±7.9228 x 10²⁸`
`TimeOfDay`	Minimum Value Maximum Value	A time of day
`TimeRange`	From To Precision (`minute`, `second`, `ms`)	A time range, without a date
`Date`	Has Time Component? Minimum Value Maximum Value Precision (`minute`, `second`, `ms`) Allowed Days	A date
`DateRange`	Has Time Component? From To	A date range
`SingleSelect`	Options	A list of options, one of which can be selected
`MultiSelect`	Options Minimum number of selections Maximum number of selections	A list of options, one or many can be selected
`IpAddress`	Subnet Mask	An IP Address
`GeoLocation`	Bounding Box	A latitude and longitude coordinate

Requiredness

Properties can be marked as Required to ensure that a value is always present. This requiredness is validated on creation of a Data Instance.

Value Types

Provided

The value for the property is provided directly on the Data Instance, either collected from a completion via the API.

Calculated

The value for the property is calculated from other properties on the Data Instance.

For example, in the above home loan enquiry the Loan To Value Ratio (LVR) is calculated as:

(Mortgage Value / Home Value) * 100

Visibility

Properties on a Data Specification can be set to be either Public or Private visibility .The visibility determines who can see the property and its value:

Public

The property value is visible to everyone, including non-registered users.

This setting is not suitable for personally identifiable information (PII).

Private

The property value is only visible to an auction Winner, and to the Seller. A private property typically contains personally identifiable or sensitive information.

Personal information refers to any data or opinion that can identify an individual or make them reasonably identifiable,
depending on the situation. This can encompass a wide variety of details, such as:
- A person's name, signature, address, phone number, or date of birth
- Sensitive information
- Credit-related data
- Employee records
- Photographs
- Internet Protocol (IP) addresses
- Biometrics like voiceprints or facial recognition (as these capture unique individual characteristics)
- Location data from mobile devices (as it can indicate user behaviors and activity patterns).
It may also include sensitive information, a specific category of personal information that includes details or opinions about an individual's:
- Racial or ethnic background
- Political views or affiliations
- Religious or philosophical beliefs
- Trade union membership or associations
- Sexual orientation or behavior
- Criminal history
- Health or genetic data
- Certain types of biometric information.

Queryability

Properties on a Data Specification can be set to be either Queryable or Not Queryable.

Queryable

Buyers are able to create conditions against this property value as part of their Campaign queries.

For example, if you have an Address type property, and set it to Queryable then a Buyer can create a variety of different types of conditions in their Campaign:

Within the same country as the address
Within the same post code as the address
Within the same region as the address
Within X (kilometres/miles) of the address
Within a defined bounding box, that includes the address

Not Queryable

The property is not queryable within a Campaign. This is often used in conjunction with Private visibility as described above.

Example

An example Data Specification for a home loan enquiry is as follows:

Field	Type	Visibility	Required?	Queryable?	Validation	Value
`Name`	`Name`	Private	✅	❌	Title is optional
`Email`	`Text`	Private	✅	❌	Valid e-mail address
`Telephone`	`Text`	Private	✅	❌	Valid Australian number
`Address`	`Address`	Private	✅	✅	Valid Australian address
`DateOfBirth`	`Date`	Private	✅	✅	18 to 65 years old
`HomeValue`	`Integer`	Public	✅	✅	$0 to $50,000,000
`MortgageValue`	`Integer`	Public	✅	✅	$0 to $50,000,000
`LVR`	`Decimal`	Private	❌	✅	0.0% to 100.0%	Calculated as an expression: `(Mortgage Value / Home Value) * 100`
`Term`	`Integer`	Public	❌	✅	10 to 35 years
`Occupation`	`Choice`	Public	❌	✅	Single Choice	Skilled / Unskilled / Unemployed / Retired
`BadCredit`	`Boolean`	Public	✅	✅	Single Choice	Yes / No
`CallPreference`	`Time`	Private	❌	✅		08:00 - 20:00

Using the Create a Data Specification API, this can be expressed as:

{
    "name": "Home Loan Enquiry",
    "culture": "en-AU",
    "timeZone": "Australia/Sydney",
    "description": "Capturing enquiries from user's looking for a home loan",
    "properties": [
        {
            "name": "Name",
            "description": "The individual's name",
            "valueType": {
                "provided": {
                    "isRequired": true
                }
            },
            "isQueryable": false,
            "visibility": "PRIVATE",
            "propertyType": {
                "name": {
                    "requireFirstName": true,
                    "requireLastName": true,
                    "requireTitle": false
                }
            }
        },
        {
            "name": "Email",
            "description": "The individual's email address",
            "valueType": {
                "provided": {
                    "isRequired": true
                }
            },
            "isQueryable": false,
            "visibility": "PRIVATE",
            "propertyType": {
                "text": {
                    "maximumLength": 1024,
                    "regularExpressionFormat": "^[^@]+@[^@]+$"
                }
            }
        },
        {
            "name": "Telephone",
            "description": "The individual's telephone number",
            "valueType": {
                "provided": {
                    "isRequired": true
                }
            },
            "isQueryable": false,
            "visibility": "PRIVATE",
            "propertyType": {
                "text": {
                    "maximumLength": 30,
                    "regularExpressionFormat": "^(\\+?61|0)[2-478]\\d+$"
                }
            }
        },
        {
            "name": "Address",
            "description": "The individual's address",
            "valueType": {
                "provided": {
                    "isRequired": true
                }
            },
            "isQueryable": true,
            "visibility": "PRIVATE",
            "propertyType": {
                "address": {
                    "requireLine1": true,
                    "requireLine2": false,
                    "requireTownCity": false,
                    "requireRegion": false,
                    "requirePostcode": true,
                    "allowedTwoLetterCountryCodes": [
                        "AU"
                    ]
                }
            }
        },
        {
            "name": "DateOfBirth",
            "description": "The individual's Date of Birth",
            "valueType": {
                "provided": {
                    "isRequired": true
                }
            },
            "isQueryable": true,
            "visibility": "PRIVATE",
            "propertyType": {
                "int": {
                    "minimumValue": 18,
                    "maximumValue": 65
                }
            }
        },
        {
            "name": "HomeValue",
            "description": "The value of the home to get a loan for",
            "valueType": {
                "provided": {
                    "isRequired": true
                }
            },
            "isQueryable": true,
            "visibility": "PUBLIC",
            "propertyType": {
                "int": {
                    "minimumValue": 0,
                    "maximumValue": 50000000
                }
            }
        },
        {
            "name": "MortgageValue",
            "description": "The amount of loan required",
            "valueType": {
                "provided": {
                    "isRequired": true
                }
            },
            "isQueryable": true,
            "visibility": "PUBLIC",
            "propertyType": {
                "int": {
                    "minimumValue": 0,
                    "maximumValue": 50000000
                }
            }
        },
        {
            "name": "LVR",
            "description": "Loan to Value Ratio",
            "valueType": {
                "calculated": {
                    "expression": "(MortgageValue / HomeValue) * 100"
                }
            },
            "isQueryable": true,
            "visibility": "PRIVATE",
            "propertyType": {
                "decimal": {
                    "roundingDecimals": 2
                }
            }
        },
        {
            "name": "LoanTerm",
            "description": "The length in years of the loan term",
            "valueType": {
                "provided": {
                    "isRequired": false
                }
            },
            "isQueryable": true,
            "visibility": "PUBLIC",
            "propertyType": {
                "int": {
                    "minimumValue": 10,
                    "maximumValue": 35
                }
            }
        },
        {
            "name": "Occupation",
            "description": "The individual's occupation",
            "valueType": {
                "provided": {
                    "isRequired": false
                }
            },
            "isQueryable": true,
            "visibility": "PUBLIC",
            "propertyType": {
                "singleSelect": {
                    "options": [
                        {
                            "name": "Skilled",
                            "value": "Skilled"
                        },
                        {
                            "name": "Unskilled",
                            "value": "Unskilled"
                        },
                        {
                            "name": "Unemployed",
                            "value": "Unemployed"
                        },
                        {
                            "name": "Retired",
                            "value": "Retired"
                        }
                    ]
                }
            }
        },
        {
            "name": "BadCreditHistory",
            "description": "Does the individual have a bad credit history?",
            "valueType": {
                "provided": {
                    "isRequired": true
                }
            },
            "isQueryable": true,
            "visibility": "PUBLIC",
            "propertyType": {
                "boolean": {}
            }
        },
        {
            "name": "CallPreference",
            "description": "When the individual would prefer to be called",
            "valueType": {
                "provided": {
                    "isRequired": false
                }
            },
            "isQueryable": true,
            "visibility": "PRIVATE",
            "propertyType": {
                "timeOfDay": {
                    "minimumValue": {
                        "hours": 8,
                        "minutes": 0,
                        "seconds": 0,
                        "nanos": 0
                    },
                    "maximumValue": {
                        "hours": 20,
                        "minutes": 0,
                        "seconds": 0,
                        "nanos": 0
                    }
                }
            }
        }
    ]
}

Property Types​

Requiredness​

Value Types​

Provided​

Calculated​

Visibility​

Public​

Private​

Queryability​

Queryable​

Not Queryable​

Example​