Schema

All data in Zaius is stored within collections called Objects (what many think of as a database table).

Objects are composed of Fields.

Fields link objects together via Relations.

Objects

Object Definition
{
"name": "object_name",
"display_name": "Display Name",
"alias": "object_alias",
"fields": [],
"relations": []
}

property

description

name

plural name for the object

display_name

user-friendly name shown within Zaius

alias

singular name for the object

fields

collection of Field objects constituting the Object

relations

collection of Relation objects

post
Create Object

https://api.zaius.com/v3/schema/objects
Create a new Object within Zaius, define its fields, and how it relates to other objects
Request
Response
Body Parameters
name
required
string
the plural name of the object (e.g. tickets)
display_name
required
string
the human-readable name of the object (e.g. Tickets)
alias
optional
string
the singular name of the object (e.g. ticket)
fields
required
array
an array of fields objects (see definition above)
relations
optional
array
an array of relations objects (see definition above)
200: OK
{
"name": "objects",
"display_name": "Object",
"alias": "object",
"fields": [
{
"name": "object_id",
"display_name": "New Object Identifier",
"type": "string",
"primary": true
},{
"name": "another_field",
"display_name": "Another Fields",
"type": "string"
},{
"name": "child_id",
"display_name": "Child Identifier",
"type": "number"
}
],
"relations": [
{
"name": "my_relation",
"display_name": "My Relationship",
"child_object": "child",
"join_fields": [{
"parent": "child_id",
"child": "child_id"
}]
}
]
}
400: Bad Request
{
"title": "Bad Request",
"status": 400,
"timestamp": "2018-08-07T13:44:17.659Z",
"detail": {
"invalids": [
{
"field": "name",
"reason": "already used by another object"
},
{
"field": "alias",
"reason": "already used by another object"
},
{
"field": "display_name",
"reason": "already used by another object"
},
{
"field": "fields",
"reason": "at least one primary key field required"
},
{
"field": "relations[0].child_object",
"reason": "does not exist"
}
]
}
}
Example Payload
{
"name": "objects",
"display_name": "Object",
"alias": "object",
"fields": [
{
"name": "object_id",
"display_name": "New Object Identifier",
"type": "string",
"primary": true
},{
"name": "another_field",
"display_name": "Another Fields",
"type": "string"
},{
"name": "child_id",
"display_name": "Child Identifier",
"type": "number"
}
],
"relations": [
{
"name": "my_relation",
"display_name": "My Relationship",
"child_object": "child",
"join_fields": [{
"parent": "child_id",
"child": "child_id"
}]
}
]
}

get
List Objects

https://api.zaius.com/v3/schema/objects
List the details of all objects within a Zaius account.
Request
Response
‚Äč
200: OK
[
{
"name": "tickets",
"display_name": "Tickets",
"alias": "ticket",
"fields": [
{
"name": "field_name",
"type": "number",
"display_name": "Display Name",
"primary": true
}
],
"relations": [
{
"name": "my_relation",
"display_name": "My Relationship",
"child_object": "target_object_name",
"join_fields": [
{
"parent": "child_id",
"child": "child_id"
}
]
}
]
},
{
"name": "concerts",
"display_name": "Concerts",
"alias": "concert",
"fields": [
{
"name": "field_name",
"type": "number",
"display_name": "Display Name",
"primary": true
}
],
"relations": [
{
"name": "my_relation",
"display_name": "My Relationship",
"child_object": "target_object_name",
"join_fields": [
{
"parent": "child_id",
"child": "child_id"
}
]
}
]
}
]
Example Request
curl -iX GET \
'https://api.zaius.com/v3/schema/objects' \
-H 'x-api-key: example.apiKey'

get
Get Object

https://api.zaius.com/v3/schema/objects/{object_name}
List all objects with a Zaius account.
Request
Response
Path Parameters
{object_name}
required
string
List the details of a specific object.
200: OK
{
"name": "tickets",
"display_name": "Tickets",
"alias": "ticket",
"fields": [
{
"name": "field_name",
"type": "number",
"display_name": "Display Name",
"primary": true
}
],
"relations": [
{
"name": "my_relation",
"display_name": "My Relationship",
"child_object": "target_object_name",
"join_fields": [
{
"parent": "child_id",
"child": "child_id"
}
]
}
]
}
Example Request
curl -iX GET \
'https://api.zaius.com/v3/schema/objects/myobject' \
-H 'x-api-key: example.apiKey'

Fields

{
"name": "field_name",
"type": "number",
"auto": true,
"display_name": "Display Name",
"description": "Description of field",
"created_by": "zaius",
"primary_key": true
}

property

description

name

name of the field

type

field data type. options are number, timestamp, text, boolean

auto

(read only) marks the field as one that is auto populated by Zaius

display_name

the user-friendly name used within Zaius

description

description of the field

created_by

(read only) specifies what/who created the field. current values as zaius and account

primary_key

marks the field as identifying for the containing object. only allowed during object creation.

post
Create Field

