Endpoints(v2)

Agents

Get Agent

Sample Angular Typescript Get Agent Request

public getAgent(): Observable<Agent> {
  const agentUrl = ...

  let params = new HttpParams();

  const requestOptions = {
    headers: new HttpHeaders(
      {
        'Content-Type': 'application/json',
        Accept: 'application/json',
        Authorization: localStorage.getItem('session_token')
      }
    ),
    params
  };

  // `${environment.API_URL}/v2/agents/${agentId}` also works
  return this.http.get<Agent>(`${environment.API_URL}/v2/${agentUrl}`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return Agent.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript Get Agent Response

HTTP/1.1 200 OK
{
  "data": {
    "id": "1",
    "type": "agent",
    "attributes": {
      "url": "topfloor",
      "name": "Kenough Property Management Ltd",
      "address": "Kenough Property Management Ltd\r\nSuite 7\r\n51  Demo Street\r\nLondon\r\nE4 7YQ",
      "email": "demo@blockman.co.uk",
      "website": "https://demo.blockman.co.uk",
      "default_phone": "020 12345678",
      "emergency_phone": "020 87654321",
      "licence_number": null,
      "disabled": false,
      "country": 1,
      "external_payment_portal_url": "https://www.blockman.co.uk/test_payment",
      "external_payment_portal_url_instruction": "You can pay by Debit/Credit card by visiting the link below. Please note additional fees apply to credit card payments.",
      "company_logo_urls": {
        "website_tiny": "https://s3.eu-west-2.amazonaws.com/myblockman-uk-production/agents/company_logos/000/000/001/cde2084cc0a4d6882fba1994b38ca73711208542.png?1725461287",
        "website_small": "https://s3.eu-west-2.amazonaws.com/myblockman-uk-production/agents/company_logos/000/000/001/71d7c7058832f0d973d297aa4b882e9b359613ca.png?1725461287",
        "website_medium": "https://s3.eu-west-2.amazonaws.com/myblockman-uk-production/agents/company_logos/000/000/001/028eb480fb9d44afa1bd5679889b6443b06709d8.png?1725461287",
        "website_large": "https://s3.eu-west-2.amazonaws.com/myblockman-uk-production/agents/company_logos/000/000/001/d11b2a7452a8aa66e6412e988f844f1448d1340e.png?1725461287",
        "email": "https://s3.eu-west-2.amazonaws.com/myblockman-uk-production/agents/company_logos/000/000/001/e40b8279688a8d0ae969262215a29cbba18d1d98.png?1725461287",
        "original": "https://s3.eu-west-2.amazonaws.com/myblockman-uk-production/agents/company_logos/000/000/001/28a1534b6d798b9c793d2a73b281dfabcba8792c.png?1725461287"
      },
      "created_at": "2019-11-25T11:11:38.261Z",
      "updated_at": "2025-06-10T14:05:57.229Z"
    }
  }
}

Finds and displays Agent with url of agent_url or with id of agent_id

Note: This endpoint is unusual as it can be accessed by unauthenticated users to enable login page branding with agent information.

GET https://api.myblockman.ie/v2/:agent_url

GET https://api.myblockman.co.uk/v2/:agent_url

GET https://api.myblockman.ie/v2/agents/:agent_id

GET https://api.myblockman.co.uk/v2/agents/:agent_id

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
agent_id	String	Agent id

Response

HTTP Status	HTTP Body	Description
200	A Agent Object	API found your agent and you have permission to view it.
403	Error Object	You do not have permission to view Agent. View error message in response for further details.
404	Error Object	Agent with agent_url not found. View error message in response for further details.

Update Agent

Sample Angular Typescript Update Agent Request

public updateAgent(): Observable<Agent> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Accept: 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  const body = {
    agent: {
      name: 'NEW NAME',
      ...
    }
  };

  return this.http.put<Agent>(
  `${environment.API_URL}/v2/${agentUrl}`,
    body,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return Agent.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript Update Agent Success Response

HTTP/1.1 200 OK
{
  "data": ... # Agent Object with new values
}

Sample Javascript Update Agent Failure Response

HTTP/1.1 422 Unprocessable Entity
{
    "url": [],
    "name": [
        "is too long (maximum is 50 characters)"
    ],
    "default_phone": [],
    "emergency_phone": [],
    "licence_number": [],
    "address": [],
    "website": [
        "is not a valid website URL"
    ],
    "email": []
}

Update an Agent with url of agent_url.

Only a Block Manager Role UserRole can update an Agent.

PUT https://api.myblockman.ie/v2/:agent_url

PUT https://api.myblockman.co.uk/v2/:agent_url

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Body Parameters

Parameter	Type	Required	Description
agent	Object	yes	Agent object with updated attributes

Agent Update Object

Parameter	Type	Required	Description
name	String	no	Agent name
address	String	no	Agent address
email	String	no	Must be a valid email address
default_phone	String	no	Agent phone number
emergency_phone	String	no	Agent emergency phone number
licence_number	String	no	Agent PSRA licence number in Ireland
email_greeting_format	String	no	Email greeting format template
website	String	no	Must be a valid website URL starting with http:// or https://
import_blockman_issues_enabled	Boolean	no	Enable importing blockman issues
blockman_issue_notifications_enabled	Boolean	no	Enable blockman issue notifications
statement_background_image_enabled	Boolean	no	Enable statement background image
statement_background_image	File	no	Must be a PNG file
company_logo	File	no	Must be a PNG, JPEG or GIF file. See Agent for documentation on how this image file is thumbnailed
external_payment_portal_url_myblockman_payload_enabled	Boolean	no	Enable external payment portal URL myblockman payload

Response

HTTP Status	HTTP Body	Description
200	An Agent Object	Agent successfully updated.
400	Error Object	Unpermitted parameters were in POST/PUT data. View error message in response for further details.
422	Hash object with Agent attributes and associated validation errors	Agent has validation errors. View error message in response for further details.
404	Error Object	Agent with agent_url not found. View error message in response for further details.

Authentication

Log in/Create User Session

Sample login requeset

public login(): Observable<AuthToken> {
  const body = {
    email: email,
    password: password
  };

  const requestOptions = {
    headers: new HttpHeaders(
      {
        'Content-Type': 'application/json'
      }
    )
  };

  return this.http.post<AuthToken>(
    `${environment.API_URL}/v2/login`,
    body,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return AuthToken.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript Log in via AuthToken Response

HTTP/1.1 201 Created
{
  "data": {
    "id": "...",
    "type": "auth_token",
    "attributes": {
      "token": "128_character_token"
    }
  }
}

Logs in a User and returns an AuthToken object. Client should be the attributes.token value in the Authorization header to authenticate API endpoints that require authentication.

Note this api does not require agent_url in the route.

POST https://api.myblockman.ie/v2/login

POST https://api.myblockman.co.uk/v2/login

URL Parameters

Parameter	Type	Description

Post Body Parameters

Parameter	Type	Required
email	String	yes
password	String	yes

Response

HTTP Status	HTTP Body	Description
201	AuthToken	The email and password matches a User and User Session is created
401	Error Object (Code 210)	Email Address or Password are incorrect
401	Error Object (Code 223)	Your account has not yet been activated. Please check your email sent from myblockman, and click the activation link. Alternatively, you can activate via Forgot Password link below.
401	Error Object (Code 204)	User account is disabled
400	Error Object (Code 208)	Already Logged In

Log out of User Session

Sample logout request

public logout(): Observable<> {
  const requestOptions = {
    headers: new HttpHeaders(
      {
        'Content-Type': 'application/json',
        Authorization: localStorage.getItem('session_token')
      }
    )
  };

  return this.http.delete<>(
    `${environment.API_URL}/v2/logout`,
    requestOptions
  )
  .pipe(
    ...
  );
}

Sample Javascript Log out via AuthToken Response

HTTP/1.1 204 No Content

Logs out a User

Note this api does not require agent_url in the route.

DELETE https://api.myblockman.ie/v2/logout

DELETE https://api.myblockman.co.uk/v2/logout

URL Parameters

Parameter	Type	Description

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Response

HTTP Status	HTTP Body	Description
204	Empty Body	User was successfully logged out, which means that the token won't work anymore.
403	Error Object (Code 216)	When not logged in or token is invalid

Validate User Session Token

Sample validate user session request

public validateUserSessionToken(): Observable<> {
  const requestOptions = {
    headers: new HttpHeaders(
      {
        'Content-Type': 'application/json',
        Authorization: localStorage.getItem('session_token')
      }
    )
  };

  return this.http.get<>(
    `${environment.API_URL}/v2/token/validate`,
    requestOptions
  )
  .pipe(
    ...
  );
}

Sample Javascript Validate Token via AuthToken Response

HTTP/1.1 204 No Content

Checks if the token passed into the Authorization header is valid. This does not log out the User. Low cost/low overhead API end point to check if a user session token is still valid/active.

Note this api does not require agent_url in the route.

GET https://api.myblockman.ie/v2/token/validate

GET https://api.myblockman.co.uk/v2/token/validate

URL Parameters

Parameter	Type	Description

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Response

HTTP Status	HTTP Body	Description
204	Empty Body	Token is valid
403	Error Object (Code 216)	When not logged in or token is invalid

Announcements

List/Search Global Announcements

Sample Angular Typescript List/Search Global Announcements Request

public listGlobalAnnouncements(): Observable<Announcement[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<Announcement[]>(
    `${environment.API_URL}/v2/${agentUrl}/announcements/search`
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return Announcement.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List/Search Global Announcements Response

HTTP/1.1 200 OK
{
  "data": [
    ... # List of Announcements 
  ],
  "meta": {
    "pagination": { ... }
  },
  "links": { ...}
}

List all Global Announcements. User must have adequate permissions to list:

• User must have Super Mega Admin Role UserRole
• User must have Block Manager Role UserRole

GET|POST https://api.myblockman.ie/v2/:agent_url/announcements/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/announcements/search

Note: This API returns only announcements where is_global is true.

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
page	PaginationParams	no	Pagination Params. Default is 30 per page.

Supported Includes (Relationship expand)

... This API does not support any include params ...

Supported Filters

... This API does not support any filtering ...

Supported Sorting

... This API does not support any sorting ...

Response

HTTP Status	HTTP Body	Description
200	Array of Announcement Objects with pagination meta	API found your block documents and you have permission to view them.
403	Error Object	You do not have permission to view Announcements for this Block. View error message in response for further details.
404	Error Object	Block with block_id not found. View error message in response for further details.

List/Search Block Announcements

Sample Angular Typescript List/Search Global Announcements Request

public listBlockAnnouncements(blockId: number): Observable<Announcement[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<Announcement[]>(
    `${environment.API_URL}/v2/${agentUrl}/blocks/:block_id/announcements/search`
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return Announcement.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List/Search Global Announcements Response

HTTP/1.1 200 OK
{
  "data": [
    ... # List of Announcements 
  ],
  "meta": {
    "pagination": { ... }
  },
  "links": { ...}
}

List all Announcements associated with a Block. User must have permission to view the Block. User must have adequate permissions to list:

• User must have Super Mega Admin Role UserRole
• User must have Block Manager Role UserRole
• User must have Unit Owner Role UserRole and own a Unit in the Block.
• User must have Third Party Role UserRole on behalf of a Unit Owner who owns a Unit in the Block.
• User must have Resident Role UserRole and be a resident of a Unit in the Block

GET|POST https://api.myblockman.ie/v2/:agent_url/blocks/:block_id/announcements/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/blocks/:block_id/announcements/search

Note: This API returns any announcement associated with the Block ( :block_id ). This will include global and non-global announcements.

Only Super Mega Admin Role and Block Manager Role will be able to view Announcements where is_published=false. Only announcements with is_published=true will be show to the other user roles.

There is one additional constraint for any user with a Resident User Role. Only announcements where resident_can_view=true will be returned to this user.

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
block_id	Integer	Block id

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
page	PaginationParams	no	Pagination Params. Default is 30 per page.

Supported Includes (Relationship expand)

... This API does not support any include params ...

Supported Filters

... This API does not support any filtering ...

Supported Sorting

... This API does not support any sorting ...

Response

HTTP Status	HTTP Body	Description
200	Array of Announcement Objects with pagination meta	API found your block documents and you have permission to view them.
403	Error Object	You do not have permission to view Announcements for this Block. View error message in response for further details.
404	Error Object	Block with block_id not found. View error message in response for further details.

Get Announcement

Sample Angular Typescript Get Announcement Request

public getAnnouncement(id: number): Observable<Announcement> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<Announcement>(
    `${environment.API_URL}/v2/${agentUrl}/announcements/${id}?include_content=true`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return Announcement.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Response

HTTP/1.1 200 OK
{
  "data": {
    "id": "7",
    "type": "announcement",
    "attributes": {
      "title": "Some New Event is Happening Soon",
      "publish_at": "2025-01-09T00:00:00.000Z",
      "is_read_only": false,
      "resident_can_view": false,
      "is_published": true,
      "is_global": true,
      "html_content_status": 0,
      "html_content_status_updated_at": "2025-06-12T14:07:45.598Z",
      "created_at": "2025-01-08T14:23:02.019Z",
      "updated_at": "2025-06-12T14:07:45.814Z",
      "content": {
        "delta":"{\"ops\":[{\"insert\":\"te\"},{\"attributes\":{\"link\":\"about:blank\"},\"insert\":\"stt\<hr\>\"},{\"insert\":\"\\n\"}]}",
        "html": "<div>\n  <p>te<a href=\"about:blank\" target=\"_blank\">stt&lt;hr&gt;</a></p>\n</div>",
      }
    }
  }
}

Returns a full single Announcement object. User must have adequate permissions to view:

• User must have Super Mega Admin Role UserRole
• User must have Block Manager Role UserRole.
• User must have Unit Owner Role UserRole and own a Unit in the Block.
• User must have Third Party Role UserRole on behalf of a Unit Owner who owns a Unit in the Block.
• User must have Resident Role UserRole and be a resident of a Unit in the Block - can only view documents where resident_can_view is true.

GET https://api.myblockman.ie/v2/:agent_url/announcements/:id

GET https://api.myblockman.co.uk/v2/:agent_url/announcements/:id

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
id	Integer	Announcement id - unique identifier

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include_content	Boolean	no	Include delta and html attributes

Supported Includes (Relationship expand)

... This API does not support any include params ...

Response

HTTP Status	HTTP Body	Description
200	A Announcement Object	API found your block document and you have permission to view it.
403	Error Object	You do not have permission to view this Announcement. View error message in response for further details.
404	Error Object	Announcement with id not found in this Block. View error message in response for further details.

Block Documents

List/Search BlockDocuments

Sample Angular Typescript List/Search Block Documents Request

public listBlockDocuments(blockId: number): Observable<BlockDocument[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<BlockDocument[]>(
    `${environment.API_URL}/v2/${agentUrl}/blocks/${blockId}/block_documents/search`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return BlockDocument.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List/Search BlockDocuments Response

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": "7",
      "type": "block_document",
      "attributes": {
        "category_name": "quasi",
        "notes": null,
        "document_date": "2023-09-20",
        "resident_can_view": false,
        "created_at": "2024-11-26T11:30:29.242Z",
        "updated_at": "2024-11-26T11:30:29.242Z",
        "file": {
          "download_url": null,
          "file_name": "file.pdf",
          "file_size": 501150,
          "updated_at": "2024-11-26T11:30:29.238Z"
        }
      },
      "relationships": {
        "block": {
          "data": {
            "id": "2",
            "type": "block"
          }
        }
      },
      "meta": {...}
    }
  ],
  "included": [
    {
      "id": "2",
      "type": "block",
      "attributes": {...},
      "relationships": {...},
      "meta": {...}
    }
  ],
  "meta": {
    "pagination": {...},
    "sort": [...]
  },
  "links": {...}
}

Finds all block documents for a specific block. User must have adequate permissions to view Block:

• User must have Super Mega Admin Role UserRole
• User must have Block Manager Role UserRole.
• User must have Unit Owner Role UserRole and own a Unit in the Block.
• User must have Third Party Role UserRole on behalf of a Unit Owner who owns a Unit in the Block.
• User must have Resident Role UserRole and be a resident of a Unit in the Block - can only view documents where resident_can_view is true.

GET|POST https://api.myblockman.ie/v2/:agent_url/blocks/:block_id/block_documents/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/blocks/:block_id/block_documents/search

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
block_id	Integer	Block id

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects
sort	SortParams	no	sort results. Default is ['-document_date']
page	PaginationParams	no	Pagination Params. Default is 30 per page.

Supported Includes (Relationship expand)

Parameter	Description
block	Blocka

Supported Filters

... This API does not support any filtering ...

Supported Sorting

Parameter	Description
-document_date	Document Date descending
document_date	Document Date ascending

Response

HTTP Status	HTTP Body	Description
200	Array of BlockDocument Objects with pagination meta	API found your block documents and you have permission to view them.
403	Error Object	You do not have permission to view BlockDocuments for this Block. View error message in response for further details.
404	Error Object	Block with block_id not found. View error message in response for further details.

Note: - Residents will only be shown block documents where resident_can_view is set to true.

Get BlockDocument

Sample Angular Typescript Get BlockDocument Request

public getBlockDocument(id: number): Observable<BlockDocument> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<BlockDocument>(
    `${environment.API_URL}/v2/${agentUrl}/block_documents/${id}?generate_download_url=true`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return BlockDocument.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Response

HTTP/1.1 200 OK
{
  "data": {
    "id": "127",
    "type": "block_document",
    "attributes": {
      "category_name": "Meeting Minutes",
      "notes": "Important block meeting documentation",
      "document_date": "2018-07-28",
      "resident_can_view": true,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-05-06T15:23:00.000Z",
      "file": {
        "download_url": "https://example.com/download/block_document_127.pdf",
        "file_name": "block_meeting_minutes_2018.pdf",
        "file_size": 1024576,
        "updated_at": "2018-05-06T15:23:00.000Z"
      }
    },
    "relationships": {
      "block": {
        "data": {
          "id": "13",
          "type": "block"
        }
      }
    },
    "meta": {...}
  }
}

Returns a single BlockDocument object.

The show endpoint retrieves details of a specific BlockDocument. User must have adequate permissions to view Block:

• User must have Super Mega Admin Role UserRole
• User must have Block Manager Role UserRole.
• User must have Unit Owner Role UserRole and own a Unit in the Block.
• User must have Third Party Role UserRole on behalf of a Unit Owner who owns a Unit in the Block.
• User must have Resident Role UserRole and be a resident of a Unit in the Block - can only view documents where resident_can_view is true.

File downloads (file) are available by passing the generate_download_url parameter. See more detail on file downloads at Secure File Downloads

GET https://api.myblockman.ie/v2/:agent_url/block_documents/:id

GET https://api.myblockman.co.uk/v2/:agent_url/block_documents/:id

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
id	Integer	BlockDocument id - unique identifier

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
generate_download_url	Boolean	no	Include download URLs for file
include	IncludeParams	no	expand relationships to full json objects

Supported Includes (Relationship expand)

Parameter	Description
block	Block

Response

HTTP Status	HTTP Body	Description
200	A BlockDocument Object	API found your block document and you have permission to view it.
403	Error Object	You do not have permission to view this BlockDocument. View error message in response for further details.
404	Error Object	BlockDocument with id not found in this Block. View error message in response for further details.

Block Managers

List/Search BlockManagers

Sample Angular Typescript List/Search BlockManagers Request

public listBlockManagers(): Observable<BlockManager[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<BlockManager[]>(
    `${environment.API_URL}/v2/${agentUrl}/block_managers/search`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return BlockManager.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List/Search BlockManagers Response

HTTP/1.1 200 OK
{
  "data": [
    ... # List of BlockManager Objects
  ],
  "meta": {
    "sort": ["name"],
    "pagination": { ... },
  },
  "links": { ... }
}

Lists all block managers.

GET|POST https://api.myblockman.ie/v2/:agent_url/block_managers/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/block_managers/search

Note: Both GET/POST methods are provided to allow flexibility in how params are passed to the API.

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects
sort	SortParams	no	sort results. Default is ['name']
page	PaginationParams	no	Pagination Params. Default is 20 per page.

Supported Includes (Relationship expand)

Parameter	Description
user	User

Supported Sorting

Parameter	Description
name	Name ascending
-name	Name descending

Response

HTTP Status	HTTP Body	Description
200	Array of BlockManager Objects	API found your block managers and you have permission to view them.
403	Error Object	You do not have permission to view BlockManagers in this Agent. View error message in response for further details.

Block Meetings

List/Search BlockMeetings

Sample Angular Typescript List/Search BlockMeetings Request

public listBlockMeetings(blockId: number): Observable<BlockMeeting[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders(
      {
        'Content-Type': 'application/json',
        Authorization: localStorage.getItem('session_token')
      }
    )
  };

  return this.http.get<BlockMeeting[]>(
    `${environment.API_URL}/v2/${agentUrl}/blocks/${blockId}/block_meetings/search`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return BlockMeeting.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List/Search BlockMeetings Response

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": "1",
      "type": "block_meeting",
      "attributes": {
        "meeting_type": 0,
        "venue_address": "123 Main Street, Dublin 1",
        "notice_description": "Notice for Annual General Meeting",
        "created_at": "2025-01-15T10:00:00.000Z",
        "updated_at": "2025-01-15T10:00:00.000Z",
        "meeting_date": "2025-02-15 14:00",
        "notice_date": "2025-02-01 12:00",
        "minutes_description": null,
        "notice": { // if notice file exists
          "download_url": null, // see "Get Block Meeting" page for details in downloading the file
          "file_name": "6219_Some_Block_Name_Log_Details__Venue_Date_01Apr2021___19_00_NOTICE.pdf",
          "file_size": 10320,
          "updated_at": "2025-04-02T11:09:35.983Z"
        },
        "minutes": { // if minutes file exists
          "download_url": null, // see "Get Block Meeting" page for details in downloading the file
          "file_name": "6219_Some_Block_Name_Log_Details__Venue_Date_01Apr2021___19_00_MINUTES.pdf",
          "file_size": 8904,
          "updated_at": "2025-04-02T11:09:35.736Z"
        }
      },
      "relationships": {      
        "block": {
          "data": {
            "id": "1",
            "type": "block"
          }
        }
      },
      "meta": {
        "notice_exists": true,
        "minutes_exists": true
      }
    },
    // ...
  ],
  "meta": {
    "pagination": { ... },
    "sort": [ ... ]
  },
  "links": { ...}
}

Finds all block meetings for a specific block. User must have adequate permissions to view Block:

• User must have Super Mega Admin Role UserRole
• User must have Block Manager Role UserRole.
• User must have Unit Owner Role UserRole and own a Unit in the Block.
• User must have Third Party Role UserRole on behalf of a Unit Owner who owns a Unit in the Block.

Note: - Third party users can only view AGM and EGM meetings. - Unit owners and residents can view AGM and EGM meetings by default. They can also view Directors meetings if they are a director, and Residents Committee meetings if they are a committee member.

GET|POST https://api.myblockman.ie/v2/:agent_url/blocks/:block_id/block_meetings/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/blocks/:block_id/block_meetings/search

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
block_id	Integer	Block id

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects
sort	SortParams	no	sort results. Default is ['-meeting_date']
page	PaginationParams	no	Pagination Params. Default is 20 per page.

Supported Includes (Relationship expand)

Parameter	Description
block	Block

Supported Filters

... This API does not support any filtering ...

Supported Sorting

Parameter	Description
-meeting_date	Meeting Date descending
meeting_date	Meeting Date ascending

Response

HTTP Status	HTTP Body	Description
200	Array of BlockMeeting Objects with pagination meta	API found your block meetings and you have permission to view them.
403	Error Object	You do not have permission to view BlockMeetings for this Block. View error message in response for further details.
404	Error Object	Block with block_id not found. View error message in response for further details.

Get BlockMeeting

Sample Angular Typescript Get BlockMeeting Request

public getBlockMeeting(
  id: number
): Observable<BlockMeeting> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders(
      {
        'Content-Type': 'application/json',
        Authorization: localStorage.getItem('session_token')
      }
    )
  };

  return this.http.get<BlockMeeting>(
    `${environment.API_URL}/v2/${agentUrl}/block_meetings/${id}`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return BlockMeeting.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Response

HTTP/1.1 200 OK
{
  "data": {
    "id": "123",
    "type": "block_meeting",
    "attributes": {
      "meeting_type": 0,
      "venue_address": "Conference Room A, 123 Main Street, Dublin 1",
      "notice_description": "Notice is hereby given that the Annual General Meeting will be held...",
      "created_at": "2025-01-15T10:00:00.000Z",
      "updated_at": "2025-01-15T10:00:00.000Z",
      "meeting_date": "2025-02-15 14:00",
      "notice_date": "2025-02-01 12:00",
      "minutes_description": "Minutes of the Annual General Meeting held on...",
      "notice": {
        "download_url": "https://example.s3.amazonaws.com/signed-url-for-notice",
        "file_name": "agm_notice.pdf",
        "file_size": 102400,
        "updated_at": "2025-02-01T12:00:00.000Z"
      },
      "minutes": {
        "download_url": "https://example.s3.amazonaws.com/signed-url-for-minutes",
        "file_name": "agm_minutes.pdf",
        "file_size": 204800,
        "updated_at": "2025-02-16T10:00:00.000Z"
      }
    },
    "relationships": {
      "block": {
        "data": {
          "id": "1",
          "type": "block"
        }
      }
    },
    "meta": {
      "notice_exists": true,
      "minutes_exists": true
    }
  }
}

Returns a single BlockMeeting object.

The show endpoint retrieves details of a specific BlockMeeting. User must have adequate permissions to view Block:

• User must have Super Mega Admin Role UserRole
• User must have Block Manager Role UserRole for the Agent
• User must have Unit Owner Role UserRole and own a Unit in the Block
• User must have Third Party Role UserRole on behalf of a Unit Owner who owns a Unit in the Block

In addition to permission to view the Block access may be restricted based on the user's role and the meeting type:

• Super Mega Admin and Block Manager: Can view all meeting types
• Unit Owner and : Can view AGM and EGM meetings by default. Can also view Directors meetings if they are a director, and Residents Committee meetings if they are a committee member
• Third Party: Can only view AGM and EGM meetings

File downloads (notice and minutes) are available by passing the generate_download_url parameter. See more detail on file downloads at Secure File Downloads

GET https://api.myblockman.ie/v2/:agent_url/block_meetings/:id

GET https://api.myblockman.co.uk/v2/:agent_url/block_meetings/:id

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
id	Integer	BlockMeeting id

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
generate_download_url	Boolean	no	Include download URLs for notice and minutes files (when present)
include	IncludeParams	no	expand relationships to full json objects

Supported Includes (Relationship expand)

Parameter	Description
block	Block
agent	Agent

Response

HTTP Status	HTTP Body	Description
200	A BlockMeeting Object	API found your block meeting and you have permission to view it.
403	Error Object	You do not have permission to view this BlockMeeting. View error message in response for further details.
404	Error Object	BlockMeeting with id not found. View error message in response for further details.

Blocks

List/Search Blocks

Sample Angular Typescript List Blocks Request

public listBlocks(): Observable<Block[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<Block[]>(
    `${environment.API_URL}/v2/${agentUrl}/blocks/search`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return Block.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List Blocks Response

HTTP/1.1 200 OK
{
  "data": [
    ... # List of Block Objects!
  ],
  "meta": {
    "pagination": { ... },
    "sort": [ ... ],
    "filters": { ... }
  },
  "links": { ...}
}

Lists all blocks that the current user has permission to view.

• User with Super Mega Admin Role UserRole can view all blocks.
• User with Block Manager Role UserRole can view all blocks.
• User with Unit Owner Role UserRole can view blocks associated with their owned Units.
• User with Third Party Role UserRole can view blocks they have access to via their linked Unit Owner.
• User with Resident Role UserRole can view blocks associated with Units where they are residents.

GET|POST https://api.myblockman.ie/v2/:agent_url/blocks/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/blocks/search

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects
sort	SortParams	no	sort results. Default is ['block_name']
filter	FilterParams	no	filter results.
page	PaginationParams	no	Pagination Params. Default is 20 per page.

Supported Includes (Relationship expand)

Parameter	Description
block_manager	BlockManager

Supported Filters

Parameter	Type	Description
block_manager_id_eq	int	Filter by block manager (using block manager id)
quick_search_cont	string	text search against block name and company name

Supported Sorting

Parameter	Description
-block_name	Block Name Desc
block_name	Block Name Asc
-company_name	Company Name Desc
company_name	Company Name Asc

Response

HTTP Status	HTTP Body	Description
200	Array of Block Objects with pagination meta	API found your blocks and you have permission to view them.
403	Error Object	You do not have permission to view Blocks in this Agent. View error message in response for further details.

Get Block

Sample Angular Typescript Get Block Request

public getBlock(id: number): Observable<Block> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<Block>(
    `${environment.API_URL}/v2/${agentUrl}/blocks/${id}?include[]=block_manager`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return Block.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript Get Block Response

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "type": "block",
    "attributes": {
      "block_name": "The Oaks Development",
      "company_name": "The Oaks Management CLG",
      "address": "123 Green Lane, Oakville, County Dublin",
      "website": "www.demo.topfloor.ie",
      "email": "info@demo.topfloor.ie",
      "is_blockman_export_lease_schedules": true,
      "created_at": "2024-01-10T14:30:00.000Z",
      "updated_at": "2025-03-15T10:00:00.000Z",
      "block_picture": {
          "tiny": "SIGNED_EXPIRING_S3_URL",
          "small": "SIGNED_EXPIRING_S3_URL",
          "medium1": "SIGNED_EXPIRING_S3_URL",
          "medium2": "SIGNED_EXPIRING_S3_URL",
          "large": "SIGNED_EXPIRING_S3_URL",
          "original": "SIGNED_EXPIRING_S3_URL"
      },
      // Conditional Bank Attributes
      "current_bank_account_branch_name_and_address": "Main Street Branch, Exampletown",
      "current_bank_account_bic": "BOFIXXXX",
      "current_bank_account_sort_code": "900000",
      "current_bank_account_iban": "IE00BOFI90000012345678",
      "current_bank_account_number": "12345678",
      "current_bank_account_name": "The Oaks Management CLG Service Charge Account",
      // Conditional Non-Resident Attributes
      "unit_type_apartment_count": 50,
      "unit_type_duplex_count": 10,
      "unit_type_house_count": 5,
      "unit_type_car_space_count": 65,
      "unit_type_commercial_count": 2,
      "ct1_number": "CT12345",
      "vat_number": "IE9876543W",
      "number_of_units": 67,
      "governance_type": "Board Of Directors",
      "limited_by_type": "Guarantee",
      "company_registration_number": "600123",
      "registered_office_address": "45 Corporate Road, Business Park, Dublin 2",
      "annual_return_date_day": 15,
      "annual_return_date_month": 9,
      "secretary_name": "Corporate Secretaries Ltd.",
      "is_ground_rent_activated": false,
      "financial_year_start_on": "2025-01-01",
      "incorporation_date": "2010-06-01",
      "secretary_appointed_on": "2010-07-01"
    },
    "relationships": {
        "block_manager": {
          "data": { 
            "id": 3, 
            "type": "block_manager" 
          }
        }
    },
    "meta": {
      "block_directors_count": 3,
      "block_committee_members_count": 1,
      "block_meetings_count": 4,
      "block_documents_count": 27,
      "director_documents_count": 3,
      "ground_rent_landlords_count": 1,
      "residents_count": 56
    }
  },
  "included": [
    {
      "id": 3, 
      "type": "block_manager",
      "attributes": {...},
      "relationships": {...} 
    }
  ]
}

Returns single Block with id of block_id. User must have adequate permissions to view that Block:

• User with Super Mega Admin Role UserRole can view all blocks associated with Agent.
• User with Block Manager Role UserRole can view all blocks associated with Agent.
• User with Unit Owner Role UserRole can view blocks associated with their owned Units.
• User with Third Party Role UserRole can view blocks they have access to via their linked Unit Owner.
• User with Resident Role UserRole can view blocks associated with Units where they are residents.

GET https://api.myblockman.ie/v2/:agent_url/blocks/:block_id

GET https://api.myblockman.co.uk/v2/:agent_url/blocks/:block_id

URL Parameters

Parameter	Type	Description	Notes
agent_url	String	Agent url - unique identifier
block_id	int	Unique id for the Block

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects

Supported Includes (Relationship expand)

Parameter	Description
block_manager	BlockManager

Response

HTTP Status	HTTP Body	Description
200	A Block Object	API found your block and you have permission to view it.
403	Error Object	You do not have permission to view Block. View error message in response for further details.
404	Error Object	Block with block_id not found. View error message in response for further details.

List/Search Block Announcements

Sample Angular Typescript List/Search Global Announcements Request

public listBlockAnnouncements(blockId: number): Observable<Announcement[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<Announcement[]>(
    `${environment.API_URL}/v2/${agentUrl}/blocks/:block_id/announcements/search`
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return Announcement.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List/Search Global Announcements Response

HTTP/1.1 200 OK
{
  "data": [
    ... # List of Announcements 
  ],
  "meta": {
    "pagination": { ... }
  },
  "links": { ...}
}

List all Announcements associated with a Block. User must have permission to view the Block. User must have adequate permissions to list:

• User must have Super Mega Admin Role UserRole
• User must have Block Manager Role UserRole
• User must have Unit Owner Role UserRole and own a Unit in the Block.
• User must have Third Party Role UserRole on behalf of a Unit Owner who owns a Unit in the Block.
• User must have Resident Role UserRole and be a resident of a Unit in the Block

GET|POST https://api.myblockman.ie/v2/:agent_url/blocks/:block_id/announcements/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/blocks/:block_id/announcements/search

Note: This API returns any announcement associated with the Block ( :block_id ). This will include global and non-global announcements.

Only Super Mega Admin Role and Block Manager Role will be able to view Announcements where is_published=false. Only announcements with is_published=true will be show to the other user roles.

There is one additional constraint for any user with a Resident User Role. Only announcements where resident_can_view=true will be returned to this user.

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
block_id	Integer	Block id

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
page	PaginationParams	no	Pagination Params. Default is 30 per page.

Supported Includes (Relationship expand)

... This API does not support any include params ...

Supported Filters

... This API does not support any filtering ...

Supported Sorting

... This API does not support any sorting ...

Response

HTTP Status	HTTP Body	Description
200	Array of Announcement Objects with pagination meta	API found your block documents and you have permission to view them.
403	Error Object	You do not have permission to view Announcements for this Block. View error message in response for further details.
404	Error Object	Block with block_id not found. View error message in response for further details.

List/Search Block Units

Sample Angular Typescript List Units Belonging to a Block Request

public listBlockUnits(blockId): Observable<Unit[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders(
      {
        'Content-Type': 'application/json',
        Authorization: localStorage.getItem('session_token')
      }
    )
  };

  return this.http.get<Unit[]>(
    `${environment.API_URL}/v2/${agentUrl}/blocks/${blockId}/units/search`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return Unit.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List Units Response

HTTP/1.1 200 OK
{
  "data": [
    ... # List of Unit Objects!
  ],
  "meta": {
    "pagination": { ... },
    "sort": [ ... ],
    "filters": { ... }
  },
  "links": { ...}
}

Finds all units associated with this User and specified Block. User must have adequate permissions to view Block :

• User has Super Mega Admin Role UserRole will see all units in Block.
• User has Block Manager Role UserRole will see all units in Block.
• User has Unit Owner Role UserRole - will only see units in Block they own.
• User has Third Party Role UserRole - will only see units in Block they have access to via their linked Unit Owner.
• User hasResident Role UserRole - will only see units in Block they are residents of.

GET|POST https://api.myblockman.ie/v2/:agent_url/blocks/:block_id/units/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/blocks/:block_id/units/search

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
block_id	Integer	Block which the units belong to

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects
sort	SortParams	no	sort results. Default is ['unit_name']
filter	FilterParams	no	filter results.
page	PaginationParams	no	Pagination Params. Default is 20 per page.

Supported Includes (Relationship expand)

Parameter	Description
user	User who owns the unit
block	Block associated with unit
ground_rent_landlord	Ground Rent Landlord, UK only

Supported Filters

Parameter	Type	Description
quick_search_cont	String	Searches Unit Code, Unit Name, Lessee Name, Unit Owner User's Email, Residents' First Names, Residents' Last Names, Residents' Emails

Supported Sorting

Parameter	Description
unit_name	Sort by unit name asc
-unit_name	Sort by unit name desc

Response

HTTP Status	HTTP Body	Description
200	Array of Unit Objects with pagination meta	API found your units and you have permission to view them.
403	Error Object	You do not have permission to view Units in this Agent. View error message in response for further details.

Director Documents

Lis/Search DirectorDocuments

Sample Angular Typescript Get DirectorDocuments Request

public listBlockDirectorDocuments(blockId: number): Observable<DirectorDocument[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<DirectorDocument[]>(
    `${environment.API_URL}/v2/${agentUrl}/blocks/${blockId}/director_documents/search`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return DirectorDocument.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript Get DirectorDocuments Response

HTTP/1.1 200 OK
{
  "data": [
    ... # List of DirectorDocument Objects
  ],
  "meta": {
    "pagination": { ... },
    "sort": [ ... ],
    "filters": { ... }
  },
  "links": { ...}
}

Lists all director documents belonging to a block. User must have adequate permissions to view DirectorDocuments:

• User must have Super Mega Admin Role UserRole
• User must have Block Manager Role UserRole.
• User must have Director Role UserRole and the role is associated with the Block.
• User must have Third Party Role UserRole where the parent role is a director role associated with the Block.

GET|POST https://api.myblockman.ie/v2/:agent_url/blocks/:block_id/director_documents/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/blocks/:block_id/director_documents/search

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
block_id	Integer	Block id - unique identifier

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects
sort	SortParams	no	sort results. Default is ['block_name']
page	PaginationParams	no	Pagination Params. Default is 20 per page.

Supported Includes (Relationship expand)

Parameter	Description
block	Block

Supported Sorting

Parameter	Description
-document_date	Document Date Name Desc
document_date	Document Date Asc

Response

HTTP Status	HTTP Body	Description
200	Array of DirectorDocument Objects	API found your director documents and you have permission to view them.
403	Error Object	You do not have permission to view DirectorDocuments in this Block. View error message in response for further details.
404	Error Object	Block with block_id not found. View error message in response for further details.

Get DirectorDocument

Sample Angular Typescript Get DirectorDocument Request

public getDirectorDocument(id: number): Observable<DirectorDocument> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<DirectorDocument>(
    `${environment.API_URL}/v2/${agentUrl}/director_documents/${id}?generate_download_url=true`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return DirectorDocument.Deserialize(resData.data, resData.included);
    })
  );
}

Sample DirectorDocument Get Response

HTTP/1.1 200 OK
{
  "data": {
    "id": "127",
    "type": "director_document",
    "attributes": {
      "title": "Board Meeting Minutes - Q1 2025",
      "notes": "Minutes from the quarterly board meeting discussing budget allocation",
      "document_date": "2025-03-15",
      "created_at": "2025-03-16T10:30:00.000Z",
      "updated_at": "2025-03-16T10:30:00.000Z",
      "file": {
        "download_url": "https://example.com/download/director_document_127.pdf",,
        "file_name": "Q1_2025_Board_Minutes.pdf",
        "file_size": 2048576,
        "updated_at": "2025-03-16T10:30:00.000Z"
      }
    },
    "relationships": {
      "block": {
        "data": {
          "id": "13",
          "type": "block"
        }
      }
    },
    "meta": {...}
  }
}

Returns a single DirectorDocument object. User must have adequate permissions to view DirectorDocuments:

• User must have Super Mega Admin Role UserRole
• User must have Block Manager Role UserRole.
• User must have Director Role UserRole and the role is associated with the Block.
• User must have Third Party Role UserRole where the parent role is a director role associated with the Block.

File downloads (file) are available by passing the generate_download_url parameter. See more detail on file downloads at Secure File Downloads

GET https://api.myblockman.ie/v2/:agent_url/director_documents/:id

GET https://api.myblockman.co.uk/v2/:agent_url/director_documents/:id

URL Parameters

Parameter	Type	Description	Notes
agent_url	String	Agent url - unique identifier
id	int	Unique id for the DirectorDocument

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
generate_download_url	Boolean	no	Include download URLs for notice and minutes files (when present)
include	IncludeParams	no	expand relationships to full json objects

Response

HTTP Status	HTTP Body	Description
200	A DirectorDocument Object	API found your director_document and you have permission to view it.
403	Error Object	You do not have permission to view DirectorDocument. View error message in response for further details.
404	Error Object	DirectorDocument with director_document_id not found. View error message in response for further details.

Emergency Contacts

List/Search EmergencyContacts

Sample Angular Typescript List/Search EmergencyContacts Request

public listEmergencyContacts(unitId: number): Observable<EmergencyContact[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<EmergencyContact[]>(
    `${environment.API_URL}/v2/${agentUrl}/units/${unitId}/emergency_contacts/search`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return EmergencyContact.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List/Search EmergencyContacts Response

HTTP/1.1 200 OK
{
  "data": [
    ... # List of EmergencyContact Objects for this Unit
  ],
   "meta": {
    "pagination": { ... },
    "sort": [ ... ],
  },
  "links": { ...}
}

Lists all emergency contacts in a unit. User must have adequate permissions to view Emergency Contacts:

• User has Super Mega Admin Role UserRole
• User has Block Manager Role UserRole for the same Agent that the Unit belongs to.
• User has Unit Owner Role UserRole and own the Unit the Emergency Contacts belongs to.
• User has Third Party Role UserRole on behalf of a Unit Owner Role UserRole that owns the specified Unit.

GET|POST https://api.myblockman.ie/v2/:agent_url/units/:unit_id/emergency_contacts/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/units/:unit_id/emergency_contacts/search

Note: Both GET/POST methods are provided to allow flexibility in how params are passed to the API.

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
unit_id	Integer	Unit id which the emergency contacts belong to

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects
sort	SortParams	no	sort results. Default is ['name']
page	PaginationParams	no	Pagination Params. Default is 20 per page.

Supported Includes (Relationship expand)

Parameter	Description
unit	Unit

Supported Sorts

Parameter	Description
name	Name ascending
-name	Name descending
contact_type	contact_type ascending
-contact_type	contact_type descending

Response

HTTP Status	HTTP Body	Description
200	Array of EmergencyContact Objects	API found your emergency contacts for this unit and you have permission to view them.
403	Error Object	You do not have permission to view EmergencyContacts for this Unit. View error message in response for further details.

Get EmergencyContact

Sample Angular Typescript Get EmergencyContact Request

public getEmergencyContact(id: number): Observable<EmergencyContact> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<EmergencyContact>(
    `${environment.API_URL}/v2/${agentUrl}/emergency_contacts/${id}`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return EmergencyContact.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript Get EmergencyContact Response

HTTP/1.1 200 OK
{
   "data": ... # EmergencyContact Object
}

Finds EmergencyContact by id. User must have adequate permissions to view EmergencyContact :

• User has Super Mega Admin Role UserRole
• User has Block Manager Role UserRole for the same Agent that the Unit belongs to.
• User has Unit Owner Role UserRole and own the Unit the Emergency Contacts belongs to.
• User has Third Party Role UserRole on behalf of a Unit Owner Role UserRole that owns the specified Unit.

GET https://api.myblockman.ie/v2/:agent_url/emergency_contacts/:id

GET https://api.myblockman.co.uk/v2/:agent_url/emergency_contacts/:id

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
id	int	Unique id for the EmergencyContact

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects

Supported Includes (Relationship expand)

Parameter	Description
unit	Unit

Response

HTTP Status	HTTP Body	Description
200	A EmergencyContact Object	API found your emergency_contact and you have permission to view it.
403	Error Object	You do not have permission to view EmergencyContact. View error message in response for further details.
404	Error Object	EmergencyContact with emergency_contact_id not found. View error message in response for further details.

Ground Rent Transactions

List Ground Rent Transactions

Sample Angular Typescript List/Search Ground Rent Transactions Request

public searchGroundRentTransactions(unitId: number): Observable<Transaction[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<Transaction[]>(
    `${environment.API_URL}/v2/${agentUrl}/units/${unitId}/ground_rent_transactions/search`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return Transaction.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List/Search Ground Rent Transactions Response

HTTP/1.1 200 OK
{
  "data": [
    ... # List of Transaction Objects!
  ]
}

Finds all Ground Rent Transactions for a unit. User must have adequate permissions to view a units Transactions:

• User must have Super Mega Admin Role UserRole.
• User must have Block Manager Role UserRole.
• User must have Unit Owner Role UserRole and own the Unit the Transactions belongs to.
• User must have Third Party Role UserRole on behalf of another Unit Owner Role UserRole that has access to the unit.

GET|POST https://api.myblockman.ie/v2/:agent_url/units/:unit_id/ground_rent_transactions/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/units/:unit_id/ground_rent_transactions/search

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
unit_id	Integer	Unit which the transactions belongs to

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
page	PaginationParams	no	Pagination Params. Default is 20 per page.

Supported Includes (Relationship expand)

... This API does not support any includes ...

Supported Filters

... This API does not support any filtering ...

Supported Sorting

... This API does not support any sorting ...

Response

HTTP Status	HTTP Body	Description
200	Array of Transaction Objects with pagination links	API found your transactions and you have permission to view them.
403	Error Object	You do not have permission to view Transactions for this Unit. View error message in response for further details.
404	Error Object	Unit with unit_id not found. View error message in response for further details.

Get Ground Rent Transaction Document

Sample Angular Typescript Get Ground Rent Transaction Document Request

public getTransactionDocument(transactionId: number): Observable<TransactionDocument> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<TransactionDocument>(
    `${environment.API_URL}/v2/${agentUrl}/ground_rent_transactions/${transactionId}/document`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return TransactionDocument.Deserialize(resData.data);
    })
  );
}

Sample Javascript Get Ground Rent Transaction Document Response (Document Processing)

HTTP/1.1 202 Accepted
{
  "data": {
    "type": "transaction_document",
    "id": "1842",
    "attributes": {
      "status": 0
    }
  }
}

Sample Javascript Get Ground Rent Transaction Document Response (Document Ready)

HTTP/1.1 200 OK
{
  "data": {
    "type": "transaction_document",
    "id": "1842",
    "attributes": {
      "status": 1,
      "document": {
        //..Secure File Download Object
      }
    }
  }
}

Retrieves or initiates generation of a PDF document for a specific Ground Rent Transaction. User must have adequate permissions to view the transaction:

• User must have Super Mega Admin Role UserRole.
• User must have Block Manager Role UserRole.
• User must have Unit Owner Role UserRole and own the Unit the Transaction belongs to.
• User must have Third Party Role UserRole on behalf of another Unit Owner Role UserRole that has access to the unit.

GET https://api.myblockman.ie/v2/:agent_url/ground_rent_transactions/:id/document

GET https://api.myblockman.co.uk/v2/:agent_url/ground_rent_transactions/:id/document

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
id	Integer	Unique id for the Transaction

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Response

HTTP Status	HTTP Body	Description
200	A TransactionDocument Object	Document is ready to download, follow the usual SecureFileDownload approaach
202	A TransactionDocument Object	Document is not ready yet for download. Check again.
403	Error Object	You do not have permission to view this
404	Error Object	Transaction does not have a document available for download.
422	Error Object	Document generation failed or encountered an error.

Usage Notes

• Documents are generated on demand. You will need to poll this endpoint when status is 0 (Processing).
• Not all transactions have associated documents. Check the has_document meta field in the transaction object first.
• PDF documents are typically generated for charges, notices, and receipts but not for all transaction types.

Issues

List/Search Issues

Sample Angular Typescript List Issues Request

public listIssues(
  unitId: number
): Observable<Issue[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders(
      {
        'Content-Type': 'application/json',
        Authorization: localStorage.getItem('session_token')
      }
    )
  };

  return this.http.get<Issue[]>(
    `${environment.API_URL}/v2/${agentUrl}/units/${unitId}/issues/search`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return Issue.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List Issues Response

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": "456",
      "type": "issue",
      "attributes": {
        "issue_reference_number": 2024001,
        "status": 0,
        "category": "Plumbing",
        "reported_at": "2024-01-15T09:30:00.000Z",
        "status_at": "2024-01-15T09:30:00.000Z",
        "created_at": "2024-01-15T09:30:00.000Z",
        "updated_at": "2024-01-15T09:30:00.000Z",
      },
      "relationships": {
        "unit": {
          "data": { "id": "123", "type": "unit" }
        },
        "issues_actions":[...]
      },
      "meta": {
        "issue_actions_count": 3
      }
    }
  ],
  "meta": {
    "pagination": {
      "records": 25,
      "page": 1,
      "per_page": 20,
      "total_pages": 2,
      "total_current_page": 20,
      "next_page": 2,
      "prev_page": null,
      "first_page": 1,
      "last_page": 2
    },
    "sort:" ["-issue_reference_number"]
  }
}

Finds all issues for a specific unit. User must have adequate permissions to the associated Unit:

• User must have Super Mega Admin Role UserRole
• User must have Block Manager Role UserRole.
• User must have Unit Owner Role UserRole and own the Unit that the Issues belongs to.
• User must have Third Party Role UserRole on behalf of a Unit Owner Role UserRole that owns the Unit that the Issues belongs to.

Note:

• Issues are only available when the agent has import_blockman_issues_enabled feature flag enabled.

GET|POST https://api.myblockman.ie/v2/:agent_url/units/:unit_id/issues/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/units/:unit_id/issues/search

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
unit_id	Integer	Unit id - unique identifier

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects. Default is ['issue_actions']
sort	SortParams	no	sort results. Default is ['-issue_reference_number']
page	PaginationParams	no	Pagination Params. Default is 20 per page.

Supported Includes (Relationship expand)

Parameter	Description
unit	Unit
issue_actions	IssueActions has_many relationship

Supported Filters

... This API does not support any filtering ...

Supported Sorting

Parameter	Description
-issue_reference_number	Issue Reference Number descending (default)
issue_reference_number	Issue Reference Number ascending
-reported_at	Reported Date descending
reported_at	Reported Date ascending
-status_at	Status Date descending
status_at	Status Date ascending

Response

HTTP Status	HTTP Body	Description
200	Array of Issue Objects with pagination meta	API found your issues and you have permission to view them.
403	Error Object	You do not have permission to view Issues for this Unit. View error message in response for further details.
404	Error Object	Unit with unit_id not found. View error message in response for further details.

Password Reset

Create Password Reset Request

Sample Angular Typescript Send a Password Reset Email Request

public createPasswordResetRequest(
  email: string
): Observable<any> {
  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json'
    })
  };

  const body = {
    email: email
  };

  return this.http
    .post<any>(
      `${environment.API_URL}/v2/password_reset`,
      body,
      requestOptions
    )
    .pipe(
      catchError(this.handleError),
      map((resData: any) => {...})
    );
}

Sample Javascript Send a Password Reset Email Response

HTTP/1.1 201 Created
{#empty ojbect}

Creates a password reset request if API finds a user that matches email.

After a successful creation, the API will send an email to the registered users email address with further instructions.

See Password Reset Flow for guideness on the full recommended process to reset a users password.

Note this api does not require agent_url in the route but it is an optional POST param if you want to specify which agent branding should be used on the password reset email.

POST https://api.myblockman.ie/v2/password_reset

POST https://api.myblockman.co.uk/v2/password_reset

URL Parameters

Parameter	Type	Description

Post Body Parameters

Parameter	Type	Required	Description
email	String	yes	Email address to send password reset instructions to
agent_url	String	no	Optional Agent url identifier if you want to control the password reset email branding

Response

HTTP Status	HTTP Body	Description
201	empty object	Success password reset request creation. Email will be sent shortly
400	Error Object (Code 222)	No user found with the specified email address
401	Error Object	Rate limit exceeded or user account is disabled
422	Error Object	Invalid email address format

Validate Password Reset Request Key/Token

Sample Angular Typescript Validate Password Reset Key/Token Request

public validatePasswordResetKeyToken(
  passwordResetKey: string,
  passwordResetToken: string
): Observable<any> {
  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json'
    })
  };

  return this.http.get<any>(
    `${environment.API_URL}/v2/password_reset/validate/${passwordResetKey}/${passwordResetToken}`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map(() => {...})
  );
}

Sample Javascript Validate Password Reset Key/Token Response

HTTP/1.1 204 No Content

Validates if Password Reset key and token pair are valid. This endpoint can be used to verify a reset link before showing the password change form to provide better user experience.

See Password Reset Flow for guideness on the full recommended process to reset a users password.

Note this api does not require agent_url in the route.

GET https://api.myblockman.ie/v2/password_reset/validate/:key/:token

GET https://api.myblockman.co.uk/v2/password_reset/validate/:key/:token

URL Parameters

Parameter	Type	Description
key	String	The Password Reset Key
token	String	The Password Reset Token

Response

HTTP Status	HTTP Body	Description
204	Empty	Password reset key/token combination is valid and can be used to reset password
403	Error Object (Code 219)	Key and/or Token not valid
403	Error Object (Code 220)	Password Reset has expired after 15 minutes
403	Error Object (Code 221)	Password Reset was already used for this link/key

Complete Password Reset Request

Sample Angular Typescript Update User Password Via Password Reset Link Request

public updateUserPasswordViaPasswordResetLink(
  passwordResetKey: string,
  passwordResetToken: string,
  password: string
): Observable<any> {
  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json'
    })
  };

  const body = {
    password: password
  };

  return this.http
    .put<any>(
      `${environment.API_URL}/v2/password_reset/validate/${passwordResetKey}/${passwordResetToken}`,
      body,
      requestOptions
    )
    .pipe(
      catchError(this.handleError),
      map((resData: any) => {
        return resData;
      })
    );
}

Sample Javascript Update User Password Via Password Reset Link Response

HTTP/1.1 201 Created
{
  "data": {
    "id": "...",
    "type": "auth_token",
    "attributes": {
      "token": "128_character_token"
    }
  }
}

Updates user password using a valid password reset key-token pair. A successful password reset update will log the user in and return a AuthToken

See Password Reset Flow for guideness on the full recommended process to reset a users password.

Note this api does not require agent_url in the route.

PUT https://api.myblockman.ie/v2/password_reset/validate/:key/:token

PUT https://api.myblockman.co.uk/v2/password_reset/validate/:key/:token

URL Parameters

Parameter	Type	Description
key	String	The Password Reset Key
token	String	The Password Reset Token

Put Body Parameters

Parameter	Type	Required	Description
password	String	yes	New password for the user account

Response

HTTP Status	HTTP Body	Description
201	AuthToken	Password successfully updated and user automatically logged in
422	Hash object containing validation error messages	Password validation failed (e.g., too short, weak password)
403	Error Object (Code 219)	Key and/or Token not valid
403	Error Object (Code 220)	Password Reset has expired after 15 minutes
403	Error Object (Code 221)	Password Reset was already used for this link/key

Resident Documents

List/Search ResidentDocuments

Sample Angular Typescript List ResidentDocuments Request

public getResidentDocuments(unitId?: number): Observable<ResidentDocument[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<ResidentDocument[]>(
    `${environment.API_URL}/v2/${agentUrl}/units/${unitId}/resident_documents/search`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return ResidentDocument.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List ResidentDocuments Response

HTTP/1.1 200 OK
{
  "data": [
      ... # List of ResidentDocuments Objects!
  ]
}

Finds all resident_documents for a unit. User must have adequate permissions to view ResidentDocuments :

• User has Super Mega Admin Role UserRole
• User has Block Manager Role UserRole
• User has Unit Owner Role UserRole and own the Unit
• User has Third Party Role UserRole and parent role is the unit owner
• User has Resident Role UserRole and be a resident of a Unit. Only ResidentDocuments associated with the Resident will be shown.

Each resident document has a downloadable file. See more detail on file downloads at Secure File Downloads

GET|POST https://api.myblockman.ie/v2/:agent_url/units/:unit_id/resident_documents/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/units/:unit_id/resident_documents/search

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
unit_id	Integer	Unit id

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects
sort	SortParams	no	sort results. Default is ['-document_date']
page	PaginationParams	no	Pagination Params. Default is 20 per page.

Supported Includes (Relationship expand)

Parameter	Description
resident	Resident

Supported Filters

Parameter	Type	Description

Supported Sorting

Parameter	Description
-document_date	document_date Desc
document_date	document_date Asc

Response

HTTP Status	HTTP Body	Description
200	Array of ResidentDocument Objects	API found your resident_documents and you have permission to view them.
403	Error Object	You do not have permission to view ResidentDocuments in this Agent. View error message in response for further details.

Get ResidentDocument

Sample Angular Typescript Get ResidentDocument Request

public getResidentDocument(id: number): Observable<ResidentDocument> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<ResidentDocument>(
    `${environment.API_URL}/v2/${agentUrl}/resident_documents/${id}`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return ResidentDocument.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript Get ResidentDocument Response

HTTP/1.1 200 OK
{
   "data": ... # ResidentDocument Object
}

Finds and displays ResidentDocument by id. User must have adequate permissions to view ResidentDocument :

• User has Super Mega Admin Role UserRole
• User has Block Manager Role UserRole
• User has Unit Owner Role UserRole and own the Unit
• User has Third Party Role UserRole and parent role is the unit owner
• User has Resident Role UserRole and be a resident is associated with ResidentDocument.

File downloads (file) are available by passing the generate_download_url parameter. See more detail on file downloads at Secure File Downloads

GET https://api.myblockman.ie/v2/:agent_url/resident_documents/:id

GET https://api.myblockman.co.uk/v2/:agent_url/resident_documents/:id

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
id	int	Unique id for the ResidentDocument

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
generate_download_url	Boolean	no	Include download URLs for file
include	IncludeParams	no	expand relationships to full json objects

Supported Includes (Relationship expand)

Parameter	Description
resident	Resident

Response

HTTP Status	HTTP Body	Description
200	A ResidentDocument Object	API found your resident_document and you have permission to view it.
403	Error Object	You do not have permission to view ResidentDocument. View error message in response for further details.
404	Error Object	ResidentDocument with resident_document_id not found. View error message in response for further details.

Residents

List/Search Residents

Sample Angular Typescript List/Search Residents Request

public listUnitResidents(unitId: number): Observable<Resident[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<Resident[]>(
    `${environment.API_URL}/v2/${agentUrl}/units/${unitId}/residents/search`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return Resident.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List/Search Residents Response

HTTP/1.1 200 OK
{
  "data": [
      ... # List of Residents Objects!
  ],
  "meta": {
    "pagination": { ... },
    "sort": [ ... ],
    "filters": { ... }
  },
  "links": { ...}
}

Finds all residents in a unit. User must have adequate permissions to view Residents :

• User has Super Mega Admin Role UserRole.
• User has Block Manager Role UserRole.
• User has Unit Owner Role UserRole and own the Unit the Residents belongs to.
• User has Third Party Role UserRole and parent role is the unit owner

GET|POST https://api.myblockman.ie/v2/:agent_url/units/:unit_id/residents/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/units/:unit_id/residents/search

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
unit_id	Integer	Unit which the residents belongs to

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects
sort	SortParams	no	sort results. Default is ['first_name', 'last_name']
page	PaginationParams	no	Pagination Params. Default is 20 per page.

Supported Includes (Relationship expand)

Parameter	Description
unit	Unit

Supported Sorting

Parameter	Description
first_name	First name ascending
-first_name	First name descending
last_name	Last name ascending
-last_name	Last name descending

Response

HTTP Status	HTTP Body	Description
200	Array of Resident Objects	API found your residents and you have permission to view them.
403	Error Object	You do not have permission to view Residents in this Agent. View error message in response for further details.

Get Resident

Sample Angular Typescript Get Resident Request

public getResident(id: number): Observable<Resident> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<Resident>(
    `${environment.API_URL}/v2/${agentUrl}/residents/${id}`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return Resident.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript Get Resident Response

HTTP/1.1 200 OK
{
   "data": ... # Resident Object
}

Finds and displays Resident by id. User must have adequate permissions to view Resident :

• User must have Super Mega Admin Role UserRole
• User must have Block Manager Role UserRole for the same Agent that the Resident belongs to.
• User must have Unit Owner Role UserRole and own the Unit the Resident belongs to.
• User must have Third Party Role UserRole on behalf of another Unit Owner Role UserRole that has access to the Resident.
• User must have Resident Role UserRole that has access to the Resident.

GET https://api.myblockman.ie/v2/:agent_url/residents/:id

GET https://api.myblockman.co.uk/v2/:agent_url/residents/:id

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
id	int	Unique id for the Resident

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects

Supported Includes (Relationship expand)

Parameter	Description
unit	Unit

Response

HTTP Status	HTTP Body	Description
200	A Resident Object	API found your resident and you have permission to view it.
403	Error Object	You do not have permission to view Resident. View error message in response for further details.
404	Error Object	Resident with resident_id not found. View error message in response for further details.

Service Charge Transactions

List Service Charge Transactions

Sample Angular Typescript List/Search Service Charge Transactions Request

public searchServiceChargeTransactions(unitId: number): Observable<Transaction[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<Transaction[]>(
    `${environment.API_URL}/v2/${agentUrl}/units/${unitId}/service_charge_transactions/search`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return Transaction.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List/Search Service Charge Transactions Response

HTTP/1.1 200 OK
{
  "data": [
    ... # List of Transaction Objects!
  ]
}

Finds all service charge Transactions for a unit. User must have adequate permissions to view a units Transactions:

• User must have Super Mega Admin Role UserRole.
• User must have Block Manager Role UserRole.
• User must have Unit Owner Role UserRole and own the Unit the Transactions belongs to.
• User must have Third Party Role UserRole on behalf of another Unit Owner Role UserRole that has access to the unit.

GET|POST https://api.myblockman.ie/v2/:agent_url/units/:unit_id/service_charge_transactions/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/units/:unit_id/service_charge_transactions/search

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
unit_id	Integer	Unit which the transactions belongs to

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
page	PaginationParams	no	Pagination Params. Default is 20 per page.

Supported Includes (Relationship expand)

... This API does not support any includes ...

Supported Filters

... This API does not support any filtering ...

Supported Sorting

... This API does not support any sorting ...

Response

HTTP Status	HTTP Body	Description
200	Array of Transaction Objects with pagination links	API found your transactions and you have permission to view them.
403	Error Object	You do not have permission to view Transactions for this Unit. View error message in response for further details.
404	Error Object	Unit with unit_id not found. View error message in response for further details.

Get Service Charge Transaction Document

Sample Angular Typescript Get Service Charge Transaction Document Request

public getTransactionDocument(transactionId: number): Observable<TransactionDocument> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<TransactionDocument>(
    `${environment.API_URL}/v2/${agentUrl}/service_charge_transactions/${transactionId}/document`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return TransactionDocument.Deserialize(resData.data);
    })
  );
}

Sample Javascript Get Service Charge Transaction Document Response (Document Processing)

HTTP/1.1 202 Accepted
{
  "data": {
    "type": "transaction_document",
    "id": "1842",
    "attributes": {
      "status": 0
    }
  }
}

Sample Javascript Get Service Charge Transaction Document Response (Document Ready)

HTTP/1.1 200 OK
{
  "data": {
    "type": "transaction_document",
    "id": "1842",
    "attributes": {
      "status": 1,
      "document": {
        //..Secure File Download Object
      }
    }
  }
}

Retrieves or initiates generation of a PDF document for a specific service charge Transaction. User must have adequate permissions to view the transaction:

• User must have Super Mega Admin Role UserRole.
• User must have Block Manager Role UserRole.
• User must have Unit Owner Role UserRole and own the Unit the Transaction belongs to.
• User must have Third Party Role UserRole on behalf of another Unit Owner Role UserRole that has access to the unit.

GET https://api.myblockman.ie/v2/:agent_url/service_charge_transactions/:id/document

GET https://api.myblockman.co.uk/v2/:agent_url/service_charge_transactions/:id/document

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
id	Integer	Unique id for the Transaction

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Response

HTTP Status	HTTP Body	Description
200	A TransactionDocument Object	Document is ready to download, follow the usual SecureFileDownload approaach
202	A TransactionDocument Object	Document is not ready yet for download. Check again.
403	Error Object	You do not have permission to view this
404	Error Object	Transaction does not have a document available for download.
422	Error Object	Document generation failed or encountered an error.

Usage Notes

• Documents are generated on demand. You will need to poll this endpoint when status is 0 (Processing).
• Not all transactions have associated documents. Check the has_document meta field in the transaction object first.
• PDF documents are typically generated for charges, notices, and receipts but not for all transaction types.

Unit Documents

List/Search UnitDocuments

Sample Angular Typescript List UnitDocuments Request

public listUnitDocuments(unitId: number): Observable<UnitDocument[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<UnitDocument[]>(
    `${environment.API_URL}/v2/${agentUrl}/units/${unitId}/unit_documents/search`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return UnitDocument.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List UnitDocuments Response

HTTP/1.1 200 OK
{
  "data": [
    ... # List of UnitDocuments Objects!
  ],
  "meta": {
    "pagination": { ... },
    "sort": [ ... ],
    "filters": { ... }
  },
  "links": { ... }
}

Finds all unit_documents of a unit. User must have adequate permissions to view UnitDocuments :

• User has Super Mega Admin Role UserRole
• User has Block Manager Role UserRole
• User has Unit Owner Role UserRole and own the Unit
• User has Third Party Role UserRole and parent role is the unit owner
• User has Resident Role UserRole and be a resident of a Unit

Each unit document has a downloadable file. See more detail on file downloads at Secure File Downloads

GET|POST https://api.myblockman.ie/v2/:agent_url/units/:unit_id/unit_documents/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/units/:unit_id/unit_documents/search

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
unit_id	Integer	Unit which the unit_documents belongs to

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects
sort	SortParams	no	sort results. Default is ['-document_date']
page	PaginationParams	no	Pagination Params. Default is 20 per page.

Supported Includes (Relationship expand)

Parameter	Description
unit	Unit

Supported Filters

Parameter	Type	Description

Supported Sorting

Parameter	Description
-document_date	Document Date Desc
document	Document Date Asc

Response

HTTP Status	HTTP Body	Description
200	Array of UnitDocument Objects	API found your unit_documents and you have permission to view them.
403	Error Object	You do not have permission to view UnitDocuments in this Agent. View error message in response for further details.

Get UnitDocument

Sample Angular Typescript Get UnitDocument Request

public getUnitDocument(id: number): Observable<UnitDocument> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<UnitDocument>(
    `${environment.API_URL}/v2/${agentUrl}/unit_documents/${id}`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return UnitDocument.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript Get UnitDocument Response

HTTP/1.1 200 OK
{
   "data": ... # UnitDocument Object
}

Finds and displays UnitDocument by id. User must have adequate permissions to view UnitDocument :

• User has Super Mega Admin Role UserRole
• User has Block Manager Role UserRole
• User has Unit Owner Role UserRole and own the Unit
• User has Third Party Role UserRole and parent role is the unit owner
• User has Resident Role UserRole and be a resident of a Unit - can only view documents where resident_can_view is true.

File downloads (file) are available by passing the generate_download_url parameter. See more detail on file downloads at Secure File Downloads

GET https://api.myblockman.ie/v2/:agent_url/unit_documents/:id

GET https://api.myblockman.co.uk/v2/:agent_url/unit_documents/:id

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
id	int	Unique id for the UnitDocument

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
generate_download_url	Boolean	no	Include download URLs for file
include	IncludeParams	no	expand relationships to full json objects

Supported Includes (Relationship expand)

Parameter	Description
unit	Unit

Response

HTTP Status	HTTP Body	Description
200	A UnitDocument Object	API found your unit_document and you have permission to view it.
403	Error Object	You do not have permission to view UnitDocument. View error message in response for further details.
404	Error Object	UnitDocument with unit_document_id not found. View error message in response for further details.

Unit Lease Schedule Reports

Get UnitLeaseScheduleReport

Sample Angular Typescript Get UnitLeaseScheduleReport Request

public getUnitLeaseScheduleReport(unitId: number): Observable<UnitLeaseScheduleReport> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<UnitLeaseScheduleReport>(
    `${environment.API_URL}/v2/${agentUrl}/units/${unitId}/unit_lease_schedule_report`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return UnitLeaseScheduleReport.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript Get UnitLeaseScheduleReport Response

HTTP/1.1 200 OK
{
  "data": {
    "id": "1",
    "type": "unit_lease_schedule_report",
    "attributes": {
      "totals": {
        "yearly_charge": "778.75",
        "frequency_period_1_charge": "389.38",
        "frequency_period_2_charge": 0,
        "frequency_period_3_charge": "389.38",
        "frequency_period_4_charge": 0
      },
      "data": [
        {
          "percentage": null,
          "charge_name": "Service Charge",
          "charge_type": 0,
          "charge_frequency": 1,
          "unit_yearly_charge": "778.75",
          "charge_type_description": "Equal (All Units)",
          "charge_frequency_description": "Half Yearly",
          "lease_schedule_yearly_charge": "778.75",
          "max_number_of_yearly_charges": 2,
          "include_unit_in_lease_schedule": true,
          "unit_frequency_period_1_charge": "389.38",
          "unit_frequency_period_2_charge": null,
          "unit_frequency_period_3_charge": "389.38",
          "unit_frequency_period_4_charge": null,
          "number_of_times_charged_this_year": 1
        }
      ],
      "created_at": "2024-05-31T16:14:25.145Z",
      "updated_at": "2024-05-31T16:14:25.145Z"
    },
    "relationships": {
      "unit": {
        "data": {
          "id": "102",
          "type": "unit"
        }
      }
    }
  }
}

The unit lease schedule report combines data from multiple sources into a complex summary. To simplify this process, this API end point compiles the data into a unit_lease_schedule_report object, so the front end only needs to render the HTML table and totals without knowing how the underlying data is gathered.

User must have adequate permissions to view the UnitLeaseScheduleReport for the specified unit:

• User has Super Mega Admin Role UserRole.
• User has Block Manager Role UserRole.
• User has Unit Owner Role UserRole and own the Unit.
• User has Third Party Role UserRole and parent role is the unit owner

GET https://api.myblockman.ie/v2/:agent_url/units/:unit_id/unit_lease_schedule_report

GET https://api.myblockman.co.uk/v2/:agent_url/units/:unit_id/unit_lease_schedule_report

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
unit_id	Integer	Unique id for the Unit whose lease schedule report to retrieve

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects

Supported Includes

Parameter	Description
unit	Include the complete unit data with the response

Response

HTTP Status	HTTP Body	Description
200	A UnitLeaseScheduleReport Object	Successfully retrieved the lease schedule report for the specified unit
403	Error Object	You do not have permission to view the UnitLeaseScheduleReport for this Unit. View error message in response for further details
404	Error Object	Unit with unit_id not found, or no lease schedule report exists for this unit

Units

List/Search Units

Sample Angular Typescript List Units Request

public listUnits(): Observable<Unit[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders(
      {
        'Content-Type': 'application/json',
        Authorization: localStorage.getItem('session_token')
      }
    )
  };

  return this.http.get<Unit[]>(
    `${environment.API_URL}/v2/${agentUrl}/units/search`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return Unit.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List Units Response

HTTP/1.1 200 OK
{
  "data": [
    ... # List of Unit Objects!
  ],
  "meta": {
    "pagination": { ... },
    "sort": [ ... ],
    "filters": { ... }
  },
  "links": { ...}
}

Finds all units associated with this user:

• User has Unit Owner Role UserRole - will see all units they own.
• User has Third Party Role UserRole - will see all units they have access to via their linked Unit Owner.
• User has Resident Role UserRole - will see all units they are residents of.

GET|POST https://api.myblockman.ie/v2/:agent_url/units/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/units/search

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects
sort	SortParams	no	sort results. Default is ['unit_name']
filter	FilterParams	no	filter results.
page	PaginationParams	no	Pagination Params. Default is 20 per page.

Supported Includes (Relationship expand)

Parameter	Description
user	User who owns the unit
block	Block associated with unit
ground_rent_landlord	Ground Rent Landlord, UK only

Supported Filters

Parameter	Type	Description
quick_search_cont	String	Searches Unit Code, Unit Name, Lessee Name, Unit Owner User's Email, Residents' First Names, Residents' Last Names, Residents' Emails

Supported Sorting

Parameter	Description
unit_name	Sort by unit name asc
-unit_name	Sort by unit name desc

Response

HTTP Status	HTTP Body	Description
200	Array of Unit Objects with pagination meta	API found your units and you have permission to view them.
403	Error Object	You do not have permission to view Units in this Agent. View error message in response for further details.

Get Unit

Sample Angular Typescript Get Unit Request

public getUnit(id: number): Observable<Unit> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders(
      {
        'Content-Type': 'application/json',
        Authorization: localStorage.getItem('session_token')
      }
    )
  };

  return this.http.get<Unit>(
    `${environment.API_URL}/v2/${agentUrl}/units/${id}?include[]=block`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return Unit.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript Get Unit Response

HTTP/1.1 200 OK
{
  "data": {
    "id": 11,
    "type": "unit",
    "attributes": {
      "unit_code": "A101",
      "unit_name": "Apartment 101",
      "unit_type": "Apartment",
      "number_of_bedrooms": 2,
      "floor": "1",
      "size": "75sqm",
      "build_description": "Standard apartment build",
      "mailing_name": "Mr. John Owner",
      "salutation": "Dear Mr. Owner",
      "created_at": "2025-05-14T16:24:23.479Z",
      "updated_at": "2025-05-14T16:24:23.479Z",
      // Conditional attributes - visibility depends on user permissions
      "service_charge_payment_method_type": "Direct Debit",
      "ground_rent_payment_method_type": "Annual Bill",
      "ground_rent_amount_status": "Standard",
      "ground_rent_overridden_amount": null,
      "serivce_charge_payment_reference": "SC-A101-2025",
      "ground_rent_payment_reference": "GR-A101-2025",
      "interested_parties": "Bank of Ireland",
      "lessee_name": "John Owner",
      "lessee_phone_mobile": "0871234567",
      "lessee_phone_other": "012999999",
      "lessee_other_contact_notes": "Contact via email preferably",
      "lessee_address": "123 Main Street, Dublin 1",
      "lessee_is_resident": false,
      "car_space": "Space 22",
      "lessee_email": "john.owner@example.com",
      "service_charge_balance": 150.75,
      "ground_rent_balance": 50.00,
      "encoded_service_charge_payment_data": "ENCODED_SC_PAYLOAD_STRING",
      "encoded_ground_rent_payment_data": "ENCODED_GR_PAYLOAD_STRING",
      "lease_date_on": "2020-01-15"
    },
    "relationships": {
      "user": {
        "data": {
          "id": 55,
          "type": "user"
        }
      },
      "block": {
        "data": {
          "id": 7,
          "type": "block"
        }
      },
      "ground_rent_landlord": {
        "data": { 
          "id": 3, 
          "type": "ground_rent_landlord" 
        }
      }
    },
    "meta": {
      "residents_count": 2,
      "unit_previous_owners_count": 1,
      "emergency_contacts_count": 3,
      "unit_documents_count": 8
    }
  },
  "included": [
    {
      "id": 7,
      "type": "block",
      "attributes": {...},
      "relationships": {...}
    }
  ]
}

Finds and displays Unit with id of unit_id. User must have adequate permissions to view Unit :

• User must have Super Mega Admin Role UserRole
• User must have Block Manager Role UserRole for the same Agent that the Unit belongs to.
• User must have Unit Owner Role UserRole and own the Unit.
• User must have Third Party Role UserRole on behalf of another Unit Owner Role UserRole that has access to the Unit.

• User must have Resident Role UserRole that belongs to the Unit.

• User with Super Mega Admin Role UserRole can view all units.

• User with Block Manager Role UserRole for the same Agent that the Unit belongs to.

• User with Unit Owner Role UserRole and own the Unit.

• User with Third Party Role UserRole on behalf of another Unit Owner Role UserRole that has access to the Unit.

• User with Resident Role UserRole that belongs to the Unit. A resident will have a limited view of attributes. See Unit documentation for which attributes are available to a resident.

GET https://api.myblockman.ie/v2/:agent_url/units/:unit_id

GET https://api.myblockman.co.uk/v2/:agent_url/units/:unit_id

URL Parameters

Parameter	Type	Description	Notes
agent_url	String	Agent url - unique identifier
unit_id	int	Unique id for the Unit

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects

Supported Includes (Relationship expand)

Parameter	Description
user	User who owns the unit
block	Block associated with unit
ground_rent_landlord	Ground Rent Landlord, UK only

Response

HTTP Status	HTTP Body	Description
200	A Unit Object	API found your unit and you have permission to view it.
403	Error Object	You do not have permission to view Unit. View error message in response for further details.
404	Error Object	Unit with unit_id not found. View error message in response for further details.

List/Search Block Units

Sample Angular Typescript List Units Belonging to a Block Request

public listBlockUnits(blockId): Observable<Unit[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders(
      {
        'Content-Type': 'application/json',
        Authorization: localStorage.getItem('session_token')
      }
    )
  };

  return this.http.get<Unit[]>(
    `${environment.API_URL}/v2/${agentUrl}/blocks/${blockId}/units/search`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return Unit.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List Units Response

HTTP/1.1 200 OK
{
  "data": [
    ... # List of Unit Objects!
  ],
  "meta": {
    "pagination": { ... },
    "sort": [ ... ],
    "filters": { ... }
  },
  "links": { ...}
}

Finds all units associated with this User and specified Block. User must have adequate permissions to view Block :

• User has Super Mega Admin Role UserRole will see all units in Block.
• User has Block Manager Role UserRole will see all units in Block.
• User has Unit Owner Role UserRole - will only see units in Block they own.
• User has Third Party Role UserRole - will only see units in Block they have access to via their linked Unit Owner.
• User hasResident Role UserRole - will only see units in Block they are residents of.

GET|POST https://api.myblockman.ie/v2/:agent_url/blocks/:block_id/units/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/blocks/:block_id/units/search

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier
block_id	Integer	Block which the units belong to

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects
sort	SortParams	no	sort results. Default is ['unit_name']
filter	FilterParams	no	filter results.
page	PaginationParams	no	Pagination Params. Default is 20 per page.

Supported Includes (Relationship expand)

Parameter	Description
user	User who owns the unit
block	Block associated with unit
ground_rent_landlord	Ground Rent Landlord, UK only

Supported Filters

Parameter	Type	Description
quick_search_cont	String	Searches Unit Code, Unit Name, Lessee Name, Unit Owner User's Email, Residents' First Names, Residents' Last Names, Residents' Emails

Supported Sorting

Parameter	Description
unit_name	Sort by unit name asc
-unit_name	Sort by unit name desc

Response

HTTP Status	HTTP Body	Description
200	Array of Unit Objects with pagination meta	API found your units and you have permission to view them.
403	Error Object	You do not have permission to view Units in this Agent. View error message in response for further details.

Users

Get Current Logged-In User

Sample Javascript Get Current Logged-In User Request

public getCurrentUser(): Observable<User> {
  const requestOptions = {
    headers: new HttpHeaders(
      {
        'Content-Type': 'application/json',
        Authorization: localStorage.getItem('session_token')
      }
    )
  };

  return this.http.get<User>(
    `${environment.API_URL}/v2/me`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return User.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript Get Current Logged-In User Response

HTTP/1.1 200 OK
{
  "data": {
    "id": "142738",
    "type": "user",
    "attributes": {
      "email": "wl_demo_owner_a@topfloor.ie",
      "created_at": "2024-06-24T12:41:52.666Z",
      "updated_at": "2025-07-27T17:16:38.629Z"
    },
    "relationships": {
      "user_roles": {
        "data": [
          {
            "id": "146243",
            "type": "user_role"
          },
          {
            "id": "146239",
            "type": "user_role"
          }
        ]
      }
    },
    "meta": {}
  },
  "included": [
    {
      "id": "146243",
      "type": "user_role",
      "attributes": {
        "resources": {
          "block_ids": [
            3
          ]
        },
        "role_type": 4,
        "permissions": {},
        "name": null,
        "created_at": "2024-06-24T14:24:58.003Z",
        "updated_at": "2024-06-24T14:24:58.003Z"
      },
      "relationships": {
        "agent": {
          "data": {
            "id": "1",
            "type": "agent"
          }
        },
        "user": {
          "data": {
            "id": "142738",
            "type": "user"
          }
        },
        "user_role": {
          "data": null
        }
      }
    },
    {
      "id": "146239",
      "type": "user_role",
      "attributes": {
        "resources": {
          "unit_ids": [
            136673
          ],
          "block_ids": [
            3
          ]
        },
        "role_type": 0,
        "permissions": {},
        "name": null,
        "created_at": "2024-06-24T12:41:52.877Z",
        "updated_at": "2024-06-24T12:41:52.877Z"
      },
      "relationships": {
        "agent": {
          "data": {
            "id": "1",
            "type": "agent"
          }
        },
        "user": {
          "data": {
            "id": "142738",
            "type": "user"
          }
        },
        "user_role": {
          "data": null
        }
      }
    }
  ]
}

Finds and displays Current Logged-In User that is associated with the Authorization Header token.

The response always contains "included" user_roles. The included response format also follows JSON API spec

Note this api does not require agent_url in the route.

GET https://api.myblockman.ie/v2/me

GET https://api.myblockman.co.uk/v2/me

URL Parameters

Parameter	Type	Description

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects. Default is ['user_roles']

Supported Includes (Relationship expand)

Parameter	Description
user_roles	UserRole
user_roles.agent	UserRole->Agent

Response

HTTP Status	HTTP Body	Description
200	A User Object	Current Logged in User
403	Error Object	You do not have permission to view User. View error message in response for further details.

Update Current Logged-In User

Sample Javascript Update Current Logged-In User

public updateCurrentUser(newPassowrd: string): Observable<User> {
  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  const body = {password: newPassword};

  return this.http.put<User>(
  `${environment.API_URL}/v2/me`,
    body,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return User.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript Update Current Logged-In User

HTTP/1.1 200 OK
{
   "data": ... # User Object
}

Updates Current Logged-In User that is associated with the Authorization Header token.

Note this api does not require agent_url in the route.

PUT/PATCH https://api.myblockman.ie/v2/me

PUT/PATCH https://api.myblockman.co.uk/v2/me

URL Parameters

Parameter	Type	Description

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	User Session Auth Token

Body Parameters

Parameter	Type	Required	Description
user	Object	yes	user object with updated attributes

User Update Object

Parameter	Type	Required	Description
password	String	no	new user password. must have at least 1 lower case character (a b c ...) must have at least 1 upper case character (A B C ...) must have at least 1 numerical digit (0 1 2 3 ...) must have at least 1 symbol (!£€$%^&*()-_+=[]{};#:@~,.

Response

HTTP Status	HTTP Body	Description
200	A User Object	Current Logged in User
400	Error Object	Unpermitted parameters were in PUT/PATCH data. View error message in response for further details.
422	validation errors	There is a problem with user input, parse and display validation errors so user can correct their form inputs.
403	Error Object	You do not have permission to view User. View error message in response for further details.

User Roles

List/Search Third-Party UserRoles of Current Logged-In User

Sample Angular Typescript List Third-Party UserRoles of Current Logged-In User Request

public listThirdPartyUserRoles(): Observable<UserRole[]> {
  const agentUrl = ...

  const requestOptions = {
    headers: new HttpHeaders({
      'Content-Type': 'application/json',
      Authorization: localStorage.getItem('session_token')
    })
  };

  return this.http.get<UserRole[]>(
    `${environment.API_URL}/v2/${agentUrl}/me/third_party_users/search`,
    requestOptions
  )
  .pipe(
    catchError(this.handleError),
    map((resData: any) => {
      return UserRole.Deserialize(resData.data, resData.included);
    })
  );
}

Sample Javascript List Third-Party UserRoles of Current Logged-In User Response

HTTP/1.1 200 OK
{
  "data": [
    ... # List of UserRole Objects!
  ],
  "meta": {
    "pagination": { ... },
    "sort": [ ... ],
    "filters": { ... }
  },
  "included": [
    ... # List of User Objects (by default)
  ],
  "links": { ...}
}

Finds all users who have third-party access to curent user:

• User has Unit Owner Role UserRole - will see all of its third-party users.

GET|POST https://api.myblockman.ie/v2/:agent_url/me/third_party_users/search

GET|POST https://api.myblockman.co.uk/v2/:agent_url/me/third_party_users/search

URL Parameters

Parameter	Type	Description
agent_url	String	Agent url - unique identifier

Header Parameters

Parameter	Type	Required	Description
Authorization	String	yes	Authorization Token

Query Parameters

Parameter	Type	Required	Description
include	IncludeParams	no	expand relationships to full json objects. Default is ['user']
sort	SortParams	no	sort results. Default is ['updated_at']
page	PaginationParams	no	Pagination Params. Default is 20 per page.

Supported Includes (Relationship expand)

Parameter	Description
user	User

Supported Sorting

Parameter	Description
updated_at	Updated At ascending
-updated_at	Updated At descending

Response

HTTP Status	HTTP Body	Description
200	Array of UserRole Objects with pagination meta	API found your UserRoles and you have permission to view them.
403	Error Object	You do not have permission to view Users in this Agent. View error message in response for further details.

Resources

Agent

Sample Agent JSON Object

{
    "id": 1,
    "type": "agent",
    "attributes": {
        "url": "some-agent",
        "name": "Some Agent",
        "address": "123 Some Block, Co. Goodcity, Ireland",
        "email": "someagent@example.com",
        "website": "someagent.xyz",
        "default_phone": "01 344 1111",
        "emergency_phone": "01 344 1112",
        "licence_number": "1234567A",
        "disabled": false,
        "country": 0,
        "external_payment_portal_url": "https://someagent.xyz/payment_portal",
        "external_payment_portal_url_instruction": "Pay through this link",
        "company_logo_urls": {
            "website_tiny": "http://minio.myblockmanapi.tfloc.net:59000/myblockman-development-public-read/agents/company_logos/000/000/068/695d5d660eee3a9ba303ad0882a47f386cf0b06b.png?1685540211",
            "website_small": "http://minio.myblockmanapi.tfloc.net:59000/myblockman-development-public-read/agents/company_logos/000/000/068/13da7bf0520e4191b620ae14e389efb332c7542b.png?1685540211",
            "website_medium": "http://minio.myblockmanapi.tfloc.net:59000/myblockman-development-public-read/agents/company_logos/000/000/068/88a5423f5179497cdb112e8b3443397dfde4a046.png?1685540211",
            "website_large": "http://minio.myblockmanapi.tfloc.net:59000/myblockman-development-public-read/agents/company_logos/000/000/068/73293326ebfb8c6d65d3180d89d2b296ee73a4a5.png?1685540211",
            "email": "http://minio.myblockmanapi.tfloc.net:59000/myblockman-development-public-read/agents/company_logos/000/000/068/d0e2e0ff88f00d4272dc1154eeaff8b1cd826dc0.png?1685540211",
            "original": "http://minio.myblockmanapi.tfloc.net:59000/myblockman-development-public-read/agents/company_logos/000/000/068/1e1a8419aec6369ddc51abd1d8d2066d64f1783c.png?1685540211"
        },
        "created_at": "2023-05-09T16:50:07.356Z",
        "updated_at": "2023-10-02T18:29:55.560Z"
    }
}

Summary

This resource holds the managing agent's information.

country enum should be used to determine differentiating logic in some front end features e.g:

• Formatting monetary values with the correct currency symbol e.g. Ireland uses € , United Kingdom uses £
• Access to certain sub-features e.g. Viewing Ground Rent details is a United Kingdom only feature.

If disabled is true, no user associated with that agent will be allowed to login. Any login attempts will be blocked with a 217 error code returned.

Attributes

Name	Type	Description
url	String	Agent's Unique Identifier in Myblockman
country	ENUM	Agent Country
name	String	Agent Name
disabled	Boolean	Agent Enabled/Disabled in Myblockman
address	String | null	Agent Address
email	String | null	Agent email
website	String | null	Agent website
default_phone	String | null	Agent Phone Number
emergency_phone	String | null	Agent Emergency Phone Number
licence_number	String | null	Agent PSRA in Ireland
external_payment_portal_url	String | null	Agent External Payment URL
external_payment_portal_url_instruction	String | null	Agent External Payment URL Instruction
company_logo_urls	Object | null	Agent Company Logo URLs in various sizes
created_at	String	Timestamp this database entry was created. format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	String	Timestamp this database entry was last updated. format: yyyy-mm-ddThh:mm:ss.mmmZ

Conditional Attributes 1 - Only present if user is logged in

Name	Type	Description
show_block_service_charge_bank_details	Boolean	Indicator if bank details should be displayed on service charge payment instruction page
show_ground_rent_landlord_bank_details	Boolean	Indicator if bank details should be displayed on ground rent payment instruction page
is_cheque_accepted	Boolean	Indicator if cheque details should be displayed on service charge payment instruction page
external_payment_portal_url_myblockman_payload_enabled	Boolean	Indicator if external payment url should be displayed

Conditional Attributes 2 - Only present if user is Block Manager

Name	Type	Description
import_blockman_issues_enabled	Boolean	Indicates if issues will be imported from blockman
blockman_issue_notifications_enabled	Boolean	Indicator if changes to issues will trigger notification emails
statement_background_image_enabled	Boolean	Indicator if uploaded statement background image will be used on generated statement PDFs
external_payment_portal_url_myblockman_payload_key	String	Private encryption key used to encrypt payloads for external payment portal URLs
email_greeting_format	String	Greeting template string for email notifications
statement_background_image	SecureFileDownload | null	Object Containing statement background image data

Country ENUM

Value	Type	Description
0	IRELAND
1	UNITED_KINGDOM

Company Logo URLs

The company_logo_urls object contains the following attributes:

Name	Type	Description
website_tiny	String	60px x 60px with the image centre around transparent padding fill
website_small	String	80px x 80px with the image centre around transparent padding fill
website_medium	String	160px x 160px with the image centre around transparent padding fill
website_large	String	320px x 320px with the image centre around transparent padding fill
email	String	175px x 100px with the image centre around transparent padding fill
original	String	Original uploaded image

AuthToken

Sample AuthToken JSON Object

{
  "id": "...",
  "type": "auth_token",
  "attributes": {
    "token": "128_character_token"
  }
}

Summary

This resource holds the AuthToken information. An AuthToken is created whenever a client logs in as a User. It auto-expires after 30 minutes of inactivity. See Logging in for details.

Attributes

Name	Type	Description
token	String	The token that should be passed into the Authorization header.

Announcement

Sample Announcement JSON Object

{
  "id": "7",
  "type": "announcement",
  "attributes": {
    "title": "Some New Event is Happening Soon",
    "publish_at": "2025-01-09T00:00:00.000Z",
    "is_read_only": false,
    "resident_can_view": false,
    "is_published": true,
    "is_global": true,
    "html_content_status": 0,
    "html_content_status_updated_at": "2025-06-12T14:07:45.598Z"
    "created_at": "2025-01-08T14:23:02.019Z",
    "updated_at": "2025-06-12T14:07:45.814Z",
    "content": {
      "delta":"{\"ops\":[{\"insert\":\"te\"},{\"attributes\":{\"link\":\"about:blank\"},\"insert\":\"stt\<hr\>\"},{\"insert\":\"\\n\"}]}",
      "html": "<div>\n  <p>te<a href=\"about:blank\" target=\"_blank\">stt&lt;hr&gt;</a></p>\n</div>"
    }
  }
}

Summary

This resource holds an Annoucement content. An Annoucement can be associated to one or many Blocks, and it is intended to be used like a newsletter or notice board, to inform unit owners or residents of any news/updates about their Block.

Attributes

Name	Type	Description
title	String	Title/headline of the announcement
publish_at	String	Timestamp when this is to be published on myblockman. format: yyyy-mm-ddThh:mm:ss.mmmZ
is_read_only	Boolean	This announcement is not editable. Announcements that were imported from old MyBlockman have no delta_content so we have no data to open in the editor
resident_can_view	Boolean	Whether residents are permitted to view this announcement
is_published	Boolean	Whether publish_at is in the past or today
is_global	Boolean	A global announcement is displayed on all Blocks
html_content_status	enum	Status Of HTML Generation 0 = Ready 1 = Processing 2 = Error
html_content_status_updated_at	String	Timestamp this the html_content_status was last updated. format: yyyy-mm-ddThh:mm:ss.mmmZ
content	Content Object	object containing html and delta json content. Will be null unless include_content=true param is passed
created_at	String	Timestamp this database entry was created. format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	String	Timestamp this database entry was last updated. format: yyyy-mm-ddThh:mm:ss.mmmZ

Content Object Attributes

HTML and DELTA json conent is expensive for server to render and for the client to parse. It is only available for the GET Announcement API and only if the include_content=true param is passed in.

Name	Type	Description
delta_content	String | null	Delta encoding of the content. See Quil reference
html_content	String | null	HTML encoding of the content

Relationships

... This moel does not support any relationships ...

Permission Requirements

Users must have adequate permissions to view Announcements:

• Super Mega Admin Role: Can view all announcements
• Block Manager Role: Can view all announcements
• Unit Owner Role: Can view all announcements in a block where they own a unit
• Third Party Role: Can view all announcements in a block where parent role is unit owner
• Resident Role: Can only view announcements where resident_can_view is true

Block

Sample Block JSON Object

{
  "id": 5,
  "type": "block",
  "attributes": {
    "block_name": "The Oaks Development",
    "company_name": "The Oaks Management CLG",
    "address": "123 Green Lane, Oakville, County Dublin",
    "website": "www.demo.topfloor.ie",
    "email": "info@demo.topfloor.ie",
    "is_blockman_export_lease_schedules": true,
    "created_at": "2024-01-10T14:30:00.000Z",
    "updated_at": "2025-03-15T10:00:00.000Z",
    "block_picture": {
        "tiny": "SIGNED_EXPIRING_S3_URL",
        "small": "SIGNED_EXPIRING_S3_URL",
        "medium1": "SIGNED_EXPIRING_S3_URL",
        "medium2": "SIGNED_EXPIRING_S3_URL",
        "large": "SIGNED_EXPIRING_S3_URL",
        "original": "SIGNED_EXPIRING_S3_URL"
    },
    // Conditional Bank Attributes
    "current_bank_account_branch_name_and_address": "Main Street Branch, Exampletown",
    "current_bank_account_bic": "BOFIXXXX",
    "current_bank_account_sort_code": "900000",
    "current_bank_account_iban": "IE00BOFI90000012345678",
    "current_bank_account_number": "12345678",
    "current_bank_account_name": "The Oaks Management CLG Service Charge Account",
    // Conditional Non-Resident Attributes
    "unit_type_apartment_count": 50,
    "unit_type_duplex_count": 10,
    "unit_type_house_count": 5,
    "unit_type_car_space_count": 65,
    "unit_type_commercial_count": 2,
    "ct1_number": "CT12345",
    "vat_number": "IE9876543W",
    "number_of_units": 67,
    "governance_type": "Board Of Directors",
    "limited_by_type": "Guarantee",
    "company_registration_number": "600123",
    "registered_office_address": "45 Corporate Road, Business Park, Dublin 2",
    "annual_return_date_day": 15,
    "annual_return_date_month": 9,
    "secretary_name": "Corporate Secretaries Ltd.",
    "is_ground_rent_activated": false,
    "financial_year_start_on": "2025-01-01",
    "incorporation_date": "2010-06-01",
    "secretary_appointed_on": "2010-07-01",
  },
  "relationships": {
      "block_manager": {
        "data": { 
          "id": 3, 
          "type": "block_manager" 
        }
      }
  },
  "meta": {
    "block_directors_count": 3,
    "block_committee_members_count": 1,
    "block_meetings_count": 4,
    "block_documents_count": 27,
    "director_documents_count": 3,
    "ground_rent_landlords_count": 1,
    "residents_count": 56
  }
}

Summary

This resource holds the Block information. A Block represents an apartment block (or similar property development) and the connected management company.

Attributes

Name	Type	Description
block_name	string	Name of the block/development
company_name	string	Registered company name for the block's management company
address	string	Physical address of the block/development
website	string | null	Website URL for the block
email	string | null	Contact email address for the block
created_at	string	Timestamp this database entry was created. format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	string	Timestamp this database entry was last updated. format: yyyy-mm-ddThh:mm:ss.mmmZ
block_picture	Block Picture Object	URLs for different sizes of the block's picture.

Block Picture Object

API supplys Signed S3 URLs that a valid for 120 second to be used as <img src="X" />

Name	Type	Description
tiny	string	URL to 60px by 60px image
small	string	URL to 80px by 80px image
medium1	string	URL to 140px by 140px image
medium2	string	URL to 160px by 160px image
large	string	URL to 320px by 320px image
original	string	URL to orginal uploaded image

Conditional Attributes - Only present if user is Block Manager, Unit Owner or a Third Party to a Unit Owner

Name	Type	Description
current_bank_account_branch_name_and_address	string | null	Bank details for service charge payments
current_bank_account_bic	string | null	Bank details for service charge payments
current_bank_account_sort_code	string | null	Bank details for service charge payments
current_bank_account_iban	string | null	Bank details for service charge payments
current_bank_account_number	string | null	Bank details for service charge payments
current_bank_account_name	string | null	Bank details for service charge payments
unit_type_apartment_count	Integer	Count of apartment type units
unit_type_duplex_count	Integer	Count of duplex type units
unit_type_house_count	Integer	Count of house type units
unit_type_car_space_count	Integer	Count of car space type units
unit_type_commercial_count	Integer	Count of commercial type units
ct1_number	String	CT1 number for the block
vat_number	String	VAT registration number
number_of_units	Integer	Total number of units in the block
governance_type	ENUM	Governance structure of the block
limited_by_type	ENUM	How the management company is limited
company_registration_number	String	Company Registration Office (CRO) number if Ireland, Companies house number if UK
registered_office_address	String	Registered office address of the management company
annual_return_date_day	Integer	Day of the month for annual return
annual_return_date_month	Integer	Month for annual return (1-12)
secretary_name	String	Name of the company secretary
is_ground_rent_activated	Boolean	Indicates if ground rent is activated for this block
financial_year_start_on	String	Start date of the financial year. format yyyy-mm-dd
incorporation_date	String | null	Date the management company was incorporated. format yyyy-mm-dd
secretary_appointed_on	String	Date the company secretary was appointed

Relationships

Name	Type	Description	Notes
block_manager	BlockManager	The assigned BlockManager to this Block

Meta

Name	Type	Description
none

Conditional Meta - Only present if user is Block Manager, Unit Owner or a Third Party to a Unit Owner

Name	Type	Description
block_directors_count	Integer	Count of block directors
block_committee_members_count	Integer	Count of block committee members
block_meetings_count	Integer	Count of block meetings
block_documents_count	Integer	Count of block documents
director_documents_count	Integer	Count of director documents
ground_rent_landlords_count	Integer	Count of ground rent landlords directors
residents_count	Integer	Count of residents

Governance Types ENUM

Value	Type	Description
0	GOVERNANCE_OF_DIRECTORS	Board Of Directors
1	COUNCIL_OF_MANAGEMENT	Council Of Management
2	GOVERNING_BODY	Governing Body

Limited By Types ENUM

Value	Type	Description
0	GUARANTEE	Guarantee
1	SHARE_CAPITAL	Share Capital
2	NO_SECRETARIAL	No Secretarial

BlockDocument

Sample BlockDocument JSON Object

{
  "id": "123",
  "type": "block_document",
  "attributes": {
    "category_name": "AGM Minutes",
    "notes": "Annual General Meeting minutes from 2025",
    "document_date": "2025-01-15",
    "resident_can_view": true,
    "created_at": "2025-01-16T10:30:00.000Z",
    "updated_at": "2025-01-16T10:30:00.000Z",
    "file": {
        "download_url": "https://...",
        "file_name": "agm_minutes_2025.pdf",
        "file_size": 2048576,
        "updated_at": "2025-01-16T10:30:00.000Z"
    }
  },
  "relationships": {   
    "block": {
      "data": { "id": "1", "type": "block" }
    }
  }
}

Summary

This resource holds the BlockDocument information. A BlockDocument represents documents associated with a Block, such as AGM minutes, financial reports, or other block-related documentation.

Attributes

Name	Type	Description
category_name	String	The category or type of document
notes	String | null	Additional notes or description about the
file	SecureFileDownload	Object Containing file attachment data
document_date	String	The date associated with the document. Format: yyyy-mm-dd ~Optional
resident_can_view	Boolean	Whether residents are permitted to view this document
created_at	String	Timestamp this database entry was created. format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	String	Timestamp this database entry was last updated. format: yyyy-mm-ddThh:mm:ss.mmmZ

Relationships

Name	Type	Description
block	Block	The Block this BlockDocument is associated with

Permission Requirements

Users must have adequate permissions to view BlockDocuments:

• Super Mega Admin Role: Can view all block documents
• Block Manager Role: Can view all block documents
• Unit Owner Role: Can view all block documents in a block where they own a unit
• Third Party Role: Can view all block documents in a block where parent role is unit owner
• Resident Role: Can only view documents where resident_can_view is true

BlockManager

Sample BlockManager JSON Object

{
  "id": 5,
  "type": "block_manager",
  "attributes": {
    "name": "Administrator",
    "email": "sometestemail@topfloor.ie",
    "phone": "",
    "created_at": "2023-05-09T17:06:24.082Z",
    "updated_at": "2023-05-09T17:06:24.082Z"
  },
  "relationships": {
    "user": {
      "data": { 
        "id": 3, 
        "type": "user" 
      }
    }
  },
  "meta": {
    "blocks_count": 5
  }
}

Summary

This resource holds the BlockManager information. A BlockManager belongs to an Block and is intended to be the point of contact for any queries related to the Block.

Attributes

Name	Type	Description
name	String	The BlockManager name
email	String	The BlockManager email
phone	String	The BlockManager phone
created_at	String	Timestamp this database entry was created. format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	String	Timestamp this database entry was last updated. format: yyyy-mm-ddThh:mm:ss.mmmZ

Relationships

Name	Type	Description
user	User	Optional user association with block manager.Might be null if myblockman account doesn't exist

Meta

Name	Type	Description
blocks_count	Integer	Number of blocks managed by this BlockManager. Not visible to unit owners and residents

BlockMeeting

Sample BlockMeeting JSON Object

{
  "id": "1",
  "type": "block_meeting",
  "attributes": {
    "meeting_type": 0,
    "venue_address": "Conference Room A, 123 Main Street, Dublin 1",
    "notice_description": "Notice is hereby given that the Annual General Meeting will be held...",
    "created_at": "2025-01-15T10:00:00.000Z",
    "updated_at": "2025-01-15T10:00:00.000Z",
    "meeting_date": "2025-02-15 14:00",
    "notice_date": "2025-02-01 12:00",
    "minutes_description": "Minutes of the Annual General Meeting held on...",
    "notice": { // if notice file exists
      "download_url": "https://some-s3-link.to/block_meetings/notice/1234", // if generate_download_url=true param is passed
      "file_name": "6219_Some_Block_Name_Log_Details__Venue_Date_01Apr2021___19_00_NOTICE.pdf",
      "file_size": 10320,
      "updated_at": "2025-04-02T11:09:35.983Z"
    },
    "minutes": { // if minutes file exists
      "download_url": "https://some-s3-link.to/block_meetings/minutes/1234", // if generate_download_url=true param is passed
      "file_name": "6219_Some_Block_Name_Log_Details__Venue_Date_01Apr2021___19_00_MINUTES.pdf",
      "file_size": 8904,
      "updated_at": "2025-04-02T11:09:35.736Z"
    }
  },
  "relationships": {
    "agent": {
      "data": {
        "id": "1",
        "type": "agent"
      }
    },
    "block": {
      "data": {
        "id": "7",
        "type": "block"
      }
    }
  },
  "meta": {
    "notice_exists": true,
    "minutes_exists": true
  }
}

This resource holds the BlockMeeting information. A BlockMeeting represents various types of meetings held for a Block (AGM, EGM, Directors meetings, etc.).

A Block meeting has two file attachments. See Secure File Downloads for more detail on how to implement document downloads in the frontend.

• notice - This document should be present before the meeting_date to inform unit owners of details about the meeting such as venue, date, agenda, voting details, etc . Sometimes the customer/agent decides not to attach a notice document in which case notice_exists will be false.
• minutes - This document will be present some time after the meeting_date. It will be a write up of the events discussed at the meeting. Sometimes the customer/agent decides not to attach a notice document in which case minutes_exists will be false.

Attributes

Property	Type	Description
meeting_type	ENUM	Type of meeting
venue_address	String	Address where the meeting will be/was held
meeting_date	String	Date and time of the meeting. Format: yyyy-mm-dd HH:MM
notice_description	String	Description of the meeting notice
notice_date	String	Date and time the notice was issued. Format: yyyy-mm-dd HH:MM
notice	SecureFileDownload	Usually a JPEG or PDF file containing details about the meeting venue,agenda
minutes_description	String | null	Description of the meeting minutes
minutes	SecureFileDownload	Usually a JPEG or PDF file containing minutes record of the meeting after the event
created_at	String	Timestamp this database entry was created. format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	String	Timestamp this database entry was last updated. format: yyyy-mm-ddThh:mm:ss.mmmZ

Meeting Types ENUM

Value	Type	Description
0	AGM	Annual General Meeting
1	EGM	Extraordinary General Meeting
2	Directors	Directors Meeting
3	Residents Committee	Residents Committee Meeting

Meta data

Property	Type	Description
notice_exists	Boolean	Whether a notice document has been uploaded
minutes_exists	Boolean	Whether minutes document has been uploaded

Relationships

Property	Type	Description
agent	Agent	The Agent this BlockMeeting belongs to
block	Block	The Block this BlockMeeting is for

DirectorDocument

Sample DirectorDocument JSON Object

{
  "id": 127,
  "type": "director_document",
  "attributes": {
    "title": "Some Magical Title",
    "notes": "",
    "document_date": "2018-07-28",
    "created_at": "2018-01-01T12:00:00.000Z",
    "updated_at": "2018-05-06T15:23:00.000Z",
    "file": {
      "download_url": "https://...",
      "file_name": "director_meeting_minutes_2018.pdf",
      "file_size": 1024576,
      "updated_at": "2018-05-06T15:23:00.000Z"
    }
  },
  "relationships": {   
    "block": {
      "data": { "id": "1", "type": "block" }
    }
  }
}

Summary

This resource holds the DirectorDocument information. A DirectorDocument belongs to a Block and contains important director-related documentation.

Attributes

Name	Type	Description
title	String	The DirectorDocument title
notes	String	The DirectorDocument notes
document_date	String	The DirectorDocument date. format: yyyy-mm-dd
created_at	String	Timestamp this database entry was created. format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	String	Timestamp this database entry was last updated. format: yyyy-mm-ddThh:mm:ss.mmmZ
file	SecureFileDownload	Object Containing file attachment data

Relationships

Name	Type	Description
block	Block	The Block the DirectorDocument belongs to

Permission Requirements

Users must have adequate permissions to view DirectorDocument:

• Super Mega Admin Role: Can view all director documents
• Block Manager Role: Can view all director documents for all blocks
• Director Role: Can view all director documents for a specific block tied to the UserRole
• Third Party Role: Can view all director documents for a specific block if parent role is a Director Role

EmergencyContact

Sample EmergencyContact JSON Object

{
  "id": 1,
  "type": "emergency_contact",
  "attributes": {
    "contact_type": "Keyholder",
    "name": "Emely Green",
    "phone": "0831234567",
    "email": "emelygreen@example.com",
    "created_at": "2025-05-14T16:24:23.479Z",
    "updated_at": "2025-05-14T16:24:23.479Z"
  },
  "relationships": {
    "unit": {
      "data": { 
        "id": 3, 
        "type": "unit" 
      }
    }
  }
}

This resource holds the EmergencyContact information. An EmergencyContact belongs to an Agent and Unit and contains emergency contact details.

Attributes

Name	Type	Description
contact_type	String	The EmergencyContact type
name	String	The EmergencyContact name
phone	String	The EmergencyContact phone
email	String	The EmergencyContact email
created_at	String	Timestamp this database entry was created. format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	String	Timestamp this database entry was last updated. format: yyyy-mm-ddThh:mm:ss.mmmZ

Relationships

Name	Type	Description	Notes
unit	Unit	The Unit the EmergencyContact belongs to

GroundRentLandlord

Sample GroundRentLandlord JSON Object

{
  "id": "11",
  "type": "ground_rent_landlord",
  "attributes": {
    "name": "Mr Daniel Foobar",
    "lease_start_date_on": "2019-01-01",
    "lease_length": 999,
    "payment_frequency_type": 0,
    "lease_review_frequency_length": 10,
    "last_charge_start_date_on": "2024-01-01",
    "last_charge_end_date_on": "2024-12-31",
    "amount_default": 250.0,
    "created_at": "2023-05-23T15:48:54.998Z",
    "updated_at": "2023-08-15T17:45:04.635Z",
    // Conditional attributes - visibility depends on user permissions
    "current_bank_account_branch_name_and_address": "HSBC\n1-3 Victoria Square\nBolton\nBL1 1RJ",
    "current_bank_account_bic": "",
    "current_bank_account_sort_code": "401225",
    "current_bank_account_iban": "",
    "current_bank_account_number": "12345678",
    "current_bank_account_name": "Mr Daniel Foobar"
  },
  "relationships": {
    "block": {
      "data": {
        "id": "56",
        "type": "block"
      }
    }
  }
}

Summary

Available for UK agents only. This resource holds the GroundRentLandlord information. It details the Landlord or freeholder of the land who would collect ground rent from the leaseholders or Unit owners at specific time intervals.

Attributes

Name	Type	Description	Notes
name	String	Name of the Ground Rent Landlord
lease_start_date_one	String	Start date of the Lease of the land	Date format: yyyy-mm-dd
lease_length	Integer	Duration of the Lease in years
payment_frequency_type	Integer	Payment Frequency: 0: Yearly 1: Half Yearly 2: Quarterly 3: English Quarter Rent Days 4: English Half Yearly Rent Days 5: English Yearly Rent Day
lease_review_frequency_length	Integer	Frequency of Lease review in years
last_charge_start_date_on	String	Last Charge Start Date	Date format: yyyy-mm-dd
last_charge_end_date_on	String	Last Charge End Date	Date format: yyyy-mm-dd
amount_default	Decimal	Default Annual Rent Payable
created_at	String	Timestamp this database entry was created. format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	String	Timestamp this database entry was last updated. format: yyyy-mm-ddThh:mm:ss.mmmZ

Conditional Attributes - Only present if user is Block Manager, Unit Owner or a Third Party of a Unit Owner

Name	Type	Description	Notes
current_bank_account_branch_name_and_address	String	Bank account branch name and address
current_bank_account_bic	String	Bank account BIC
current_bank_account_sort_code	String	Bank account sort code
current_bank_account_iban	String	Bank account IBAN
current_bank_account_number	String	Bank account number
current_bank_account_name	String	Bank account name

Relationships

Name	Type	Description	Notes
block	Block	The Block this GroundRentLandlord is part of

Meta

Name	Type	Description
none

Issue

Sample Issue JSON Object

{
  "data": {
    "id": "456",
    "type": "issue",
    "attributes": {
      "issue_reference_number": 2024001,
      "status": 0,
      "category": "Plumbing",
      "reported_at": "2024-01-15T09:30:00.000Z",
      "status_at": "2024-01-15T09:30:00.000Z",
      "created_at": "2024-01-15T09:30:00.000Z",
      "updated_at": "2024-01-15T09:30:00.000Z",
      "status_by": "Block Manager",
    },
    "relationships": {
      "unit": {
        "data": { "id": "123", "type": "unit" }
      }
      "issue_actions": [...]
    },
    "meta": {
      "issue_actions_count": 3
    }
  }
}

Summary

This resource holds the Issue information. An Issue represents a maintenance request, complaint, or other matter related to a specific Unit that requires attention or resolution.

Attributes

Name	Type	Description
issue_reference_number	int	Unique reference number for the issue
status	ENUM	Current status of the issue
category	String	Category or type of issue
reported_at	String	Timestamp when the issue was originally reported. format: yyyy-mm-ddThh:mm:ss.mmmZ
status_at	String	Timestamp when the current status was last updated. format: yyyy-mm-ddThh:mm:ss.mmmZ
created_at	String	Timestamp this database entry was created. format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	String	Timestamp this database entry was last updated. format: yyyy-mm-ddThh:mm:ss.mmmZ

Status ENUM

Value	Type	Description
0	OPEN_CURRENT	Issue is open and most recent action was less than 31 day ago
1	OPEN_31_DAYS_PLUS	Issue is open and most recent action is more than 31 day ago
2	RESOLVED	Issue is resolved
3	TO_WORKS_ORDER	Issue has been sent as works order to a contractor

Relationships

Name	Type	Description
agent	Agent	The Agent this Issue belongs to
unit	Unit	The Unit this Issue is associated with
issue_actions	IssueActions	an issue has_many issue actions

Meta

Name	Type	Description
issue_actions_count	Integer	Number of actions associated with this issue

IssueAction

Sample IssueAction JSON Object

{
  "data": {
    "id": "60",
    "type": "issue_action",
    "attributes": {
      "action_at": "2025-01-25T04:11:55.473Z",
      "created_at": "2025-07-28T16:10:34.232Z",
      "updated_at": "2025-07-28T16:10:34.232Z"
    },
    "relationships": {
      "issue": {
        "data": {
          "id": "1",
          "type": "issue"
          }
      }
    },
    "meta": null
  }
}

Summary

This resource holds the IssueAction information. At this time, it is only really a holder for the action_at timestamp. It will be expanded in the future with more functionality.

Attributes

Name	Type	Description
action_at	String	Timestamp when the action was performed. format: yyyy-mm-ddThh:mm:ss.mmmZ
created_at	String	Timestamp this database entry was created. format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	String	Timestamp this database entry was last updated. format: yyyy-mm-ddThh:mm:ss.mmmZ

Relationships

Name	Type	Description

issue | issue | parent issue |

Meta

Name	Type	Description

none

Job

Sample Job JSON Object

{
  "id": "a63f8149-0bfc-4081-809b-9fb6e50ac714",
  "type": "job",
  "attributes": {
    "job_id": "a63f8149-0bfc-4081-809b-9fb6e50ac714",
    "provider_job_id": "71e7ea40b8818698cc95a2c4"
  }
}

Summary

This resource holds the Job information. A Job object represents an asynchronous background-job to be processed by another application (named Sidekiq). There's no guarantee that this job will be processed immediately, as it depends on how many jobs there are in the queue, and if the job is scheduled to be processed on a specified time instead.

Attributes

Name	Type	Description	Notes
job_id	String	The unique job ID (from the perspective of Rails)
provider_job_id	String	The unique job ID (from the perspective of the provider, in this case: Sidekiq)

Resident

Sample Resident JSON Object

{
  "id": 1,
  "type": "resident",
  "attributes": {
    "first_name": "Emely",
    "last_name": "Green",
    "email": "emelygreen@example.com",
    "phone": "0831234567",
    "created_at": "2025-05-14T16:24:23.479Z",
    "updated_at": "2025-05-14T16:24:23.479Z"
  },
  "meta": {
    "has_myblockman_account": true
  },
  "relationships": {
    "unit": {
      "data": {
        "id": 11,
        "type": "unit"
      }
    }
  }
}

Summary

This resource holds the Resident information. An example of a Resident is the one who lives in a unit / apartment / house. This is why a Resident is associated to a Unit

Attributes

Name	Type	Description
first_name	String	The resident's first name
last_name	String	The resident's last name
email	String	The resident's email
phone	String	The resident mobile phone number
created_at	String	Timestamp this database entry was created. format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	String	Timestamp this database entry was last updated. format: yyyy-mm-ddThh:mm:ss.mmmZ

Metadata

Name	Type	Description
has_myblockman_account	Boolean	Indicates whether the resident has an associated MyBlockman user account

Relationships

Name	Type	Description	Notes
unit	Unit	The Unit the Resident belongs to

ResidentDocument

Sample ResidentDocument JSON Object

{
  "id": "1",
  "type": "resident_document",
  "attributes": {
    "document_name": "Test Document",
    "document_date": "2024-05-16",
    "notes": "test",
    "category_name": "Some Category",
    "created_at": "2025-05-16T09:56:45.572Z",
    "updated_at": "2025-05-16T09:58:43.295Z",
    "file": {
        "download_url": "https://example.s3.amazonaws.com/path-to-resident-document-download",
        "file_name": "doc.pdf",
        "file_size": 192,
        "updated_at": "2025-05-16T09:56:45.556Z",
        "content_type": "application/pdf"
    }
  },
  "relationships": {
    "resident": {
      "data": {
        "id": "241",
        "type": "resident"
      }
    }
  }
}

Summary

This resource holds the ResidentDocument information. A ResidentDocument belongs to a Resident of a Unit.

Attributes

Name	Type	Description
document_name	String	The ResidentDocument name
document_date	String	The ResidentDocument date
notes	String	The ResidentDocument notes
category_name	String	The ResidentDocument category name
created_at	String	Timestamp this database entry was created. format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	String	Timestamp this database entry was last updated. format: yyyy-mm-ddThh:mm:ss.mmmZ
file	SecureFileDownload	Object Containing file attachment data

Relationships

Name	Type	Description
resident	Resident	The Resident the ResidentDocument belongs to

Permission Requirements

Users must have adequate permissions to view BlockDocuments:

• Super Mega Admin Role: Can view all resident documents
• Block Manager Role: Can view all resident documents
• Unit Owner Role: Can view all resident documents in a unit where they own the unit
• Third Party Role: Can view all resident documents in a unit where parent role is unit owner
• Resident Role: Can only view resident documents that are associated with their Resident

Unit

Sample Unit JSON Object

{
  "id": 11,
  "type": "unit",
  "attributes": {
    "unit_code": "A101",
    "unit_name": "Apartment 101",
    "unit_type": "Apartment",
    "number_of_bedrooms": 2,
    "floor": "1",
    "size": "75sqm",
    "build_description": "Standard apartment build",
    "mailing_name": "Mr. John Owner",
    "salutation": "Dear Mr. Owner",
    "created_at": "2025-05-14T16:24:23.479Z",
    "updated_at": "2025-05-14T16:24:23.479Z",
    // Conditional attributes - visibility depends on user permissions
    "service_charge_payment_method_type": "Direct Debit",
    "ground_rent_payment_method_type": "Annual Bill",
    "ground_rent_amount_status": "Standard",
    "ground_rent_overridden_amount": null,
    "serivce_charge_payment_reference": "SC-A101-2025",
    "ground_rent_payment_reference": "GR-A101-2025",
    "interested_parties": "Bank of Ireland",
    "lessee_name": "John Owner",
    "lessee_phone_mobile": "0871234567",
    "lessee_phone_other": "012999999",
    "lessee_other_contact_notes": "Contact via email preferably",
    "lessee_address": "123 Main Street, Dublin 1",
    "lessee_is_resident": false,
    "car_space": "Space 22",
    "lessee_email": "john.owner@example.com",
    "service_charge_balance": 150.75,
    "ground_rent_balance": 50.00,
    "encoded_service_charge_payment_data": "ENCODED_SC_PAYLOAD_STRING",
    "encoded_ground_rent_payment_data": "ENCODED_GR_PAYLOAD_STRING",
    "lease_date_on": "2020-01-15"
  },
  "relationships": {
    "user": {
      "data": {
        "id": 55,
        "type": "user"
      }
    },
    "block": {
      "data": {
        "id": 7,
        "type": "block"
      }
    },
    "ground_rent_landlord": {
      "data": { 
        "id": 3, 
        "type": "ground_rent_landlord" 
      }
    }
  },
  "meta": {
    "residents_count": 2,
    "unit_previous_owners_count": 1,
    "emergency_contacts_count": 3,
    "unit_documents_count": 8
  }
}

Summary

This resource holds the Unit information. A Unit typically represents an apartment, house, or commercial space within a Block. It is owned by a User (Unit Owner) and can have Residents.

Attributes

Name	Type	Description	Notes
unit_code	String	Code/identifier for the unit (e.g., apartment number)
unit_name	String	Display name for the unit
unit_type	String	Type of unit	Apartment, Duplex, House, Car Space, Commercial
number_of_bedrooms	int	Number of bedrooms in the unit	~Optional
floor	String	Floor number or level of the unit	~Optional
size	String	Size of the unit (e.g., "75sqm")	~Optional
build_description	String	Description of the unit build	~Optional
mailing_name	String	Name to be used for mail correspondence
salutation	String	Salutation for correspondence (e.g., "Dear Mr. Smith")
created_at	String	Timestamp this database entry was created	Date format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	String	Timestamp this database entry was last updated	Date format: yyyy-mm-ddThh:mm:ss.mmmZ

Conditional Attributes - Only present if user is Block Manager, Unit Owner or a Third Party of a Unit Owner

Name	Type	Description	Notes
service_charge_payment_method_type	String	How service charges are paid
ground_rent_payment_method_type	String	How ground rent is paid
ground_rent_amount_status	String	Status of the ground rent amount (e.g., Standard, Overridden, Exempt)
ground_rent_overridden_amount	Decimal	Overridden amount for ground rent, if applicable
serivce_charge_payment_reference	String	Payment reference for service charges
ground_rent_payment_reference	String	Payment reference for ground rent
interested_parties	String	Any interested third parties related to the unit
lessee_name	String	Name of the lessee/owner
lessee_phone_mobile	String	Mobile phone number of the lessee
lessee_phone_other	String	Other contact phone number for the lessee
lessee_other_contact_notes	String	Additional contact notes for the lessee
lessee_address	String	Postal address of the lessee
lessee_is_resident	Boolean	Indicates if the lessee is also a resident of the unit
car_space	String	Details of any associated car space(s)
lessee_email	String	Email address of the lessee (derived from associated User)
service_charge_balance	Decimal	Current service charge balance for the unit
ground_rent_balance	Decimal	Current ground rent balance for the unit
encoded_service_charge_payment_data	String	Encrypted payload for external service charge payment portal
encoded_ground_rent_payment_data	String	Encrypted payload for external ground rent payment portal
lease_date_on	String	Lease start date	Format: yyyy-mm-dd

Relationships

Name	Type	Description	Notes
user	User	The User (owner) associated with this Unit
block	Block	The Block this Unit is part of
ground_rent_landlord	GroundRentLandlord	The GroundRentLandlord for this Unit	~Optional

Meta

Name	Type	Description
none

Conditional Meta - Only present if user is Block Manager, Unit Owner or a Third Party to a Unit Owner

Name	Type	Description
residents_count	Integer	Count of residents
unit_previous_owners_count	Integer	Count of previous owners
emergency_contacts_count	Integer	Count of emergency contacts
unit_documents_count	Integer	Count of unit documents

UnitDocument

Sample UnitDocument JSON Object

{
  "id": 1,
  "type": "unit_document",
  "attributes": {
    "id": 19,
    "document_name": "Some Document Name",
    "document_date": "2024-11-04",
    "category_name": "CAR PARKING VISITORS",
    "notes": "Some Notes",
    "created_at": "2024-11-04T15:19:10.146Z",
    "updated_at": "2024-11-04T15:19:10.146Z",
    "file": {
      "download_url": "https://...",
      "file_name": "28_Apartment_1_accounts_2018_17-09-2024.jpeg",
      "file_size": 157448,
      "updated_at": "2024-11-04T15:16:02.127Z"
    }
  },
  "relationships": {
    "unit": {
      "data": {
        "id": "3885",
        "type": "unit"
      }
    }
  }
}

Summary

This resource holds the UnitDocument information. A UnitDocument belongs to a Unit.

Attributes

Name	Type	Description
document_name	String	The UnitDocument name
document_date	String	The UnitDocument date
category_name	String	The UnitDocument category name
notes	String	The UnitDocument notes
resident_can_view	Boolean	Whether residents are permitted to view this document
created_at	String	Timestamp this database entry was created. format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	String	Timestamp this database entry was last updated . format: yyyy-mm-ddThh:mm:ss.mmmZ
file	SecureFileDownload	Object Containing file attachment data

Relationships

Name	Type	Description
unit	Unit	The Unit the UnitDocument belongs to

Permission Requirements

Users must have adequate permissions to view BlockDocuments:

• Super Mega Admin Role: Can view all unit documents
• Block Manager Role: Can view all unit documents
• Unit Owner Role: Can view all unit documents in a unit where they own the unit
• Third Party Role: Can view all unit documents in a unit where parent role is unit owner
• Resident Role: Can only view unit documents where resident_can_view is true

UnitLeaseScheduleReport

Sample UnitLeaseScheduleReport JSON Object

{
    "id": 1,
    "type": "unit_lease_schedule_report",
    "attributes": {
        "totals": {
            "yearly_charge": "778.75",
            "frequency_period_1_charge": "389.38",
            "frequency_period_2_charge": 0,
            "frequency_period_3_charge": "389.38",
            "frequency_period_4_charge": 0
        },
        "data": [
            {
                "percentage": null,
                "charge_name": "Service Charge",
                "charge_type": 0,
                "charge_frequency": 1,
                "unit_yearly_charge": "778.75",
                "charge_type_description": "Equal (All Units)",
                "charge_frequency_description": "Half Yearly",
                "lease_schedule_yearly_charge": "778.75",
                "max_number_of_yearly_charges": 2,
                "include_unit_in_lease_schedule": true,
                "unit_frequency_period_1_charge": "389.38",
                "unit_frequency_period_2_charge": null,
                "unit_frequency_period_3_charge": "389.38",
                "unit_frequency_period_4_charge": null,
                "number_of_times_charged_this_year": 1
            }
        ],
        "created_at": "2024-05-31T16:14:25.145Z",
        "updated_at": "2024-05-31T16:14:25.145Z"
    },
    "relationships": {
        "unit": {
            "data": {
                "id": "102",
                "type": "unit"
            }
        }
    }
}

The unit lease schedule report combines data from multiple sources into a complex summary. To simplify this process, the API compiles the data into a unit_lease_schedule_report object, so the front end only needs to render the HTML table and totals without knowing how the underlying data is gathered.

Attributes

Name	Type	Description
data	Object[]	Each item in the array is a row to render in the html table
totals	Object	Monetary amount from data totalled together

Data Object

Property	Type	Description
charge_name	String	Descriptive name of this charge (e.g., "Service Charge", "Ground Rent")
percentage	String	Percentage allocation for this charge when using percentage-based calculation
charge_type	ENUM	Type of Lease Schedule Charge
charge_frequency	ENUM	How frequent charge is applied
charge_type_description	String	Human-readable description of the charge calculation method
charge_frequency_description	String	Human-readable description of the billing frequency
unit_yearly_charge	String	Total yearly amount for this specific charge allocated to this unit
lease_schedule_yearly_charge	String	Total yearly amount for this charge across the entire lease schedule
unit_frequency_period_1_charge	String	Amount for this unit in billing period 1
unit_frequency_period_2_charge	String	Amount for this unit in billing period 2
unit_frequency_period_3_charge	String	Amount for this unit in billing period 3
unit_frequency_period_4_charge	String	Amount for this unit in billing period 4
max_number_of_yearly_charges	Integer	Maximum number of times this charge can be applied in one year
include_unit_in_lease_schedule	Boolean	Whether this unit is included in the lease schedule calculation for this charge, if false exclude from html table
number_of_times_charged_this_year	Integer	Number of times this charge has been applied to this unit in the current year

All monetary amounts are returned as strings to preserve precision

Totals Object

Property	Type	Description
yearly_charge	String	Total amount charged to this unit annually across all charge types
frequency_period_1_charge	String	Total amount for the first billing frequency period
frequency_period_2_charge	String	Total amount for the second billing frequency period
frequency_period_3_charge	String	Total amount for the third billing frequency period
frequency_period_4_charge	String	Total amount for the fourth billing frequency period

Charge Type ENUM

Value	Description	Calculation Method
0	Equal (All Units)
1	Percentage

Charge Frequency ENUM

Value	Description
0	Yearly
1	Half Yearly
2	Quarterly
3	English Quarter Rent Days
4	English Half Yearly Rent Days
5	English Yearly Rent Days

Relationships

Name	Type	Description
unit	Unit	The unit that this lease schedule report belongs to

Transaction

Sample Transaction JSON Object

{
  "id": "1842",
  "type": "transaction",
  "attributes": {
    "transaction_id": 1842,
    "transaction_date_on": "2024-03-15",
    "description": "Service Charge Q1 2024",
    "charge_type": 0,
    "transaction_type": 1,
    "financial_period": "2024",
    "statement_number": 12,
    "charge_amount": 1250.00,
    "balance": 3850.75,
    "debit": null,
    "credit": 1250.00,
    "payment_reference": "SC-APT-001-2024",
    "created_at": "2024-03-15T09:30:00.000Z",
    "updated_at": "2024-03-15T09:30:00.000Z"
  },
  "meta": {
    "has_document": true,
    "document_status": 1
  }
}

Summary

This resource holds the Transaction information. A Transaction belongs to a Unit. Transactions represent financial activity including charges, payments, and notices for property management.

Attributes

Name	Type	Description	Notes
transaction_id	Integer	Unique identifier for the transaction
transaction_date_on	String	Date the transaction occurred	Date format: yyyy-mm-dd
description	String	Description of the transaction
charge_type	Integer	Type of charge	0 = Service Charge 1 = Ground Rent
transaction_type	Integer	Type of transaction	0 = Receipt or Direct Debit 1 = Charge (Global or Single) 2 = Standard/Reminder/Final Notice 3 = Advance Notice
financial_period	String	Financial period (year)	Only present for Service Charge transactions
statement_number	Integer	Statement number for tracking	~Optional
charge_amount	Decimal	Transaction amount (always positive)
balance	Decimal	Running balance after this transaction
debit	Decimal	Debit amount (positive transactions)	~Optional - Only when transaction increases balance
credit	Decimal	Credit amount (negative transactions)	~Optional - Only when transaction decreases balance
payment_reference	String	Payment reference for this charge type	~Optional - Generated based on unit and charge type
created_at	String	Timestamp this database entry was created	Date format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	String	Timestamp this database entry was last updated	Date format: yyyy-mm-ddThh:mm:ss.mmmZ

Relationships

Name	Type	Description	Notes

Meta

Name	Type	Description	Notes
has_document	Boolean	Whether this transaction has an associated document
document_status	Integer	Status of document generation	~Optional - Only present when has_document is true null = Generation not yet started. You must call Get Transaction Document endpoint at least once to start generation of the document. 0 = Processing 1 = Ready 2 = Error

Transaction Document

Sample Transaction Download JSON Object that is ready to download

{
  "id": "1842",
  "type": "transaction_document",
  "attributes": {
    "status": 1,
    "document": {
      "download_url": "https://...,
       "file_name": "...-09-2024.pdf",
      "file_size": 157448,
      "updated_at": "2024-11-04T15:16:02.127Z"
    }
  }
}

Sample Transaction Download JSON Object that is NOT ready to download

{
  "id": "1842",
  "type": "transaction_document",
  "attributes": {
    "status": 0,
    "document": null
  }
}

Summary

This resource holds download information for a PDF associated with a transaction. This document is generated on demand, so client will have to poll the API until status changes to 1 to indicate the document is ready for download.

Attributes

Name	Type	Description
status	Integer	Document status ((0 = Processing, 1 = Ready)
document	SecureFileDownload	Object Containing file attachment data

User

Sample User JSON Object

{
  "data": {
    "id": "1",
    "type": "user",
    "attributes": {
      "email": "charles_ernser_1@topfloor.ie",
      "created_at": "2025-05-23T12:51:49.190Z",
      "updated_at": "2025-05-23T12:51:49.190Z"
    },
    "relationships": {
      "user_roles": {
        "data": [
          {
            "id": "101",
            "type": "user_role"
          }
        ]
      }
    },
    "meta": {
      "units_count": 3
    }
  }
}

Summary

This resource holds the User information. A User can log in to Myblockman, and has one or more UserRole that determines which permissions the User has access to

Attributes

Name	Type	Description
email	String	User's email
created_at	String	Timestamp this database entry was created. format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	String	Timestamp this database entry was last updated .format: yyyy-mm-ddThh:mm:ss.mmmZ

Meta

Name	Type	Description	Notes
units_count	Integer	Count of Units the User owns when having Unit-Owner role

UserRole

Sample Unit Owner UserRole JSON Object

{
  "data": {
    "id": "146239",
    "type": "user_role",
    "attributes": {
      "role_type": 0,
      "permissions": {},
      "name": null,
      "created_at": "2024-06-24T12:41:52.877Z",
      "updated_at": "2024-06-24T12:41:52.877Z"
    },
    "relationships": {
      "user": {
        "data": {
          "id": "142738",
          "type": "user"
        }
      },
      "user_role": {
        "data": null
      },
      "units": [
        "data": {
          "id": "136673",
          "type": "unit"
        }
      ],
      "blocks": [
        "data": {
          "id": "3",
          "type": "block"
        }
      ]
    }
  }
}

Sample Block Director UserRole JSON Object

{
  "data": {
    "id": "12",
    "type": "user_role",
    "attributes": {
      "role_type": 4,
      "permissions": {},
      "name": null,
      "created_at": "2024-06-24T12:41:52.877Z",
      "updated_at": "2024-06-24T12:41:52.877Z"
    },
    "relationships": {
      "user": {
        "data": {
          "id": "89",
          "type": "user"
        }
      },
      "user_role": {
        "data": null
      },
      "blocks": [
        "data": {
          "id": "34",
          "type": "block"
        }
      ],
      "units": []
    }
  }
}

A UserRole represents access permission a User has. A User has many UserRoles , with each one giving the user a certain level of permissions to access blocks/units.

Attributes

Property	Type	Description
role_type	ENUM	Type of user role
permissions	Object	THIRD_PARTY user roles can be customised with further sub-permissions
name	string | null	THIRD_PARTY user roles are given a name to help identify them
created_at	String	Timestamp this database entry was created. format: yyyy-mm-ddThh:mm:ss.mmmZ
updated_at	String	Timestamp this database entry was last updated. format: yyyy-mm-ddThh:mm:ss.mmmZ

Role Types ENUM

Value	Type	Description
0	UNIT_OWNER	Will only have access to associated blocks/units
1	BLOCK_MANAGER	Employee of agent/customer. Can view all data
2	SUPER_MEGA_ADMIN	reserved for internal use
3	THIRD_PARTY	This is a user who has been granted permission to access data by a UNIT_OWNER or RESIDENT
4	BLOCK_DIRECTOR	A user who is director of a management company. It is likely this user also holds a UNIT_OWNER user role too.
5	API_SYSTEM_USER	reserved for internal use
6	RESIDENT	A user who lives in the block. They may be a tenant of a UNIT_OWNER or they may be the UNIT_OWNER themselves if they live in the block

Permissions Object

Property	Type	Description
read_access	boolean	Third Party User has read access to Unit owners data.
receive_notifications	boolean	Third party user will receive a copy of same email notifications as Unit Owner.

Relationships

Property	Type	Description
agent	Agent	The Agent this UserRole belongs to
user	User	The User this UserRole belongs to
user_role	UserRole | null	The parent UserRole associated with this one e.g. If this is a THIRD_PARTY user role, this parent with probably be a UNIT_OWNER role.
blocks	Block[]	List of blocks this user role grants access to
units	Unit[]	List of units this user role grants access to

Miscellaneous

Pagination Params

Sample Angular Typescript Use of using page http param, to request page 2 and 25 object per page

public listBlockMeetings(
  blockId: number
): Observable<BlockMeeting[]> {
  const agentUrl = ...
  const requestOptions = ...

  const urlParams = '?page[number]=2&page[size]=25';

  return this.http
    .get<BlockMeeting[]>(
      `${environment.API_URL}/v2/${agentUrl}/blocks/${blockId}/block_meetings${urlParams}`,
      requestOptions
    )
    .pipe(
      ...
    );
}

Sample JSON API response with pagination metadata

HTTP/1.1 200 OK
{
  "data": {
      // ...
  ],
  "meta": {
    "pagination": {
      "current": 2,
      "prev": 1,
      "next": 3,
      "last": 3,
      "records": 75,
      "total": 10,
      "per_page": 25
    },
    "sort": ...
  },
  "links": {
    // ...
  }
}

List/Search API end points usually have too much data to fit on visible screen. To increase efficiency of a single http response, results are usually paginated to keep http response body sizes as small as practical.

The API consumer can navigate through page results by attaching a page[number] parameter to their http request , e.g. page[number] = 2 will request page 2 of results.

The API consumer can customise the number of objects per page by attaching a page[size] parameter to their http request , e.g. page[number] = 50 will instruct the API to put 50 results per page. This may be desirable in situations where frontend is dynamically detecting how much space is available to render data. API consumer can then request the API includes more results per page to reduce HTTP requests and fill the available space on screen.

page object

Property	Type	Description	Default
page	int	Page Number	Will always default to 1
number	int	Number of object per page in the http response	See each API endpoint for details as default will vary.

Pagination Meta HTTP Response object

The List/Search API will always include pagination meta data in the http response.

Property	Type	Description
current	int	Current Page Number
prev	int	Previous Page Number
next	int	Next Page Number
last	int	Number of Last page
records	int	Total number of records found for search query
total	int	Total number of records (relevant to user)
per_page	int	Number of records per page

Sorting Params

Sample Angular Typescript Use of using page http param, to request page 2 and 25 object per page

public listBlockMeetings(
  blockId: number
): Observable<BlockMeeting[]> {
  const agentUrl = ...
  const requestOptions = ...

  const urlParams = '?sort[]=meeting_date';

  return this.http.get<BlockMeeting[]>(
    `${environment.API_URL}/v2/${agentUrl}/blocks/${blockId}/block_meetings${urlParams}`,
    requestOptions
  )
  .pipe(
    ...
  );
}

Sample JSON API response with pagination metadata

HTTP/1.1 200 OK
{
  "data": {
      // ...
  ],
  "meta": {
    "pagination": ...,
    "sort": [ 'meeting_date'] 
  },
  "links": {
    // ...
  }
}

Some List/Search APIs offer the ability to customise the order/sorting of results. Each API end point documentation will specify accepted sorting values. The sort param is an array of strings. The API will apply the sorting in the order the string appear in the array e.g.

sort=['some_date', '-name]

In this example the API will sort results by some_date in an ascending order. If 2 items in the results have the same value for some_date it will then sort those by name descending.

sort param

Property	Type	Description	Default
sort	string[]	Array of accepts sorting targets	See each API endpoint for details as default will vary.

Sort Meta HTTP Response object

The List/Search API will always include pagination meta data in the http response.

Property	Type	Description
sort	string[]	Ordered string array of applied sorting

Include Params

Sample Angular Typescript Use of using page http param, to request page 2 and 25 object per page

public listBlockMeetings(
  blockId: number
): Observable<BlockMeeting[]> {
  const agentUrl = ...
  const requestOptions = ...

  const urlParams = '?include[]=block';

  return this.http.get<BlockMeeting[]>(
    `${environment.API_URL}/v2/${agentUrl}/blocks/${blockId}/block_meetings${urlParams}`,
    requestOptions
  )
  .pipe(
    ...
  );
}

Sample JSON API response with pagination metadata

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": "5",
      "type": "block_meeting",
      "attributes": {...},
      "relationships": {
        "agent": {...},
        "block": {
          "data": {
            "id": "2", // note this ID
            "type": "block"
          }
        }
      }
    },
    {
      "id": "6",
      ...
    }
  ],
  "meta": { ...},
  "links": { ... },
  "included": [
    {
      "id": "2", // search included array for matching id(2) and type(block)
      "type": "block",
      "attributes": {
        "block_name": "Eagle Acres",
        ...
      }
    }
  ]
}

The JSON response body for this API is based on conventions set by JSONApi. By default, related objects in a JSON:API response are returned as relationship stubs—just the id and type. e.g A BlockMeeting "belongs to" a Block. A BlockMeeting JSON response will contains a relationship object and in there will be a stubbed Block.

The JSON response for this API follows the JSONApi specification. By default, related objects are returned as relationship stubs—containing only their id and type.

For example, a BlockMeeting belongs to a Block. When fetching a BlockMeeting, the relationships object will contain a stub reference to the related Block.

If you want the full Block object, you have two options:

1. Use the `include` param for the BlockMeeting API request
2. Extract the `block` ID from the relationship stub and make a separate call to the Get Block API

Option 1 makes a single HTTP request but returns a larger JSON payload.

Option 2 results in two smaller HTTP responses but requires an extra round trip.

If using Option 1, the response will contain the full object under the included array. You can then match it by id and type from the relationships section.

The include parameter accepts an array of strings. If an API supports multiple relationships, you can include several related objects in one request. Each endpoint will document the available include options.

Note has many relationships are usually not supported as they are too expensive to render to json. An exception is made for rare edge cases where the size of the relationship is likely to be small or making a second HTTP request would have a negative impact of User Experience. e.g. Get Current User API endpoint will always include associated UserRoles by default.

include param

Property	Type	Description	Default
include	string[]	Array of related resources to fully include	Varies per endpoint

Sort Meta HTTP Response object

Property	Type	Description
included	object[]	Array of included objects, potentially multiple types

Filter Params

Sample Angular Typescript Use of using page http param, to request page 2 and 25 object per page

public searchBlocks(
  blockId: number
): Observable<Block[]> {
  const agentUrl = ...
  const requestOptions = ...

  const params = {
    filter: {
      quick_search_cont: 'test',
      block_manager_id_eq: 3,
      created_at_gteq: "2025-07-01"
    }
  }

  return this.http.post<Block[]>(
    `${environment.API_URL}/v2/${agentUrl}/blocks/search`,
    params,
    requestOptions
  )
  .pipe(
    ...
  );
}

Most List/Search APIs will have an accepted list of filter params to be used to filter results. The filter params can be submitted as GET URL param or inside the POST body. The filter param is a Hash/Object of key-value pairs.

For example the List/Search Blocks API, here is an acceptable filter combination

{ "filter": { "quick_search_cont": "test", "block_manager_id_eq": 3, "created_at_gteq": "2025-07-01" } }

When multiple filters are provided, they are combined using AND logic in the Database query.

Secure File Download

MyBlockman uses AWS S3 to store all customer created files and documents.

Files are downloaded directly from S3 using a signed URL, which the MyBlockman API generates only if the user is authorised to access that file. These signed URLs are valid for 120 seconds and will expire after that, making them unusable.

We recommend the following flow for downloading a file, using a BlockDocument as an example:

1. User clicks the download button
2. Call the Get Block Document API with the generate_download_url param set to true e.g GET ${environment.API_URL}/v2/${agentUrl}/block_documents/${documentId}?generate_download_url=true
3. The response will return a BlockDocument JSON response with the data.attributes.file.download_url value being a signed S3 URL for the file
4. Render a temporary invisible html <a> with the href set to the S3 URL and simulate a click (or some other similar alternative method for avoiding the browser popup blocked warnings)

File/Attachment HTTP Response object

download_url will always be null unless the generate_download_url param is set to true

Parameter	Type	Description
file_name	string	file name including extension
file_size	int	Size of file in bytes
updated_at	string	When was file last updated, format: yyyy-mm-ddThh:mm:ss.mmmZ
download_url	string | null	Signed S3 Download URL

Password Reset Flow

1). Begin with asking user for their email address

2). Submit email address to the Create Password Reset Request API

3). User will receive an email with a password reset link. The structure of this link will look like

    https://{{AGENT_URL}}.myblockman.co.uk/user/password_reset/{{KEY}}/{{TOKEN}}

    e.g. https://topfloor.myblockman.co.uk/user/password_reset/SsbPiqzg2Ekp5iaZ6QPe/abcTM2Hu0wL1j9dG8fYLa1LRzL4ZvXy3htJjZeeD

4). When user clicks this link in their email, the front end will have to parse the URL segments to extract key and token

5). This key - token pair is only valid for 15 minutes and it can only be used once.

6). Before prompting the user to enter a new password, the front end should submit the key and token to the Validate Password Reset Request API. This will ensure we aren't asking the user to submit a new password and then discover that the key and token had already been used from an previous attempt or if the user waited too long to click the link in the email.

7). If key - token pair is valid, then ask the user to submit a new password. When user clicks the submit button call the Complete Password Reset Request API

8). If the user has entered a invalid/weak password, this API will return a http status 422 along with a display error message

9). If the user has entered a valid password, this API will return a http status 201. It will log the user in and in the json response will be a AuthToken object with the user session token.

Errors

Error Object

Property	Type	Description	Values
code	int	integer representation of the error message so error can be interpreted with programmatically	See Error Codes for lookup table of all codes
message	String	Plain text error message for user feedback
extra	Hash	Miscillaneous items that may be provided to help the API client recover from the error	e.g. If user is trying to access another agent's data, that the user has no permissions to access, extra Hash will contain a correct_agent_url string, giving the API client information so it can automatically redirect the user to a correct agents URL.

Error Codes

Error Code	Label	Meaning
202	ACTION_CANNOT_BE_PERFORMED_BY_LOGGED_IN_USER	This action can only be performed by a user who is not logged in
203	NO_AUTHORIZED_USER	There must be an authorized user. Use login API end point to login.
204	USER_ACCOUNT_DISABLED
205	USER_INSUFFICIENT_ACL
206	USER_AND_AGENT_DO_NOT_MATCH
207	UNAUTHORIZED
208	ALREADY_LOGGED_IN
209	INVALID_AUTHORIZATION_TOKEN
210	USER_INPUT_INVALID
212	MISSING_INPUT_PARAMETERS	Missing POST or http get parameters
213	RESOURCE_NOT_FOUND	No resource/object in Blockman matched ID/inputted serach param
214	NO_AGENT_FOUND
215	UNPERMITTED_PARAMETERS	only whitelisted attributes allowed in params
216	INSUFFICIENT_ACL
217	AGENT_DISABLED
218	INVALID_COUNTRY	The requested feature is not supported in agent's country
219	PASSWORD_RESET_INVALID_TOKEN_ERROR	The key or token were not found or are invalid. The link in email either got corrupted or the user is copying and pasting something incorrectly.
220	PASSWORD_RESET_EXPIRED_REQUEST_ERROR	The password reset link is more than 15 minutes old. The user will need to re-request a new link.
221	PASSWORD_RESET_LINK_ALREADY_USED_ERROR	The password reset link was already used. The user will need to re-request a new link.
222	PASSWORD_RESET_NO_SUCH_USER	No such user was found for the provided email address
223	USER_ACCOUNT_NOT_ACTIVATED	Cannot perform action as user as they have not yet clicked the activation link received in the email
224	USER_HAS_NO_USER_ROLES	User accounts has no user roles, e.g. they are not a unit owner or a third party user or a block manager. This account will probably be auto-deleted soon.
225	NOT_SUPPORTED_FOR_ASYNCHRONOUS_ACTION_JOB	This endpoint does not implement / support asynchronous ActionJob.
600	UNKNOWN = 600	Unknown error, follow hint in message. If no hint please contact Blockman Support

HTTP Status Codes

HTTP Status	Meaning
200	OK -- Everything is ok, relax.
201	Created -- We created your object, you do some work for once.
400	Bad Request -- Your request sucks.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The kitten requested is hidden for administrators only.
404	Not Found -- The specified kitten could not be found.
405	Method Not Allowed -- You tried to access a kitten with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The kitten requested has been removed from our servers.
418	I'm a teapot.
429	Too Many Requests -- You're requesting too many kittens! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.