Using the API

Introduction to the Caseblocks API

Caseblocks makes a full application programming interface (API) available to developers. The Caseblocks GUI is the main consumer of the Caseblocks API but 3rd party developers may use the API for a variety of automation tasks.

Below are some of the common tasks developers can accomplish using the API:

  • capture a claim on a public-facing website and using the API store the claim in Caseblocks
  • allow a public-facing website to query the status of a claim held in Caseblocks
  • update an eCommerce order's delivery status via a webhook called by an external logistics system
  • trigger a complex task workflow on a specific eCommerce order in Caseblocks
  • upload a document to a claim

Developers can also automate tasks inside Caseblocks using the API:

  • setup new users in bulk
  • create a series of buckets
  • trigger a daily export of data

Interacting with the API

The Caseblocks API follows the GraphQL standard. GraphQL is a layer on top HTTP which allows developers to execute queries against Caseblocks and have data returned in a structured and strongly-typed manner. Developers are also able to make changes via what GraphQL calls mutations.

The beauty of GraphQL is you can be very specific about what data you actually need - down to the field-level - and thereby avoid retrieving data you have no need for.

Here's an example query for the list of cases in a specific bucket:

query {
  bucket(id: 18) {
    contents(page: 3, pageSize: 25) {
      cases {

In the example above, we're asking Caseblocks to fetch cases in bucket with id: 18. There could be a million cases in that bucket, so retrieving all at once is unwise, hence we paginate through the dataset asking for page: 3 with pageSize: 25. Finally, from each case retrieved we're only asking Caseblocks to return the id and title fields. We could have asked to include additional fields like currentStatus, createdAt, updatedAt, properties, but we chose to ignore them.

Here's a GraphQL mutation to create a new Claim:

mutation {
  createCase(newCase: {
    title: "Claim 123",
    currentState: "Awaiting Assessment",
    caseTypeCode: "claim",
    properties: {
      claim_date: "2020-05-07T00:00:00",
      claim_value: 3150,
      claim_source: "website",
      broker_claim: false
  }) {

In the mutation example above we're calling the createCase(...) mutation. We're required to specify title, currentState, caseTypeCode, and a bag of properties which contain fields specified in the schema for the Claim case type. Each entry in the bag of properties is strongly-typed using ISO8601 dates, numbers, strings, and boolean values. Caseblocks will in return an error flag, a set of messages, and the caseData of the newly created case if the mutation has been successful.

GraphQL Endpoint

All calls to the API should be routed to the GraphQL endpoint of your Caseblocks domain. If your Caseblocks domain is https://acme.caseblocks.com then your GraphQL endpoint is https://acme.caseblocks.com/graphql.

Use the POST HTTP verb to send a query or mutation request to that endpoint, e.g.

curl -XPOST -H 'Content-Type: application/json' \
    --data-raw '{"query":"mutation {createSession(email: \"website@acme.local\", password: \"123\") {error jwToken}}"}' \


You, or your calling code, needs be authenticated to perform any queries or mutations on the Caseblocks API. The authentication process uses credentials, such as email address and password, to return a JSON Web Token (JWT). The JWT is then used in subsequent API calls to execute queries and mutations.

To generate a JSON web token call the createSession(...) mutation.

mutation {
  createSession(email: "website@acme.local", password: "123") {

If the credentials were correct then the jwToken field will return a value similar to:


In subsequent calls to the API you would include the JWT in an Authorization header. Make sure you prefix the token with the word Bearer.

curl -XPOST -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiaWh0IjoxNTk5MDYwNTA4LCJleHAiOjE1OTkxNDY5MDh9.TLB0bLlBKU6PQjDlvXOMBpVQ1muqTmvzNDvEYNwdqZx' \
    --data-raw '{"query":"mutation {createCase(...) {error}}"}' \

Service Accounts

Developers will often use service accounts to integrate two separate IT systems. For example to have a website send eCommerce orders to Caseblocks we suggest you use the GUI set up user account in Caseblocks called website and give that user account very limited permissions to access and create eCommerce orders.

The credentials of that website user account should then be shared with the calling website in question.

Getting Started

The best way to get started with using the Caseblocks API is to use the GraphQL PLayground. The playground is a developer-focused GUI that allows you execute queries and mutations without having to write HTTP boilerplate code.