https://api.zaius.com/v3/schema/objects/{object_name}/fields
Create a new field on an Object within Zaius
Request
Response
Path Parameters
{object_name}
required
string
the name of the object where the field will be created
Body Parameters
name
required
string
the name of the field (e.g. ticket_id)
display_name
required
string
the human-readable name of the field (e.g. Ticket ID)
description
optional
array
detailed description of what the field's purpose is
type
required
array
an array of relations field data type. options are number, timestamp, string, boolean
200: OK
{
"name": "field_name",
"display_name": "Display Name",
"description": "Description of field",
"type": "number"
}
400: Bad Request
{
"title": "Bad Request",
"status": 400,
"timestamp": "2018-08-07T13:44:17.659Z",
"detail": {
"invalids": [
{
"field": "name",
"reason": "already exists"
}
}
}
Example Payload
{
"name": "field_name",
"type": "number",
"display_name": "Display Name",
"description": "Description of field"
}

Identifier Fields

If you are attempting to create an identifier (e.g. an address for messaging or an internal reference to a customer record similar to an email, phone number or token), refer to the Identifier API documentation:

get
List Fields

https://api.zaius.com/v3/schema/objects/{object_name}/fields
List the details of all fields of an object.
Request
Response
Path Parameters
{object_name}
required
string
The name of the object.
200: OK
[
{
"name": "object_id",
"display_name": "New Object Identifier",
"type": "string",
"created_by" "account",
"primary": true
},
{
"name": "another_field",
"display_name": "Another Fields",
"type": "string",
"created_by" "account"
},
{
"name": "child_id",
"display_name": "Child Identifier",
"type": "number",
"created_by" "account"
}
]
Example Payload
{
"name": "my_relation",
"display_name": "My Relationship",
"child_object": "child",
"join_fields": [{
"parent": "child_id",
"child": "child_id"
}]
}
Example Request
curl -iX GET \
'https://api.zaius.com/v3/schema/objects/{object_name}/fields' \
-H 'x-api-key: example.apiKey'

get
Get Field

https://api.zaius.com/v3/schema/objects/{object_name}/fields/{field_name}
List the details of a single field of an object.
Request
Response
Path Parameters
{field_name}
required
string
The name of the field.
{object_name}
required
string
The name of the object.
200: OK
{
"name": "field_name",
"type": "number",
"display_name": "Display Name",
"auto": true,
"description": "The venue that the user visisted.",
"created_by" "zaius",
}
Example Request
curl -iX GET \
'https://api.zaius.com/v3/schema/objects/{object_name}/fields/{field_name}' \
-H 'x-api-key: example.apiKey'

Relationships

Representation describing a relationship between two objects. The Object containing the Relation definition is the parent object.

{
"name": "relation_name",
"display_name": "Relation Display Name",
"child_object": "child_object_name",
"join_fields": [{
"parent": "child_id",
"child": "child_id"
}]
}

property

description

name

name for the relation

display_name

user-friendly name shown within Zaius

child_object

child Object name

join_fields

collection of parent child pairs. parent is the field name (foreign key) on the owning Object and child is the related Objects primary key. Multiple are allowed to support objects with compound primary keys.

post
Create Relationship

https://api.zaius.com/v3/schema/objects/{object_name}/relations
Create a new relation between Objects within Zaius
Request
Response
Path Parameters
{object_name}
required
string
the name of the object where the field will be created
Body Parameters
child_object
required
boolean
the name of the child object
name
required
string
the name of the relationship (e.g. ticket)
display_name
required
string
the -readable name of the field (e.g. Ticket)
join_fields.parent
required
array
the name on this object that will link to the child object (e.g. id)
join_fields.child
required
array
the name on the child object that will link to this object (e.g. ticket_id)
200: OK
{
"name": "my_relation",
"display_name": "My Relationship",
"child_object": "child",
"join_fields": [{
"parent": "child_id",
"child": "child_id"
}]
}
400: Bad Request
{
"title": "Bad Request",
"status": 400,
"timestamp": "2018-08-14T12:23:04.500Z",
"detail": {
"invalids": [
{
"field": "join_fields[0].parent",
"reason": "does not match child data type"
}
]
}
}

get
List Relations

https://api.zaius.com/v3/schema/objects/{object_name}/relations
List the details of all relationships of an object.
Request
Response
Path Parameters
{object_name}
required
string
The name of the object.
200: OK
[
{
"name": "my_relation",
"display_name": "My Relationship",
"child_object": "child",
"join_fields": [{
"parent": "child_id",
"child": "child_id"
}]
},
{
"name": "my_relation2",
"display_name": "My Relationship 2",
"child_object": "child",
"join_fields": [{
"parent": "child_id",
"child": "child_id"
}]
}
]
Example Request
curl -iX GET \
'https://api.zaius.com/v3/schema/objects/{object_name}/relations' \
-H 'x-api-key: example.apiKey'

get
Get Relation

https://api.zaius.com/v3/schema/objects/{object_name}/relations/{relation_name}
List the details of a single relationship of an object.
Request
Response
Path Parameters
{relation_name}
required
string
The name of the relationship.
{object_name}
required
string
The name of the object.
200: OK
{
"name": "my_relation",
"display_name": "My Relationship",
"child_object": "target_object_name",
"join_fields": [{
"parent": "child_id",
"child": "child_id"
}]
}
Example Request
curl -iX GET \
'https://api.zaius.com/v3/schema/objects/{object_name}/relations/{relation_name}' \
-H 'x-api-key: example.apiKey'