Data Model

Tribe CRM organizes all data around three main entity types, each with its own purpose and inheritance hierarchy.

Entity Type	Description
Relations	The people and organizations in your network
Relationships	How Relations connect to your business (Customer, Supplier, Contact)
Activities	Time-based interactions: opportunities, invoices, tasks, events

Relations

The core entities in your network.

Relations represent the fundamental "who" in your CRM — the people and organizations you interact with. Every contact, company, or entity you work with starts as a Relation.

Relation Types

Relation Type	Description
Relation_Person	Individual people — name, email, phone number
Relation_Organization	Companies and organizations — company name, website, address

A single Relation can have multiple Relationships (e.g., the same person could be both a Contact and a Supplier contact).

Relations vs Relationships

This is a key distinction in Tribe CRM:

• Relation = The entity itself (the person or organization)
• Relationship = The role that entity plays in your business (Customer, Supplier, Contact, etc.)

Example:

• Relation_Organization with Name "ACME Corp" is the company entity
• Relationship_Organization_CommercialRelationship_Customer linking to ACME Corp defines their role as your customer
• The same ACME Corp could also have a Relationship_Organization_Supplier if they are also a supplier

One Relation, Multiple Relationships

A single person or organization can have many different roles in your business, each represented by a separate Relationship entity.

How Relations Are Created

In most scenarios, you create a Relationship (like a Contact or Customer), and the underlying Relation is automatically created for you.

You can also create Relations directly:

POST/v1/odata/Relation_Person

Relationships

How Relations connect to your business.

Relationships define the role or connection a Relation has within your organization. Think of them as saying: "This Person/Organization is a [Customer/Supplier/Partner/etc.] to us."

Relationship Types

Relationship Type	Description
Relationship_Person_CommercialRelationship_Contact	A person who is a contact
Relationship_Organization_CommercialRelationship_Customer	An organization that is a customer
Relationship_Organization_Supplier	An organization that is a supplier

Relationships Can Connect

• Organization to Organization — Partner companies, Subsidiaries
• Organization to Person — Employee, Contact at a company
• Person to Person — Family members, Colleagues

What Data Lives in Relationships?

Relationships store role-specific information that only applies to that particular connection.

Relationship Type	Role-Specific Data
Relationship_Organization_CommercialRelationship_Customer	Account manager, owners, price list
Relationship_Person_CommercialRelationship_Contact	Business email, phone number, department
Relationship_Organization_Supplier	Payment terms, price list, mailing preferences

