Skip to main content

API Entities

The LetsBuild GraphQL API provides access to various entities that represent the core data structures in the platform. This guide covers the main entities, their fields, and how to work with them.

Core Entities​

Project​

Projects are the central organizing unit in LetsBuild. They represent construction projects and contain all related data.

📖 Project Reference

Key Fields:

  • id: UUID! - Unique identifier
  • name: String! - Project name
  • code: String! - Project code
  • address: String - Project address
  • city: String - Project city
  • zipCode: String - Postal code
  • startDate: DateTime - Project start date
  • endDate: DateTime - Project end date
  • isArchived: Boolean! - Whether the project is archived
  • country: Country - Associated country
  • logoUrl: String - Project logo URL

Example Query:

query GetProject($id: UUID!) {
  project(id: $id) {
    id
    name
    code
    address
    city
    zipCode
    startDate
    endDate
    isArchived
    country {
      name
      iso
    }
  }
}

List​

Lists represent punch lists or inspection lists within a project. They contain points that need to be addressed.

📖 List Reference

Key Fields:

  • id: UUID! - Unique identifier
  • title: String! - List title
  • code: String! - List code
  • date: String! - List date
  • creationDate: DateTime! - When the list was created
  • isArchived: Boolean - Whether the list is archived
  • isPublic: Boolean! - Whether the list is public
  • pointsCount: Int! - Number of points in the list
  • project: Project - Associated project
  • projectId: UUID - Project ID
  • numberingType: NumberingType - How points are numbered
  • occurrence: Int - List occurrence number

Example Query:

query GetList($id: UUID!) {
  list(id: $id) {
    id
    title
    code
    date
    creationDate
    isArchived
    isPublic
    pointsCount
    project {
      name
      code
    }
    numberingType
    occurrence
  }
}

Point​

Points represent individual items in a list that need attention or action.

📖 Point Reference

Key Fields:

  • id: UUID! - Unique identifier
  • subject: String! - Point subject
  • code: String - Point code
  • codeNum: String! - Point code number
  • date: DateTime! - Point date
  • dueDate: DateTime - Due date
  • isArchived: Boolean! - Whether the point is archived
  • isUrgent: Boolean! - Whether the point is urgent
  • status: Status - Point status
  • category: Category - Point category
  • project: Project - Associated project
  • listId: UUID! - Associated list ID
  • author: User - Point author
  • inCharge: [Chargee!]! - Users in charge
  • comments: [Comment!]! - Point comments
  • attachments: [Attachment!]! - Point attachments
  • customFields: [CustomField!]! - Custom field values

Example Query:

query GetPoints($projectId: UUID!, $afterId: UUID, $pageSize: Int) {
  points(projectID: $projectId, afterId: $afterId, pageSize: $pageSize) {
    id
    projectId
    project {
      id
      name
      code
    }
    codeNum
    code
    subject
    date
    category {
      code
      description
    }
    isArchived
    isUrgent
    dueDate
    archivedDate
    listId
    inCharge {
      userId
      tag
    }
    authorId
    author {
      id
      displayName
    }
    problemLocation
    entityVersion
    status {
      id
      code
      color
      name
    }
    lastModificationUserId
    hasAttachment
    customFields {
      id
      fieldId
      fieldName
      value
    }
  }
}

Form​

Forms represent quality, safety, or environmental forms within a project.

📖 Form Reference

Key Fields:

  • id: UUID! - Unique identifier
  • subject: String! - Form subject
  • code: String - Form code
  • codeNum: String! - Form code number
  • date: DateTime! - Form date
  • dueDate: DateTime - Due date
  • type: FormType! - Form type (environment, quality, safety)
  • status: FormStatus! - Current status
  • isArchived: Boolean! - Whether the form is archived
  • isConform: Boolean! - Whether the form is conform
  • isUrgent: Boolean! - Whether the form is urgent
  • project: Project - Associated project
  • listId: UUID! - Associated list ID
  • author: User - Form author
  • inCharge: [Chargee!]! - Users in charge
  • comments: [Comment!]! - Form comments
  • attachments: [Attachment!]! - Form attachments

