PHPackages                             adambalan/helpscout-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. [HTTP & Networking](/categories/http)
4. /
5. adambalan/helpscout-api

ActiveLibrary[HTTP & Networking](/categories/http)

adambalan/helpscout-api
=======================

A simple library to help manage data from helpscout

1.13.1(8y ago)41321MITPHP

Since Nov 22Pushed 8y agoCompare

[ Source](https://github.com/AdamKyle/helpscout-api)[ Packagist](https://packagist.org/packages/adambalan/helpscout-api)[ RSS](/packages/adambalan-helpscout-api/feed)WikiDiscussions master Synced 2mo ago

READMEChangelog (10)Dependencies (8)Versions (49)Used By (1)

Helpscout API Library (PHP 7.1+)
================================

[](#helpscout-api-library-php-71)

[![Build Status](https://camo.githubusercontent.com/f4be92f80f33fd89e0e7ee8d0e85aa13634e506cdb949b706a1222fff9547d97/68747470733a2f2f7472617669732d63692e6f72672f4164616d4b796c652f68656c7073636f75742d6170692e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/AdamKyle/helpscout-api)[![Packagist](https://camo.githubusercontent.com/b67da229f961c532b581aa2d1343cfd90cfaf7178d1f48f01dab726d9f09e262/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6164616d62616c616e2f68656c7073636f75742d6170692e7376673f7374796c653d666c6174)](https://packagist.org/packages/adambalan/helpscout-api)![Maintenance](https://camo.githubusercontent.com/bc62a4386260fb7a4c9f5e3977f2f2bf876ad0374f462e723cedd156953a0da4/68747470733a2f2f696d672e736869656c64732e696f2f6d61696e74656e616e63652f7965732f323031382e737667)![Made With Love](https://camo.githubusercontent.com/8e692b7ce6dc41cb29efb7aa471b6e72a0a009ff99bf93ca83023a3da4e177b8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4d616465253230576974682d4c6f76652d677265656e2e737667)

The core purpose of this library is to manage [Helpscout API](https://developer.helpscout.com/docs-api/). I built this as a separate tool for my company to be able to backup our documentation.

> ATTN!!
>
> I am currently flushing this out with more endpoints as time goes on to make this more of a useful tool.

Installing
----------

[](#installing)

`composer install adambalan/helpscout-api`

API's
-----

[](#apis)

All of the core API endpoint classes live under `/Api/Get/`.

All of them take a GuzzleHttp client and a [ApiKey Contract](https://github.com/AdamKyle/helpscout-api/blob/master/docs/HelpscoutApi-Contracts-ApiKey.md).

### Contracts

[](#contracts)

The contracts are interfaces which are basic value objects - get/set methods based on what the api at this time needs, the following contracts exist:

- `ApiKey`
- `Article`
- `Category`
- `Collection`
- `Redirect`
- `site`
- `ArticlePostBody`
- `CategoryPostBody`
- `CollectionPostBody`
- `RequestPool`

These are implemented and then passed to the Endpoint class methods where needed.

For further documentation see [the generated documentation](https://github.com/AdamKyle/helpscout-api/blob/master/docs/ApiIndex.md).

Examples
--------

[](#examples)

The core thing to understand is that the structure and flow goes like this:

- Get all collections
- Get all categories (Based on collection ID)
- Get all articles (Based on category ID)
    - Get single article based on article id's returned from above.

You can also get Articles through the collections:

- Get all Collections
- Get all Articles (Based on Collection ID)
    - Get Single Article based on Article ID from above.

Articles Will return a list of articles, unfortunately you have to use the article ID to get specific information like text from a single article.

### Get All Articles

[](#get-all-articles)

To get all articles you must have a category id, which you can get from getting all categories, which in turn, requires a collection id.

```
use HelpscoutApi\Api\Get\Articles;
use HelpscoutApi\Contracts\ApiKey; // We will pretend we implemented this as ApiKeyValue;
use HelpscoutApi\Contracts\Category; // We will pretend we implemented this as CategoryValue;
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://docsapi.helpscout.net/v1/',
]);

$apiKey = new ApiKeyValue('xxxxxxxxxx');

$categoryValue = new CategoryValue('12345667');

$articles = new Article($client, $apiKey);
$articleJSON = $articles->getAll($categoryValue);

// Do something with $articleJSON.
```

### Get All Articles with params

[](#get-all-articles-with-params)

```
use HelpscoutApi\Api\Get\Articles;
use HelpscoutApi\Contracts\ApiKey; // We will pretend we implemented this as ApiKeyValue;
use HelpscoutApi\Contracts\Category; // We will pretend we implemented this as CategoryValue;
use HelpscoutApi\Params\Article as ArticleParams;
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://docsapi.helpscout.net/v1/',
]);

$apiKey = new ApiKeyValue('xxxxxxxxxx');

$categoryValue = new CategoryValue('12345667');

// You can set the url params that come back as `?sort=number&status=number`:

$articleParams = new ArticleParams();
$articleParams->sort('number');
$articleParams->status('name');

$articles = new Article($client, $apiKey);

// We then pass $articleParams
$articleJSON = $articles->getAll($categoryValue, $articleParams);

// Do something with $articleJSON.
```

### Post an article

[](#post-an-article)

The same concept will work for posting a category or collection, just swap out the `ArticlePostBody` for the Category or Collection post body contract.

```
use HelpscoutApi\Api\Post\Article;
use HelpscoutApi\Contracts\ApiKey; // We will pretend we implemented this as ApiKeyValue;
use HelpscoutApi\Contracts\ArticlePostBody; // We will pretend we implemented this as ArticlePostBody;
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://docsapi.helpscout.net/v1/',
]);

$apiKey = new ApiKeyValue('xxxxxxxxxx');

$articlePostBody->collectionID('123');
$articlePostBody->name('article name');
$articlePostBody->text('something');

$article = new Article($client, $apiKey);
$article->create($articlePostBodyValue);

// This will return a response, see https://developer.helpscout.com/docs-api/articles/create/
// for more information.
```

### Delete an article

[](#delete-an-article)

These concepts apply to categories and collections as well.

```
use HelpscoutApi\Api\Delete\Article;
use HelpscoutApi\Contracts\ApiKey;
use HelpscoutApi\Contracts\Article as ArticleContract;
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://docsapi.helpscout.net/v1/',
]);

$apiKey = new ApiKeyValue('xxxxxxxxxx');

$articleContract = new ArticleContract('1234');
$article         = new Article($client, $apiKey);

$article->delete($articleContract); // Returns the \GuzzleHttp\Psr7\Response
```

You can view the [tests](https://github.com/AdamKyle/helpscout-api/tree/master/tests) to get a better understanding of how you would use the endpoints.

### Update an article

[](#update-an-article)

> ## ATTN!!
>
> [](#attn)
>
> You can only update articles at this time.

Updating an article works the same way as creating an article with one minor difference, we pass an [`ArticlePutBody`](https://github.com/AdamKyle/helpscout-api/blob/master/docs/HelpscoutApi-Contracts-ArticlePutBody.md) contract.

This contract contains three methods: `id(string $articleId)`, `getId(): string`, `articlePostBody(ArticlePostBody $articlePostBody)`

There is one final method, the `createPutBody()` which is used to create the actual JSON for the request.

Much like the create, you can update a single, async and return a update request, all of which use `PUT` requests.

```
use HelpscoutApi\Api\Post\Article;
use HelpscoutApi\Contracts\ApiKey; // We will pretend we implemented this as ApiKeyValue;
use HelpscoutApi\Contracts\ArticlePostBody; // We will pretend we implemented this as ArticlePostBody;
use HelpscoutApi\Contracts\ArticlePutBody; // We will pretend we implemented this as ArticlePutBody;
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://docsapi.helpscout.net/v1/',
]);

$apiKey = new ApiKeyValue('xxxxxxxxxx');

$articlePostBody->collectionID('123');
$articlePostBody->name('article name');
$articlePostBody->text('something');

$articlePutBody->id('articleId');
$articlePutBody->articlePostBody($articlePostBody);

$article = new Article($client, $apiKey);
$article->update($articlePutBody);

// This will return a response, see https://developer.helpscout.com/docs-api/articles/update/
// for more information.
```

### Request Async and Pools

[](#request-async-and-pools)

> ## ATTN!!
>
> [](#attn-1)
>
> Currently this only works with articles and categories

When you want to do things in an async matter or you have an undefined amount of entities to post to a particular endpoint you can use the `createAsync` and `createRequest`. One will return a [Promise](http://docs.guzzlephp.org/en/stable/quickstart.html#async-requests) and the other is intended to be used with [Guzzels Pools](http://docs.guzzlephp.org/en/stable/quickstart.html?highlight=pool#concurrent-requests);

Lets look at how you might do that.

#### `createAsync()`

[](#createasync)

```
use Psr\Http\Message\ResponseInterface;
use GuzzleHttp\Exception\RequestException;

// ... Set up your article info to be posted, see previous examples.

$promise = $article->createAsync($articlePostBodyValue);
$promise->then(function(ResponseInterface $ri) {
  echo $ri->getStatusCode();
},
function(RequestException $e) {
  echo $e->getMessage();
});
```

As we can see `createAsync()` simply returns a promise.

#### `createRequest()`

[](#createrequest)

Create request is meant to be used with the contract [`RequestPool`](https://github.com/AdamKyle/helpscout-api/blob/master/docs/HelpscoutApi-Contracts-RequestPool.md)to set the requests, as this method only returns a request object. You then set the requests to the pool array and then pass the `RequestPool` instance to the [`Pool`](https://github.com/AdamKyle/helpscout-api/blob/master/docs/HelpscoutApi-Api-Pool.md) class method `pool`, along with the client instance to the instantiation.

From there you call `pool` with a rejected call back function and an optional success callback function.

```
use HelpscoutApi\Contracts\RequestPool;
use HelpscoutApi\Api\Pool;

// ... Set up your article info to be posted, see previous examples.

$request = $article->createRequest($articlePostBodyValue);

$requestPool->pushRequest($request); // Push the request
$request->setConcurrency(1); // How many should we do before we wait for them all to complete?

$pool = new Pool($client);
$pool->pool($requestPool, function($reason, $index){ ... }, function($response){ ... });

// The first call back function is called when we are rejected.
// The second is optional and only called on success.
```

> ## ATTN!!
>
> [](#attn-2)
>
> If concurrency is not set or is less then or equal to 0, we will set the default to 20.

Dealing with responses
----------------------

[](#dealing-with-responses)

Helpscout doesn't return a response body with JSON about created objects, instead a lot of the information you might want are in the header, on piece of information that is important, at least when you create new resources, is the location and the id of the resource.

```
use HelpscoutApi\Request\Request;

// See above for creating an article:

$response = $article->create($articlePostBodyValue);
$responseObject = new Request($response);

$responseObject->getLocation();  // Returns the location of the created object.
$responseObject->getContents();  // Returns the contents of the returned body.
```

[See class docs for Response](https://github.com/AdamKyle/helpscout-api/blob/master/docs/HelpscoutApi-Response-Response.md)

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity14

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity76

Established project with proven stability

 Bus Factor1

Top contributor holds 98.6% of commits — single point of failure

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 ~2 days

Recently: every ~8 days

Total

47

Last Release

2990d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/b355c694c28f31b51b43be0f1c4ba58d09729c77395a10fa4f68989065db6f27?d=identicon)[AdamKyle](/maintainers/AdamKyle)

---

Top Contributors

[![AdamKyle](https://avatars.githubusercontent.com/u/188563?v=4)](https://github.com/AdamKyle "AdamKyle (72 commits)")[![Adrienk](https://avatars.githubusercontent.com/u/509664?v=4)](https://github.com/Adrienk "Adrienk (1 commits)")

---

Tags

httpapilibraryhelpscoutfetching

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/adambalan-helpscout-api/health.svg)

```
[![Health](https://phpackages.com/badges/adambalan-helpscout-api/health.svg)](https://phpackages.com/packages/adambalan-helpscout-api)
```

###  Alternatives

[quickbooks/payments-sdk

The Official PHP SDK for QuickBooks Online Payments API

2758.2k2](/packages/quickbooks-payments-sdk)[meteocontrol/vcom-api-client

HTTP Client for meteocontrol's VCOM API - The VCOM API enables you to directly access your data on the meteocontrol platform.

175.7k1](/packages/meteocontrol-vcom-api-client)[infamoustrey/smartsheet

An API for Smartsheet

1025.2k](/packages/infamoustrey-smartsheet)

PHPackages © 2026

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