logo
API docs by Redocly

Irwin Public API (2023-05-01)

Download OpenAPI specification:Download

E-mail: support@imirwin.com URL: https://help.getirwin.com License: MIT Terms of Service

Introduction

This document describes the Irwin V1 Public API. This API is primarily intended for partners to develop integrations with our system. To use this API you must have an account with Irwin, learn more at www.getirwin.com

When using the code samples, requests should be sent with a Content-type of application/json.

CQRS

The Irwin API implements the Command Query Responsibility Segregation (CQRS) pattern at the core of it's API design. While this pattern can be intimidating for some it does have many advantages, namely that it significantly improves our ability to deal with unpredictable spikes of activity. To oversimplify this pattern we will service modify the state of the system (otherwise known as mutations) asynchronously.

Mutation requests (also known as Command requests) typically are those which do not query data. Queries tend to be requests which get, list, search or fetch data from the system. Mutations tend to be creates, updates, deletions and business logic.

For several integrations which simply want to push data into the Irwin system this should be relatively simple to implement. Command requests can be issued and forgotten about. The status of the command can periodically be checked later after a reasonable amount of time has passed. For more complex workflows it may be necessary to wait for a command to complete before making a new one. For these cases we will offer a number of solutions via our Command endpoints which should help in these cases.

Customer ID Header

For every request it is required to set the X-Irwin-Customer-Id header in order to explicitly determine which customer account the request is intended for. The value of this header must be the ID of the customer account you wish to operate upon.

You can retrieve a list of the customer accounts you have permission to operate upon using the Get Current User endpoint. This endpoint is the only endpoint which does not require the header to be set.

If this header is not included an HTTP 400 response will be returned indicating this header must be sent.

Providing an incorrect or unauthorized value to this header will result in an HTTP 403 response.

Commands

Operations that allow the user to query the status of submitted commands

Get Command Status

Returns the current status of the identified command.

Authorizations:
oauth
path Parameters
id
required
string <uuid>

ID of the Command

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Engagements

Operations related to the Engagement entities in the Irwin system

Create Engagement

Writes a command to eventually create a new engagement with an entity in the Irwin system. The command ID is returned which can be queried in the various Command endpoints.

An Engagement is a record of activity that some kind of entity took that would be of interest to users of the IRM. The list of engagement types is strictly defined but more cases can be added over time.

Authorizations:
oauth
Request Body schema: application/json
command_id
string <uuid> (CommandID)

Optional unique identifier for the transaction used for idempotence. If this value is submitted multiple times an HTTP 409 will be returned indicating the command has already been enqueued.

Person Matcher (object)
Email Subscription (object) or Email Unsubscribed (object) or Event Attended (object)

Responses

Request samples

Content type
application/json
{
  • "command_id": "7d510d78-7444-4252-aeac-9e473949661e",
  • "entity": {
    },
  • "engagement": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

IRM

Operations related to the IRM of the customer account in the Irwin system

Add Entity to IRM

Writes a command to eventually match an entity in the Irwin database or create a new entity in the user's IRM. The command ID is returned which can be queried in the various Command endpoints.

Authorizations:
oauth
Request Body schema: application/json
command_id
string <uuid> (CommandID)

Optional unique identifier for the transaction used for idempotence. If this value is submitted multiple times an HTTP 409 will be returned indicating the command has already been enqueued.

Person Matcher (object)

Responses

Request samples

Content type
application/json
{
  • "command_id": "7d510d78-7444-4252-aeac-9e473949661e",
  • "entity": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Metadata

Operations which provide information about the Irwin system

Get Current User

This endpoint will return useful information about the user identified by the access token.

Authorizations:
oauth

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ]
}