Introduction

The Pulse API is a RESTful API based on HTTPS requests and JSON responses, and has its structure based on the specifications provided by JSONApi. The API uses UUID’s as identifiers.

Base-URL

This API’s base-url is https://api-pulse.papershift.com.

Language

You can change the language of this API by setting Accept-Language in request header.

Currently supported languages are: de, en

Content-Type

Every request against this API requires Content-Type set to application/vnd.api+json

Authentication

The API uses email address and password to authenticate. On successfully signing in, the response returns a Bearer token in the header.

Pulse API expects the Bearer token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer token

Note

You must replace token with the actual token provided.

Rate Limiting

This API has a general rate limit of 300 requests/minute per IP address. For auth routes this limit has been reduced to 5 requests/20 seconds. Hitting the limit will result in a response with code 429.

In case you need higher limits, please reach out to us.

Filtering

Resources from index endpoints can be filtered by their attributes using a specific syntax.

This will return all accounts where the name equals “Company”:
/api/v1/accounts?filter[name]=eq:Company

Multiple filters can be applied as well:
/api/v1/accounts?filter[name]=ct:Paper&filter[company_type]=eq:Inc

Presence or absence of an attribute can be checked like this:
/api/v1/accounts?filter[discarded_at_blank]=1

You can even filter included associations:
/api/v1/accounts/{account.id}?include=users&filter[users][name]=ct:Peter

List of available filter operators:

eq	equal
!eq	not equal
gt	greater than
gte	greater than or equal
lt	less than
lte	less than or equal
pre	starts with
suf	ends with
ct	contains
!ct	does not contain
in	match values in array
!in	values is not in array
blank	is blank
present	not blank

Note

Note: Invalid matchers or fields are being ignored. Filtered associations are not implemented everywhere, but can be added. Please get in touch with us!

Sorting

You can easily sort all the collections by following the pattern:

Add + or nothing to sort in ascending order
Add - to sort in descending order

This will sort by name (in ascending order):
/api/v1/accounts?sort=name

This will sort by name (in ascending order) and by id (in descending order):
/api/v1/accounts?sort=name,-id

Pagination

All our collection endpoints contain a pagination system integrated.

We folllow the JSON:API specification closely in this regard; for detailed information, you can refer to its section about pagination: https://jsonapi.org/format/#fetching-pagination.

Strategy

Most endpoints use traditional, offset-based pagination. However, some use keyset-based pagination instead. That means those endpoints don’t support all pagination features (e.g. jumping to an arbitrary page number) in exchange for better response times for large datasets and no possibility of getting duplicates/missing items on follow-up pages.

Requests

If endpoints support the respective features, these pagination-related query parameters may be specified:

• page[number]: Number of the page to get, starting at page 1
• page[size]: Number of items per page

Responses

We include pagination links (as specified by JSON:API) in the top-level links object in responses from all paginated endpoints:

• first: URL of the first page of items
• last: URL of the last page of items (not supported by endpoints using keyset-based pagination)
• next: URL of the next page of items
• prev: URL of the previous page of items (not supported by endpoints using keyset-based pagination)

In addition, the following pagination-related fields will be contained in the meta object in responses, if endpoints supply the respective information:

• current_page: The current page number
• page_items: Number of items per page
• total_pages: Number of existing pages
• total_count: Number of existing items

Including Associations

You can easily include nested objects by using the following pattern:

This will include users in your GET account request:
/api/v1/accounts/{account.id}?include=users

All relationships of a resource can be included with the include param.

Note

If the relationship doesn’t exist this will currently return an error.

Meta

Some resources allow querying for specific meta data, such as permissions. What meta data can be retrieved is documented under each resource’s summary. If nothing is specified in the request, nothing is returned.

Example:

This will return permissions for boarding management related actions, as well as each boarding’s progress:

/api/v1/boardings/:boarding_id?meta[permissions]=actions&meta[progress]=true

Status Codes

You can expect the following HTTP status codes from our API:

Code	Explanation
200	Ok — Request was successfull.
400	Bad Request — Your request is invalid.
401	Unauthorized — Missing or wrong Bearer Token.
403	Forbidden — Insufficient rights to perform this action.
404	Not Found — Record could not be found.
415	Unsupported Media Type — Must be application/vnd.api+json
422	Unprocessable Entity — Could not process instructions.
429	Too Many Requests — Too many requests in too little time.
500	Internal Server Error — We had a problem with our server. Try again later.
503	Service Unavailable — We’re temporarily offline for maintenance. Please try again later.