README

The Blond PHP SDK provides convenient access to the Blond API for PHP applications.

Requirements

PHP 8.2 and later

Installation

You can install the library via Composer:

composer require strawblond/strawblond-php-sdk

Note

StrawBlond is now Blond. The package name and the StrawBlond\ PHP namespace are kept unchanged for backwards compatibility.

Getting started

Basic usage looks something like this:

// Initialize a new SDK client using your API key
$api = new StrawBlond\StrawBlond('YOUR_API_KEY');

// Retrieve an invoice
$invoice = $api->invoice()->get('jDe2KdWYK4')->json();

// Get all paid invoices and include their contact and company relations
$invoices = $api->invoice()->all(
    filters: ['status' => 'paid'],
    include: ['contact.company'],
)->json('data');

// Create a new contact
$contact = $api->contact()->create([
    'firstname' => 'Max',
    'lastname' => 'Muster',
    'email' => 'max@muster.com'
])->json();

The Blond API uses personal API keys to authenticate incoming requests. You can view and manage your API keys in the User Settings. Your API keys carry the same permissions as your regular user account, so be sure to keep them secure!

Important

An API key acts as your user in a specific organization. You cannot access multiple organizations with a single key.

Resources

The SDK gives you access to all resources documented on https://developers.strawblond.com/.

$api = new StrawBlond\StrawBlond('YOUR_API_KEY');

// CRUD resources
$api->contact();
$api->company();
$api->project();
$api->timeTracking();
$api->invoice();
$api->offer();
$api->documentElement();
$api->product();
$api->rate();
$api->unit();

// Special resources
$api->user();
$api->member();
$api->webhook();

Available methods

All CRUD resources give you at least following request methods to call:

Description	Method
Retrieve a single resource	`get(string $id)`
Get a list of resources	`all(array $filters, array $include, string $sort, int $page, ?int $perPage)`
Create a resource	`create(array $data)`
Update a resource	`update(string $id, array $changes)`
Delete a resource	`delete(string $id)`

Some resources support additional shared operations:

Description	Method	Available on
Clone a resource	`clone(string $id, array $overrides)`	contact, product, invoice, offer
Restore a soft-deleted resource	`restore(string $id)`	project, expense, invoice, offer

Consult our documentation at https://developers.strawblond.com for resources that expose additional methods (like send() on invoices and offers).

Invoices

Beyond the CRUD methods, $api->invoice() exposes:

Description	Method
Send an invoice	`send(string $id, array $recipients, ?string $message, bool $increaseDunningLevel, bool $ccToOwner, bool $adjustDates, array $attachments)`
Update the status	`updateStatus(string $id, string $status, ?string $paidAt, ?float $conversionRate, bool $notifyCustomer)`
Mark as paid	`markAsPaid(string $id, ?string $paidAt, ?float $conversionRate, bool $notifyCustomer)`
Mark as pending	`markAsPending(string $id)`
Mark as draft	`markAsDraft(string $id)`
List by status	`drafts()`, `pending()`, `paid()`, `open()`, `overdue()`, `dunned()`, `scheduled()`, `readyForDelivery()` (same arguments as `all()`)
Line items sub-resource	`lineItems(string $invoiceId)`
Payments sub-resource	`payments(string $invoiceId)` — supports `all()`, `get()`, `create()` and `delete()` (payments cannot be updated)
Create next recurring invoice	`createNextRecurring(string $id)`
Next invoice number info	`nextInfo(?string $issuedAt)` — returns the upcoming `sequence` and `number`
Add products as line items	`addProducts(string $id, array $productIds, ?int $beforeOrder)`
Add rates as line items	`addRates(string $id, array $rates, ?int $beforeOrder)` — each rate is `['id' => ..., 'quantity' => ...]`
Add expenses as line items	`addExpenses(string $id, array $expenseIds)`

// Record a payment and mark an invoice as paid
$api->invoice()->payments('jDe2KdWYK4')->create(['amount' => 150.00]);
$api->invoice()->markAsPaid('jDe2KdWYK4', paidAt: '2026-07-15', notifyCustomer: true);

Offers

Beyond the CRUD methods, $api->offer() exposes:

Description	Method
Send an offer	`send(string $id, array $recipients, ?string $message, bool $ccToOwner, array $attachments)`
Archive an offer	`archive(string $id, ?string $reason)`
Complete billing	`completeBilling(string $id, ?string $reason)`
Reopen billing	`reopenBilling(string $id)`
Line items sub-resource	`lineItems(string $offerId)`
Add products as line items	`addProducts(string $id, array $productIds, ?int $beforeOrder)`
Add rates as line items	`addRates(string $id, array $rates, ?int $beforeOrder)` — each rate is `['id' => ..., 'quantity' => ...]`

Usage

Start by sending a request using one of the methods available on the resource. In this example we're trying to fetch a single invoice given a invoice ID. The get method returns a Response object.

$response = $api->invoice()->get('jDe2KdWYK4');

We can now check if the request was successful and use the fetched data in various ways:

if ($response->ok()) {
    // Get the response data as an json decoded array
    $invoice = $response->json();

    // Same as `json` but gets a single value from the data
    $dueDate = $response->json('due_at');

    // Get the response data as a Laravel Collection.
    // ! Requires `illuminate/collections` to be installed
    $lineItems = $response->collect('elements');
}

Here's another example for creating a new contact:

$contact = $api->contact()->create([
    'firstname' => 'Max',
    'lastname' => 'Muster',
    'email' => 'max@muster.com'
])->json();

See Responses for more methods on the Response object.

Filtering

When calling the all method on a resource, you may pass an filters array to the method. (See the API reference on https://developers.strawblond.com for which filters are allowed on a given resource)

$projects = $api->project()->all(
    filters: [
        'status' => 'active',
        'billing_type' => 'flat'
    ],
)->json('data');

Sorting

When calling the all method on a resource, you may pass a sort key to the method. (See the API reference on https://developers.strawblond.com for which sort keys are allowed on a given resource)

$projects = $api->project()->all(
    sort: 'starts_at'
)->json('data');

Sorting is ascending by default and can be reversed by adding a hyphen (-) to the start of the property name.

$projects = $api->project()->all(
    sort: '-starts_at'
)->json('data');

Including relations

When calling the get or all method on a resource, you may pass an include array to include related resources. (See the API reference on https://developers.strawblond.com for which resources are allowed to be included in a request)

$projects = $api->project()->all(
    include: ['company', 'user']
)->json('data');

You may also use the dot notation to include nested relations (https://developers.strawblond.com/guide/intro.html#nested-includes)

Pagination

The all method on most resources returns a paginated list of objects inside a data property. The links and meta properties contain information useful for retrieving more pages.

You can set the page using the page argument.

$projects = $api->project()->all(
    page: 2,
)->json('data');

Responses

After sending a request, the Blond SDK resource will return a Response class. This response class contains many helpful methods for interacting with your HTTP response like seeing the HTTP status code and retrieving the body.

$response = $api->invoice()->get('jDe2KdWYK4');

$response->status() // Returns the response status code
$response->headers() // Returns all response headers
$response->header('X-Something') // Returns a given header
$response->body() // Returns the raw response body as a string
$response->json() // Retrieves a JSON response body and json_decodes it into an array.
$response->collect() // Retrieves a JSON response body and json_decodes it into a Laravel Collection. Requires `illuminate/collections`.
$response->object() // Retrieves a JSON response body and json_decodes it into an object.

// Methods used to determine if a request was successful or not based on status code.
$response->ok();
$response->successful();
$response->redirect();
$response->failed();
$response->clientError();
$response->serverError();

// Will throw an exception if the response is considered "failed".
$response->throw();

strawblond / strawblond-php-sdk

Maintainers

Package info

Statistics

Security