Using the 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 {
        id
        title
      }
    }
  }
}

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
    }
  }) {
    error
    message
    lowLevelErrorMessage
    caseData
  }
}

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}}"}' \
    https://acme.caseblocks.com/graphql

Authentication

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") {
    error
    message
    jwToken
  }
}

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

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiaWh0IjoxNTk5MDYwNTA4LCJleHAiOjE1OTkxNDY5MDh9.TLB0bLlBKU6PQjDlvXOMBpVQ1muqTmvzNDvEYNwdqZx

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}}"}' \
    https://acme.caseblocks.com/graphql

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