General information (like company name or person's birthdate) lives in the Relation. Specific information (like "this person's role at this company") lives in the Relationship.

How to Find Relationship Names

Relationship names follow a consistent pattern:

Relationship_{RelationType}_{RelationshipPath}

To find the correct name:

1. Go to Configuration > Relations in Tribe CRM
2. Look at the Relationships (types) section
3. Identify the relationship type you need

Creating a Relationship

With a New Relation

Create a Relationship and its underlying Relation in one call:

POST/v1/odata/Relationship_Organization_CommercialRelationship_Customer

Between Two Existing Relations

Link an existing Person to an existing Organization:

POST/v1/odata/Relationship_Person_Contact_Standard

Activities

Time-based interactions and business processes.

Activities represent events, tasks, and time-bound interactions. They track what happens, when it happens, and who is involved.

Activity Types

Activity Type	Description
Activity_SalesOpportunity	Track potential sales from lead to close
Activity_Invoice	Billing and payment records
Activity_Offer	Quotations and price proposals
Activity_SalesOrder	Confirmed customer orders
Activity_Event	Meetings, calls, appointments
Activity_Task	To-do items and action items
Activity_Project	Projects and deliverables

What Makes Activities Different?

Unlike Relations and Relationships, Activities:

• Represent events and processes, not entities
• Have a lifecycle (created, in progress, completed, closed)
• Often have workflows with defined phases (e.g., Opportunity: Lead → Qualified → Proposal → Won/Lost)
• Can include financial data (revenue, costs, amounts)
• Connect to Relationships to show who is involved

Creating Activities

Activities are typically created with connections to Relationships:

POST/v1/odata/Activity_SalesOpportunity

tip

Always link Activities to relevant Relationships so they appear in the proper context in the CRM.

Phases

Activities progress through phases. Query the Datastore to retrieve available phases for an activity type:

GET/v1/odata/Datastore_Phase_ActivitySalesOpportunity

Then reference a phase by ID when creating or updating:

{
  "Phase": {
    "ID": "4b368fc2-7944-4828-93be-a9a15ef30364"
  }
}

CRUD Operations

How to create, read, update, and delete data in Tribe CRM.

Creating (POST)

Create a new entity by sending a POST request without an ID:

POST/v1/odata/Relation_Person

Reading (GET)

Retrieve entities using GET requests with OData query parameters:

GET/v1/odata/Relation_Person?$top=10&$orderby=LastName asc

Updating (PUT)

Update an existing entity by its ID. Only send the fields you want to change:

PUT/v1/odata/Relation_Person({id})

Deleting (DELETE)

Delete an entity by sending a DELETE request with its ID:

DELETE/v1/odata/Activity_SalesOpportunity({id})

Returns 204 No Content on success.

Linking to Other Entities

Many fields reference other entities. Pass the referenced entity's ID inside an object:

POST/v1/odata/Activity_SalesOpportunity

To check if a field references an entity, go to Configuration > [Entity] > Fields tab and look at the field type.

Using Dropdown Values (Datastore)

Tribe CRM uses a Datastore for predefined dropdown values (phases, countries, industries, etc.). Query the Datastore to retrieve available options:

GET/v1/odata/Datastore_Phase_ActivitySalesOpportunity

Then reference them by ID when creating or updating entities:

{
  "Phase": {
    "ID": "4b368fc2-7944-4828-93be-a9a15ef30364"
  }
}

note

You can view and manage Datastore values in Configuration > Selection lists in Tribe CRM.

Inheritance Model

Tribe CRM uses an inheritance hierarchy where properties flow from general to specific. Each layer adds more specific properties.

Entity → Relation → Relation_Organization
Entity → Relation → Relation_Person
Entity → Relationship → Relationship_Organization → Relationship_Organization_Supplier
Entity → Activity → Activity_Invoice
Entity → Activity → Activity_SalesOpportunity

When making API calls, use the most specific entity type to access the complete set of fields.

How It Works

Each entity type inherits all fields from its parent types. For example:

Entity Level	Fields Added
Entity	ID, _CreatedOn, _ModifiedOn, _Type
Relation	_Name, Tags, Attachments
Relation_Person	FirstName, LastName, EmailAddress, BirthDate

When you query Relation_Person, you get all fields from Entity, Relation, and Relation_Person combined.

Querying Parent Types

You can query a parent type to get entities of all subtypes at once:

GET/v1/odata/Relation?$top=10

This returns both Relation_Person and Relation_Organization entities. Use the _Type field to distinguish between them.

tip

Query the parent type when you need a mixed list. Query the specific subtype when you need type-specific fields or want to filter to one type.

Metadata Endpoint

To discover your complete schema — all entities, fields, and relationships in your environment — use the metadata endpoint:

GET/v1/odata/$metadata

This returns the full OData schema in XML format, including custom entities and fields specific to your Tribe CRM instance.

What's Included

The metadata document describes:

Element	Description
Entity types	All available entities (Relations, Relationships, Activities, Datastores)
Properties	Field names, data types, and whether they are nullable
Navigation properties	Links between entities (e.g., Activity → Relationship)
Entity sets	The queryable collections available via the API

Example Usage

Use the metadata to:

• Discover available fields before building queries
• Find custom fields — custom fields use the __ (double underscore) naming convention
• Identify entity relationships — which entities link to which
• Check data types — know whether a field is a string, date, number, or reference

tip

The metadata endpoint reflects your specific Tribe CRM configuration, including any custom entities and fields. It's the best way to explore what's available in your environment.

Custom Entities

Beyond the built-in entity types, Tribe CRM allows administrators to define entirely new entity types. These custom entities follow the same inheritance model — they extend Entity, Relation, Activity, or another base type and support the full OData API.

Custom entities are assigned a UUID-based identifier instead of a human-readable name. Custom fields on existing entities also use this convention, appearing as _117ecf60__d492__48a1__8aab__a131ad465fd5 in the metadata and API.

To find your custom entity IDs, go to Configuration in Tribe CRM and open the OData tab for each custom entity.

See the Custom Entities page for a live explorer that discovers your instance's custom types from the metadata.

Advanced Mutations

Updating via POST (ID in body)

Alongside the keyed PUT shown in CRUD Operations, Tribe CRM also accepts a POST to the collection with ID in the body as an update. When ID is present, the call is interpreted as "update this record"; when it's absent, the same endpoint creates a new record.

POST/v1/odata/Relation_Person

Only the fields included in the body are touched — every other field on the record is left unchanged. Passing an empty string ("") clears the field; omitting it preserves the current value.

POST vs PUT

Both work. POST to the collection is the form used throughout the Postman collection and lets you create-or-update from the same client code path. PUT to the keyed URL (/Relation_Person({id})) is the more explicit OData form when you already know the record exists.

Changing a Relationship's subtype (_Type)

Subtypes within the same inheritance branch can be swapped in place by sending the new _Type value. This applies only to siblings under Relationship.Organization.CommercialRelationship.* and Relationship.Person.CommercialRelationship.* — for example, promoting a Lead to a Customer.

POST/v1/odata/Relationship_Organization_CommercialRelationship_Lead

The ID is preserved across the swap. Linked activities, notes, attachments and any other dependent records stay attached — only the relationship's role changes. After the call, the record is queryable under the new subtype's endpoint.

note

This is not the same as deleting the Lead and creating a Customer; the audit trail and history are preserved. Cross-branch changes (e.g. turning a Relationship_Person_* into a Relationship_Organization_*) are not supported.

Updating localized fields (LocalizedName)

Many entities carry a LocalizedName field that holds translations as a JSON-encoded string. Updating it is a whole-blob replace: send the complete JSON, and the API stores exactly what you send.

POST/v1/odata/Product

To add a language, include the new key in the JSON. To remove a language, omit its key. To change an existing translation, overwrite its value. There is no partial-update form — read the current JSON, edit it client-side, and POST the result.