PHPackages                             stitch-digital/laravel-simpro-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. stitch-digital/laravel-simpro-api

ActiveLibrary[API Development](/categories/api)

stitch-digital/laravel-simpro-api
=================================

Laravel package for working with the Simpro API

v1.2.3(1y ago)11.2k↓75%1[5 PRs](https://github.com/stitch-digital/laravel-simpro-api/pulls)MITPHPPHP ^8.2CI passing

Since Oct 10Pushed 3mo ago1 watchersCompare

[ Source](https://github.com/stitch-digital/laravel-simpro-api)[ Packagist](https://packagist.org/packages/stitch-digital/laravel-simpro-api)[ Docs](https://github.com/stitch-digital/laravel-simpro-api)[ GitHub Sponsors](https://github.com/stitch-digital)[ RSS](/packages/stitch-digital-laravel-simpro-api/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (16)Versions (59)Used By (0)

Laravel package for working with the Simpro API
===============================================

[](#laravel-package-for-working-with-the-simpro-api)

[![Latest Version on Packagist](https://camo.githubusercontent.com/7bda05dc4f73b58d1e44e42aec3bb415afc08c86e023e0142ed9c486fab1e068/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7374697463682d6469676974616c2f6c61726176656c2d73696d70726f2d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/stitch-digital/laravel-simpro-api)[![GitHub Tests Action Status](https://camo.githubusercontent.com/e5b818ecb207c0b5cf34ac54ed8b3df78c3bfa89447984fa06a7185179ecb136/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7374697463682d6469676974616c2f6c61726176656c2d73696d70726f2d6170692f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/stitch-digital/laravel-simpro-api/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/ff21407160e7d60af9a626a91bced92fc487afda1c8acc53b8bf4b42b9bdca5b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7374697463682d6469676974616c2f6c61726176656c2d73696d70726f2d6170692f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/stitch-digital/laravel-simpro-api/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/ad13e9aef0a4b9b9c4ce3edeb136a7c071932749807051452f40831141351dbe/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7374697463682d6469676974616c2f6c61726176656c2d73696d70726f2d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/stitch-digital/laravel-simpro-api)

[![Laravel Simpro API](./.github/screenshot.png)](./.github/screenshot.png)

Laravel Simpro is a robust package designed to seamlessly integrate your Laravel application with the Simpro API.

The full Simpro API documentation can be [found here](https://developer.simprogroup.com/apidoc/).

Table of Contents
=================

[](#table-of-contents)

- [Installation](#installation)
- [Usage](#usage)
    - [Using a Single Simpro Connection](#using-a-single-simpro-connection)
    - [Using Multiple Simpro Connections](#using-multiple-simpro-connections)
- [Available Requests](#available-requests)
- [Useful Methods](#useful-methods)
    - [Responses](#responses)
    - [Pagination](#pagination)
    - [Rate Limiting](#rate-limiting)
    - [Caching](#caching)
    - [Retries](#retries)
    - [Query Parameters](#query-parameters)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [Security](#security)
- [Credits](#credits)
- [License](#license)

Installation
============

[](#installation)

Laravel Simpro API can be installed using composer:

```
composer require stitch-digital/laravel-simpro-api
```

Then publish the config file:

```
php artisan vendor:publish --tag="simpro-api-config"
```

This will publish the configuration file to `config/simpro-api.php` where you can configure your settings.

This package is built using Saloon. Check out their [documentation here](https://docs.saloon.dev/).

Usage
=====

[](#usage)

### Using a Single Simpro Connection

[](#using-a-single-simpro-connection)

If you are using a single Simpro connection, you can add the following environment variables to your `.env` file:

```
SIMPRO_BASE_URL=https://your-build-url.simprosuite.com
SIMPRO_API_KEY=your-api-key
```

To use the package, you can use the Simpro facade to make requests to the API:

```
use StitchDigital\LaravelSimproApi\Facades\Simpro;
use StitchDigital\LaravelSimproApi\Requests\Info\GetInfo;

$response = Simpro::send(new GetInfo())->json();
```

If you prefer to use dependency injection over facades then you can do this too:

```
use StitchDigital\LaravelSimproApi\LaravelSimproApi;
use StitchDigital\LaravelSimproApi\Requests\Info\GetInfo;

$connector = new LaravelSimproApi();
$request = new GetInfo();

$response = $connector->send($request)->json();
```

### Using Multiple Simpro Connections

[](#using-multiple-simpro-connections)

If you are using multiple Simpro connections, you can pass the base URL and API key to the constructor of the connector:

```
use StitchDigital\LaravelSimproApi\LaravelSimproApi;
use StitchDigital\LaravelSimproApi\Requests\Info\GetInfo;

$connector = new LaravelSimproApi(
    baseUrl: 'https://custom-api-url.simprosuite.com',
    apiKey: 'custom-api-key'
);

$response = $connector->send(new GetInfo());

$response->json();
```

Available Requests
------------------

[](#available-requests)

For a full list of available requests, use the following command:

```
php artisan simpro:list-requests
```

Useful Methods
--------------

[](#useful-methods)

### Responses

[](#responses)

After sending a request to the Simpro API, a `Response` class is returned. In most of the examples, we show the json method that returns a JSON response body. Below are some of the key methods provided by Saloon's `Response` class:

MethodDescription`status`Returns the response status code.`headers`Returns all response headers`header`Returns a given header`body`Returns the raw response body as a string`json`Retrieves a JSON response body and json\_decodes it into an array.`array`Alias of `json``collect`Retrieves a JSON response body and json\_decodes it into a Laravel Collection. Requires `illuminate/collections`.`object`Retrieves a JSON response body and json\_decodes it into an object.`xmlReader`Used for XML responses - returns a XML Wrangler reader. Requires `saloonphp/xml-wrangler`.`dom`Used for HTML responses - returns a [Symfony DOM Crawler](https://symfony.com/doc/current/components/dom_crawler.html) instance. Requires `symfony/dom-crawler`.`stream`Returns the response body as an instance of `StreamInterface``saveBodyToFile`Allows you to save the raw body to a file or open file resource.`dto`Converts the response into a data-transfer object.`dtoOrFail`Will work just like `dto` but will throw an exception if the response is considered "failed".`ok`, `successful`, `redirect`, `failed`, `clientError`, `serverError`Methods used to determine if a request was successful or not based on status code. The `failed` method can be customised.`throw`Will throw an exception if the response is considered "failed".`getPendingRequest`Returns the `PendingRequest` class that was built up for the request.`getPsrRequest`Returns the PSR-7 request that was built up by Saloon`getPsrResponse`Return the PSR-7 response that was built up by the HTTP client/sender.### Pagination

[](#pagination)

This package uses the [Saloon Paged Paginator](https://docs.saloon.dev/installable-plugins/pagination/paged-pagination) for all GET requests that return multiple results.

There are various ways to use the paginator, all well documented in the Saloon docs - here is an example:

Let's say we want to retrieve all customers from Simpro. We can use the 'GetCustomers' request:

```
use StitchDigital\LaravelSimproApi\Facades\Simpro;
use StitchDigital\LaravelSimproApi\Requests\Customers\GetCustomers;

$companyId = 0;
$response = Simpro::send(new GetCustomers($companyId))->json();
```

However, Simpro will paginate responses by default to a page size of 30 results. We can see this if we return the headers for the same request:

```
use StitchDigital\LaravelSimproApi\Facades\Simpro;
use StitchDigital\LaravelSimproApi\Requests\Customers\GetCustomers;

$companyId = 0;
$response = Simpro::send(new GetCustomers($companyId))->headers();
```

This will return pagination data in the headers:

```
[
    "Result-Total" => "816",
    "Result-Pages" => "28",
    "Result-Count" => "30",
]
```

The easiest way to use the paginator is to collect all responses like this:

```
use StitchDigital\LaravelSimproApi\Facades\Simpro;
use StitchDigital\LaravelSimproApi\Requests\Customers\GetCustomers;

$companyId = 0;
$response = Simpro::paginate(new GetCustomers($companyId))
  ->collect()
  ->all();
```

When using the paginator, you can override the Simpro default per page limit of 30 by chaining the setPerPageLimit method to the request:

```
use StitchDigital\LaravelSimproApi\Facades\Simpro;
use StitchDigital\LaravelSimproApi\Requests\Customers\GetCustomers;

$companyId = 0;
$response = Simpro::paginate(new GetCustomers($companyId))
  ->setPerPageLimit(250) // increase the per page limit to 250
  ->collect()
  ->all();
```

The maximum per page limit is 250.

Warning

Take care when increasing the per page limit. If you are dealing with large datasets and performing complex operations, you may want to keep this at the default to avoid memory issues.

### Rate Limiting

[](#rate-limiting)

This package uses the [Saloon Rate Limiter Plugin](https://docs.saloon.dev/installable-plugins/handling-rate-limits) to rate limit requests to the Simpro API.

You can disable rate limited globally in the config file, as well as set the rate limit, threshold and driver:

```
    /*
    |--------------------------------------------------------------------------
    | Rate Limit Configuration
    |--------------------------------------------------------------------------
    |
    | Set the rate limit for Simpro requests. The rate limit is set per second
    | and the threshold is the percentage of the rate limit that is accepted.
    | The threshold must be a number between 0 and 1 (e.g. 0.5 for 50%).
    |
    | The default rate limit is as per the Simpro API documentation.
    |
    */

    'rate_limit' => [
        'enabled' => true,
        'per_second' => 10,
        'driver' => 'database',
        'threshold' => 0.8,
    ],
```

You can also disable rate limiting on a per-request basis by chaining the `useRateLimitPlugin(false)` method to the request:

```
use StitchDigital\LaravelSimproApi\Facades\Simpro;
use StitchDigital\LaravelSimproApi\Requests\Info\GetInfo;

$response = Simpro::useRateLimitPlugin(false)
  ->send(new GetInfo())
  ->json();
```

### Caching

[](#caching)

This package uses the [Saloon Caching Plugin](https://docs.saloon.dev/installable-plugins/caching-responses) to cache GET requests to the Simpro API.

You can disable caching globally in the config file, as well as set the cache driver and expiry time:

```
    /*
    |--------------------------------------------------------------------------
    | Cache Configuration
    |--------------------------------------------------------------------------
    |
    | Enable or disable caching for Simpro GET requests. The cache driver can
    | be set to any of the Laravel cache drivers. The cache expiry time is
    | set in seconds.
    |
    */

    'cache' => [
        'enabled' => true,
        'driver' => 'database',
        'expire' => 120,
    ],
```

### Retries

[](#retries)

You can control the global retry configuration in the config file:

```
    /*
    |--------------------------------------------------------------------------
    | Global Retry Configuration
    |--------------------------------------------------------------------------
    |
    | Set the number of retries for all requests. This can still be overridden
    | on a per-request basis, by chaining sendAndRetry() to the request:
    |
    | Example:
    | $response = $connector->sendAndRetry($request, 1);
    |
    */

    'global_retries' => 3, // Set to null to disable global retries
```

### Query Parameters

[](#query-parameters)

You can add query parameters to your requests by chaining the `query` method to the request:

```
use StitchDigital\LaravelSimproApi\Facades\Simpro;
use StitchDigital\LaravelSimproApi\Requests\Jobs\GetJobs;

$companyId = 0;
$siteId = 123;

$request = new GetJobs($companyId);
$request->query()->add('Site.ID', $siteId);

// Returns all jobs for Site ID 123
$response = Simpro::send($request)->json();
```

Changelog
=========

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.

Contributing
============

[](#contributing)

Contributions are welcome and will be fully credited! Contributions are accepted via Pull Requests on [GitHub](https://github.com/stitch-digital/laravel-simpro-api).

Security
========

[](#security)

If you discover any security related issues, please email  instead of using the issue tracker.

Credits
=======

[](#credits)

- [John Trickett](https://github.com/johntrickett86)
- [Anthony Elleray](https://github.com/AElleray)
- [Sam Carré](https://github.com/Sammyjo20) - The Creator of Saloon
- [All Contributors](https://github.com/stitch-digital/laravel-simpro-api/contributors)

License
=======

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

44

—

FairBetter than 91% of packages

Maintenance68

Regular maintenance activity

Popularity21

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity65

Established project with proven stability

 Bus Factor2

2 contributors hold 50%+ of commits

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~5 days

Total

35

Last Release

403d ago

Major Versions

v0.3.0 → v1.0.02024-10-27

### Community

Maintainers

![](https://www.gravatar.com/avatar/1afc3eb4b0906148c94893fc2c76a6832d3c5f6499f6f9ab223ec6d945ee95da?d=identicon)[johntrickett](/maintainers/johntrickett)

---

Top Contributors

[![AElleray](https://avatars.githubusercontent.com/u/109745189?v=4)](https://github.com/AElleray "AElleray (118 commits)")[![johntrickett86](https://avatars.githubusercontent.com/u/149476912?v=4)](https://github.com/johntrickett86 "johntrickett86 (118 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (3 commits)")

---

Tags

laravelStitch Digital Limitedlaravel-simpro-api

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/stitch-digital-laravel-simpro-api/health.svg)

```
[![Health](https://phpackages.com/badges/stitch-digital-laravel-simpro-api/health.svg)](https://phpackages.com/packages/stitch-digital-laravel-simpro-api)
```

###  Alternatives

[codebar-ag/laravel-docuware

DocuWare integration with Laravel

1221.1k](/packages/codebar-ag-laravel-docuware)[codebar-ag/laravel-zammad

Zammad integration with Laravel

106.1k](/packages/codebar-ag-laravel-zammad)[scalar/laravel

Render your OpenAPI-based API reference

6183.9k2](/packages/scalar-laravel)[ryangjchandler/bearer

Minimalistic token-based authentication for Laravel API endpoints.

8129.8k](/packages/ryangjchandler-bearer)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)