Resource objects / entity models

Resource objects (or entity models) are JSON objects representing resources / entities in requests to and responses from our API. Resource objects contain attributes of the given entity as well as resource identifier objects which represent relationships with other entities. All properties are in camel-case.

Example entity model for an activity-type:

{
	"id": 1,
	"name": "Email",
	"isEnabled": true,
	"orderIndex": 1,
	"icon": "email",
	"createdAt": "2018-05-21T10:14:12Z",
	"createdBy": { "id": 1, "type": "users" },
	"deletedBy": null,
	"deletedAt": null,
	"updatedAt": "2018-05-21T10:14:12Z",
	"updatedBy": { "id": 1, "type": "users" },
	"updatedSource": 1
}

This is just an example.

Common fields

Most resource objects will contain the following properties:

  • id: the unique identifier (integer) for this activity-type (in this example). To fetch this activity-type, you would request GET activity-types/{{id}}.json (because activity-types is the entity type).
  • createdAt: when the entity was created. All dates and times follow RFC-3339.
  • createdBy: the ID of the user who created the entity.
  • deletedAt: when the entity was deleted. All dates and times follow RFC-3339.
  • deletedBy: the ID of the user who deleted the entity.
  • updatedAt: when the entity was last updated. All dates and times follow RFC-3339.
  • updatedBy: the ID of the user who last updated the entity.
  • updatedSourceId: how the entity was updated (our web app, API, etc.) We haven’t defined the IDs returned yet.

Empty values

When a property is empty, it will always be returned by the API. It will either be null, [], {}, depending on its type.

Relationships

Properties may contain “resource identifier objects” which are used to denote relationships with other entities. There are to-one relationship which links the current entity to one other entity and to-many relationships which link the current entity to multiple other entities.

Relationships are not guaranteed to be given. They may exist or not, on an endpoint by endpoint basis. The relationship may only exist from the parent side, the child side, both, or may be omitted altogether.

To-one relationships

Example:

"createdBy": { "id": 1, "type": "users" },

A to-one relationship property’s value is a resource identifier object which contains an id and type. id is the user’s identifier and type is the [entity type](https://crmdeveloper.teamwork.com/general/entity-types). If you wanted to fetch this user, you could send [GET users/1.json`](https://crmdeveloper.teamwork.com/api/ref/users/get-users-idjson). Some endpoints also support including related entities.

An empty to-one relationship would look like this:

"deletedBy": null,

To-many relationships

An example to-many relationship would be the stages property in the pipelines model;

{
	...
	"stages": [
		{ "id": 72, "type": "stages" },
		{ "id": 10, "type": "stages" },
		...
	],
	"stagesCount": 5,
	...
}

A to-many relationship property’s value is an array of resource identifier objects. An empty to-one relationship would look like this:

"stages": [],
"stagesCount": 0,

All of the items might not be returned, see pagination for more. For each to-many relationship (e.g. stages), there’s a corresponding _Count property (e.g. stagesCount) containing the total number of items in the relationship.

For some relationships, there may be metadata. An example would be the contacts relationship in the deal entity model, which specifies which contact is the main contact;

{
	...
	"stages": [
		{ 
			"id": 12, 
			"meta": {
				"isMain": false,
			},
			"type": "contacts"
		},
		{ 
			"id": 33, 
			"meta": {
				"isMain": true,
			},
			"type": "contacts"
		},
		...
	],
	`contactsCount`: 7,
	...
}

Custom fields

Entity models may also support custom fields. See Dealing with custom fields for more.

Feedback

If you have any feedback or suggestions, feel free to contact us at api@teamwork.com.