Mason External API

PHP client for the Mason External API. For terms of use and request/response schema, refer to the official documentation.

Installation

This package requires PHP 8.4 or newer.

composer require fw4/mason-api

Usage

use Mason\Api\Client;

$api = new Client('client-id', 'client-secret');
$group = $api->group(123);

Available endpoints

Use the following methods to access available endpoints:

Estates

$group->estates->list($parameters);
$group->estates->offline($parameters);
$group->estates->get('estate-id');
$group->estates->setPublicUrl('estate-id', 'public-url');

Previews

$group->previews->list($parameters);

Offices

$group->offices->list();

Webhook

$group->webhook->set('webhook-url');
$group->webhook->unset();

Contact requests

$group->sendContactRequest($parameters);
$group->sendValuationRequest($parameters);

Tokens

$api->token->info();
$api->token->revoke();

Pagination

Endpoints that retrieve multiple items return a traversable list of objects. Pagination for large lists happens automatically.

$estates = $group->estates->list();

// Traversing over the response takes care of pagination in the background
foreach ($estates as $estate) {
    echo $estate->name . PHP_EOL;
}

Manual pagination

For situations where manual pagination is required, a page method is provided. Calling this method with both a desired page index (starting at 1), and the amount of items to retrieve per page, returns a traversable list of objects. This list also provides multiple methods for dealing with paging metadata:

• getPage() to retrieve the current page index (starting at 1).
• getPageSize() to retrieve the maximum amount of items per page.
• count() to retrieve the actual amount of items on the current page.
• getTotalCount() to retrieve the total amount of items across all pages.
• getPageCount() to retrieve the total amount of pages.

Example

$page_index = 3;
$items_per_page = 20;

$estates = $group->estates->list([
    'updated_since' => new \DateTime('2026-01-01')
]);
$page = $estates->page($page_index, $items_per_page);

echo 'Showing ' . $page->count() . ' items out of ' . $page->getTotalCount() . PHP_EOL;
echo 'Page ' . $page->getPage() . ' of ' . $page->getPageCount() . PHP_EOL;
foreach ($page as $estate) {
    echo $estate->name . PHP_EOL;
}

Configuration

The default base URL is https://dev-api.mason.immo/. It can be changed through the constructor:

$api = new Client(
    clientId: 'client-id',
    clientSecret: 'client-secret',
    baseUrl: 'https://api.example.com/',
);

The default page size is 25 and can be configured when creating the client:

$api = new Client(
    clientId: 'client-id',
    clientSecret: 'client-secret',
    defaultPageSize: 100,
);

Token storage

The client obtains new OAuth access tokens automatically when necessary. Tokens are kept in memory by default, though it is recommended to use persistent token storage instead.

To use persistent filesystem storage:

use Mason\Api\Auth\TokenStorage\FileTokenStorage;

$api = new Client(
    clientId: 'client-id',
    clientSecret: 'client-secret',
    tokenStorage: new FileTokenStorage('/secure/cache/mason-api'),
);

Native Redis storage requires the ext-redis PHP extension:

use Mason\Api\Auth\TokenStorage\RedisTokenStorage;

$redis = new Redis();
$redis->connect('127.0.0.1');

$api = new Client(
    clientId: 'client-id',
    clientSecret: 'client-secret',
    tokenStorage: new RedisTokenStorage($redis),
);

Any PSR-16 cache can be used with Psr16TokenStorage. Custom stores can implement Mason\Api\Auth\TokenStorage\TokenStorageInterface.

License

fw4/mason-api is licensed under the MIT License (MIT). Please see LICENSE for more information.