Note: Forms are accessed through the formSync query. Individual form queries are not available.

User​

Users represent people in the system who can access projects and data.

📖 User Reference

Key Fields:

  • id: UUID! - Unique identifier
  • displayName: String - User's display name
  • email: String - User's email address
  • companyName: String - User's company
  • language: LanguageCode - User's preferred language
  • role: String - User's role (deprecated)

Note: Users are accessed through project participants or sync operations. Individual user queries are not available.

ProjectParticipant​

Project participants represent users who have access to a specific project with defined permissions.

📖 ProjectParticipant Reference

Key Fields:

  • participantId: UUID! - Unique participant identifier
  • projectId: UUID! - Associated project ID
  • userId: UUID! - Associated user ID
  • accessRightLevel: AccessRightLevel! - Access level (ADMIN, MANAGER, CONTRIBUTOR, GUEST)
  • user: User! - Associated user details

Example Query:

query GetProjectParticipants($projectId: UUID!) {
  projectParticipants(projectID: $projectId) {
    participantId
    projectId
    userId
    accessRightLevel
    user {
      displayName
      email
      companyName
    }
  }
}

Supporting Entities​

Category​

Categories help organize points and forms by type or classification.

📖 Category Reference

Key Fields:

  • id: UUID! - Unique identifier
  • code: String! - Category code
  • description: String! - Category description
  • displayOrder: Int - Display order
  • isDisabled: Boolean! - Whether the category is disabled
  • parentCategoryId: UUID - Parent category ID
  • subCategories: [SubCategory!] - Sub-categories

Status​

Statuses represent the current state of points or forms.

📖 Status Reference

Key Fields:

  • id: UUID! - Unique identifier
  • name: String - Status name
  • code: String - Status code
  • color: String - Status color

Country​

Countries represent geographical locations for projects.

📖 Country Reference

Key Fields:

  • id: UUID! - Unique identifier
  • name: String! - Country name
  • iso: String! - ISO country code
  • iso2: String - ISO 2-letter country code

Room​

Rooms represent physical spaces within projects.

📖 Room Reference

Key Fields:

  • id: UUID! - Unique identifier
  • code: String! - Room code
  • description: String - Room description
  • displayOrder: Int! - Display order
  • parentRoomId: UUID - Parent room ID

Folder​

Folders organize documents and files within projects.

📖 Folder Reference

Key Fields:

  • id: UUID! - Unique identifier
  • name: String! - Folder name
  • type: FolderType - Folder type (Custom, Photo, Report)
  • isPublic: Boolean! - Whether the folder is public
  • parentFolderId: UUID - Parent folder ID
  • documentCount: Int - Number of documents in the folder

Entity Relationships​

Project Hierarchy​

Project
├── Lists
│   └── Points
│       └── Comments, Attachments, CustomFields
├── Forms
│   └── Comments, Attachments
├── ProjectParticipants
│   └── Users
├── Categories
│   └── SubCategories
│       └── Subjects
├── Statuses
├── Rooms
└── Folders

Access Control​

  • Projects contain all other entities
  • ProjectParticipants define who can access a project and with what permissions
  • AccessRightLevel determines what operations users can perform:
    • ADMIN - Full access
    • MANAGER - Manage project data
    • CONTRIBUTOR - Create and edit content
    • GUEST - Read-only access

Common Query Patterns​

query GetProjectDetails($projectId: UUID!) {
  project(id: $projectId) {
    id
    name
    code
    projectParticipants {
      user {
        displayName
        email
      }
      accessRightLevel
    }
  }
  
  lists(projectID: $projectId) {
    id
    title
    code
    pointsCount
  }
  
  folders(projectID: $projectId) {
    data {
      id
      name
      type
    }
  }
}

Get List with Points​

query GetListWithPoints($listId: UUID!) {
  list(id: $listId) {
    id
    title
    code
    project {
      name
    }
  }
  
  # Note: Points are accessed through the point sync endpoint
}

Next Steps​

Now that you understand the available entities: