Getting Started

The StrawBlond API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies or JSON payloads and returns JSON-encoded responses. It uses standard HTTP response codes, authentication, and verbs.

Disclaimer

The StrawBlond REST API and Webhooks are currently in Beta status. All documented endpoints and references are fully functional but may be subject to change.

• The Basics
• Pagination
• Filtering
• Searching
• Sorting
• Including relations
  • Nested includes
• Rate limiting
• Status and error codes

The Basics

• The base URL for API requests is always https://api.strawblond.com/api/.
• All requests must be made over HTTPS, calls made over plain HTTP will fail.
• All requests must have an Accept: application/json header.
• All requests must have an Authorization: Bearer [API-KEY] header. Read more about Authentication.
• All request bodies must be JSON payloads or Multipart Form data.

Pagination

All list endpoints return a paginated list of objects. We allow a maximum of 50 elements per page. The actual array of elements is in the data property. The links and meta properties contain information useful for retrieving more pages.

Example response

get

/invoice

// HTTP 200 OK
{
    data: [
        // An array of invoice objects
    ],
    links: {
        "first": "https://api.strawblond.com/api/invoice?page=1",
        "last": "https://api.strawblond.com/api/invoice?page=2",
        "prev": null,
        "next": "https://api.strawblond.com/api/invoice?page=2"
    },
    meta: {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://api.strawblond.com/api/invoice",
        "per_page": 20,
        "to": 3,
        "total": 3,
        "allowed_sorts": [],
        "allowed_filters": [],
    }
}

Filtering

When retrieving a list of objects, you can pass allowed filters with the filter array query parameter. Pass the filter key as the array key and the filter value as the parameter value.

In this example we're fetching only invoices where the status is overdue.

get

/invoice?filter[status]=overdue

You can combine multiple filters with more query parameters. In this example we're fetching only overdue invoices created in the year 2022.

get

/invoice?filter[status]=overdue&filter[date_range]=2022-01-01,2022-12-31

Searching

Searching is just filtering using the search filter. Pass a filter[search] query parameter to use full-text search on any resource.

get

/invoice?filter[search]=Jahresretainer

Sorting

When retrieving a list of objects, you can pass an allowed sort key with the sort query parameter:

get

/invoice?sort=paid_at

You can prefix the sort key with a minus (U+002D HYPHEN-MINUS, "-") to reverse the sort direction:

get

/invoice?sort=-paid_at

Including relations

API objects can have relations to other resources. For example, an invoice belongs to a contact or a project.

When retrieving one or a list of objects, you can pass allowed relations as a comma-separated list in the include query parameter:

get

/invoice/D4rNdYjlGy?include=project,contact

If project and contact are valid relations to an invoice, the invoice objects will contain them as extra properties:

{
    "id": "D4rNdYjlGy",
    "number": "RE-01234",
    "name": "Jahresretainer 2023",
    ...
    "project": {
        // a project object
    },
    "contact": {
        // a contact object
    }
}

Nested includes

Loading of relations can sometimes be nested. For example, when fetching an invoice, you can include contact.company.media to not only load the contact, but also the contact's company and compay logo.

The relations will be nested in the JSON response payload:

{
    "contact": {
        // a contact object
        "company": {
            // a company object
            "avatar": {
                // an image resource
            }
        }
    }
}

Rate limiting

Usage limitations

The StrawBlond API supports a limit of 50 requests per user per minute.

Past the limit, the API will return a 429 Too Many Requests error.

All API responses include the X-RateLimit-Remaining and X-RateLimit-Limit headers, which shows how many requests the client has remaining, and the total number allowed per minute.

A 429 response will also include a Retry-After header with the number of seconds to wait until retrying your query.

Status and error codes

All API queries return HTTP status codes that can tell you more about the response.

401 Unauthorized: The client doesn’t have correct authentication credentials.

402 Payment Required: The organization is in read-only mode. The organization owner will need to pay the outstanding balance to unfreeze the organization.

403 Forbidden: The server is refusing to respond. This is typically caused by incorrect access scopes.

404 Not Found: The requested resource was not found but could be available again in the future.

422 Unprocessable Entity: The request body contains (semantic) validation errors. This is typically caused by incorrect formatting, omitting required fields.

429 Too Many Requests: The client has exceeded the rate limit.

5xx Errors: An internal error occurred in StrawBlond. Check out the StrawBlond status page for more information.