API

This page explains how to create use AireFrame's APIs to build custom integrations.

Authentication

All integration APIs require a bearer token provided by AireIdentity using the OAuth client credentials flow

To get a client credentials token you must have setup an AireIdentity client that can request the AireFrameApi scope.

Example Request:

POST https://identity.aireinnovate.com/connect/token
CONTENT-TYPE application/x-www-form-urlencoded
client_id=[MY_CLIENT]&
client_secret=[MY_CLIENT_SECRET]&
grant_type=client_credentials&
tenant_key=[MY_TENANT_ENVIRONMENT_KEY]&
scope=AireFrameApi

Subject API

Get Subjects

Query subjects by a variety of filters.

Required Permission

List:Subject

Endpoint: GET api/v2/subject

Query Parameters (All optional):

Filtering:
- StructuralEntityKeys: String (Multiple can be provided, behaviour is OR)
- Either:
  - SearchTerm: String
  - customFieldValueFilter.values[custom_field_key]: String (Multiple can be provided)
    - With optional customFieldValueFilter.match: ExactAll (Match all field values exactly) or ExactAny (Match any field value exactly) - Defaults to ExactAll
Paging:
- After: String
- Before: String
- First: Integer (Defaults to 20 if First or Last is not provided)
- Last: Integer
- OrderBy: String
- OrderDirection: Ascending or Descending

Example requests:

Get all subjects that are assigned to either key1 or key2 structural entities

/api/v2/subject?structuralEntityKeys=key1&structuralEntityKeys=key2

Fuzzy search subjects by the term 'Isaac'

/api/v2/subject?searchTerm=Isaac

Get all subjects with the custom field values 'given_names' = 'Isaac' and 'family_name' = 'Newton'

/api/v2/subject?customFieldValueFilter.values[given_names]=Isaac&customFieldValueFilter.values[family_name]=Newton&customFieldValueFilter.match=ExactAll

Example Response

Example response:

json

{
  "PageInfo": {
    "HasNextPage": false,
    "HasPreviousPage": false,
    "StartCursor": "c4e44f3d-f7c8-42f7-a9c7-c1e6d35c714b",
    "EndCursor": "c4e44f3d-f7c8-42f7-a9c7-c1e6d35c714b",
    "TotalCount": 1
  },
  "Edges": [
    {
      "Node": {
        "Id": "c4e44f3d-f7c8-42f7-a9c7-c1e6d35c714b",
        "ExternalId": "6c5827d9-ae1e-4581-826b-7884596f929c",
        "CustomFieldValues": [
          {
            "Field": {
              "Key": "given_names",
              "Name": "Given Names",
              "Type": "Text",
              "Required": true,
              "IsArray": false
            },
            "Value": {
              "DataType": "String",
              "ValueText": "Isaac"
            }
          },
          {
            "Field": {
              "Key": "family_name",
              "Name": "Family Name",
              "Type": "Text",
              "Required": true,
              "IsArray": false
            },
            "Value": {
              "DataType": "String",
              "ValueText": "Newton"
            }
          },
          {
            "Field": {
              "Key": "scientific_contributions",
              "Name": "Scientific Contributions",
              "Type": "Text",
              "Required": true,
              "IsArray": true
            },
            "Value": [
              {
                "DataType": "String",
                "ValueText": "Laws of Motion"
              },
              {
                "DataType": "String",
                "ValueText": "Universal Gravitation"
              }
            ]
          }
        ]
      },
      "Cursor": "c4e44f3d-f7c8-42f7-a9c7-c1e6d35c714b"
    }
  ]
}

Get Subject By Id

Returns details about a subject given their internal id.

Required Permission

View:Subject

Endpoint: GET api/v2/subject/{subjectId}

Where:

subjectId is AireFrame's internal identifier for the subject

Example response:

json

{
  "Id": "c4e44f3d-f7c8-42f7-a9c7-c1e6d35c714b",
  "ExternalId": "6c5827d9-ae1e-4581-826b-7884596f929c",
  "CustomFieldValues": [
    {
      "Field": {
        "Key": "given_names",
        "Name": "Given Names",
        "Type": "Text",
        "Required": true,
        "IsArray": false
      },
      "Value": {
        "DataType": "String",
        "ValueText": "Isaac"
      }
    },
    {
      "Field": {
        "Key": "family_name",
        "Name": "Family Name",
        "Type": "Text",
        "Required": true,
        "IsArray": false
      },
      "Value": {
        "DataType": "String",
        "ValueText": "Newton"
      }
    },
    {
      "Field": {
        "Key": "scientific_contributions",
        "Name": "Scientific Contributions",
        "Type": "Text",
        "Required": true,
        "IsArray": true
      },
      "Value": [
        {
          "DataType": "String",
          "ValueText": "Laws of Motion"
        },
        {
          "DataType": "String",
          "ValueText": "Universal Gravitation"
        }
      ]
    }
  ],
  "StructuralEntities": [
    {
      "Key": "e060a545-b6cc-4c80-bad9-440484538627",
      "DisplayName": "name",
      "ParentKey": null,
      "Depth": 1,
      "StructureType": {
        "Name": "name",
        "Key": "f36068c0-5b87-4b43-b3e0-6ee56d4865c2",
        "SubjectAssignable": true,
        "CustomFields": []
      },
      "CustomFieldValues": []
    }
  ]
}

Update Subject By Id

Updates a subject's custom field value(s).

Required Permission

Edit:Subject

Endpoint: PATCH api/v2/subject/{subjectId}

Body:

json

{
  "CustomFields": [
    {
      "Key": "string",
      "Value": {
        "<DataType>": {
          "Value": <Value>
        }
      }
    }
  ]
}

Where:

subjectId is AireFrame's internal identifier for the subject
CustomFieldValues is an array of key-values pairs for the custom fields from the structure type
- Key references the assossiated custom field on the structure type
- Value can be an array of objects (for multiple value custom fields) or an object containing:
  - Boolean (object): Contains a Value property for a boolean value.
  - String (object): Contains a Value property for string data.
  - Integer (object): Contains a Value property for an integer value.
  - Decimal (object): Contains a Value property for a decimal value.
  - DateTime (object): Contains a Value property for a date time value.
  - Date (object): Contains a Value property for a date value.
  - Time (object): Contains a Value property for a time value.
  - UserIdentifier (object): Contains a Value property for a user identifier.

Upsert (Create/Update) Subject

AireFrame can handle upsert subject messages provided that the subject upsert api has been configured - see here.

Required Permission

Create:Subject - If the subject does not exist

Edit:Subject - If the subject already exists

Create:SubjectLocation and Delete:SubjectLocation - If the subject exists and structural entity keys are provided

Endpoint: POST /api/v2/subject

Also available at: POST /api/v2/messaging/subject

Body:

json

{
  "CustomFieldValues": [
    {
      "Key": "single-value",
      "Value": {
        "<DataType>": {
          "Value": <Value>
        }
      }
    },
    {
      "Key": "array-value",
      "Value": [
        {
          "<DataType>": {
            "Value": <Value>
          }
        },
        {
          "<DataType>": {
            "Value": <Value>
          }
        }
      ]
    }
  ],
  "StructuralEntityKeys": ["key"]
}

Where:

CustomFieldValues is an array of key-value pairs for the custom fields from the subject configuration
- Key references the assossiated custom field on the subject configuration
- Value can be an array of objects (for multiple value custom fields) or an object containing:
  - Boolean (object): Contains a Value property for a boolean value.
  - String (object): Contains a Value property for string data.
  - Integer (object): Contains a Value property for an integer value.
  - Decimal (object): Contains a Value property for a decimal value.
  - DateTime (object): Contains a Value property for a date time value.
  - Date (object): Contains a Value property for a date value.
  - Time (object): Contains a Value property for a time value.
  - UserIdentifier (object): Contains a Value property for a user identifier.
StructuralEntityKeys is an optional list of structural entity keys, for behaviour see here.

TIP

The matching field(s) must always be present within the request body.

If a subject exists, all other fields are optional and the provided fields will be updated on the subject.

If the subject does not exist, all required fields must be provided.

The response will be the created subject:

{
    "internalId": "d6df60bb-0c6d-47ab-855b-23c98d58ee79",
    "externalId": "b38a64fe-df82-4510-92bb-314e26ff5509",
    "customFieldValues": [
        {
            "customField": {
                "id": "0eabc586-c18a-4ff5-8883-081e1615ea72"
            },
            "value": "value"
        }
    ]
}

Where internalId is AireFrame's subject identifier

Bulk Upsert (Create/Update) Subjects

Creates or updates multiple subjects in a single request. A maximum of 20 subjects can be upserted at once.

AireFrame can handle upsert subject messages provided that the subject upsert api has been configured - see here.

Required Permission

Create:Subject - For any subject in the batch that does not exist

Edit:Subject - For any subject in the batch that already exists

Create:SubjectLocation and Delete:SubjectLocation - For any subject in the batch that already exists and has structural entity keys provided

Endpoint: POST /api/v2/subject/bulk

Also available at: POST /api/v2/messaging/subject/bulk

Body:

json

[
  {
    "CustomFieldValues": [
      {
        "Key": "single-value",
        "Value": {
          "<DataType>": {
            "Value": "<Value>"
          }
        }
      },
      {
        "Key": "array-value",
        "Value": [
          {
            "<DataType>": {
              "Value": "<Value>"
            }
          }
        ]
      }
    ],
    "StructuralEntityKeys": ["key"]
  }
]

Where each item in the array follows the same schema as the single upsert endpoint.

TIP

The matching field(s) must always be present within each request in the batch.

If a subject exists, all other fields are optional and the provided fields will be updated on the subject.

If the subject does not exist, all required fields must be provided.

Example response:

json

[
  {
    "internalId": "d6df60bb-0c6d-47ab-855b-23c98d58ee79",
    "externalId": "b38a64fe-df82-4510-92bb-314e26ff5509",
    "customFieldValues": [
      {
        "customField": {
          "id": "0eabc586-c18a-4ff5-8883-081e1615ea72"
        },
        "value": "value"
      }
    ]
  }
]

Where internalId is AireFrame's subject identifier

Returns:

200 OK - If all subjects were successfully upserted. Returns an array of the created/updated subjects.
400 Bad Request - If the request body fails validation (e.g. more than 20 subjects provided, or a subject fails field validation).
403 Forbidden - If the client does not have the required permission for any operation in the batch.
409 Conflict - If the subject upsert feature is not configured.

Subject Location API

Add Subject To Location

Adds existing structural entities to a subject given structural entity keys.

Required Permission

Create:SubjectLocation

Endpoint: PUT api/v1/subject/{subjectId}/structuralEntities

Body:

{
    "keys" : [ "key1", "key2", "key3" ]
}

Where:

subjectId is AireFrame's internal identifier for the subject
keys is an array of structural entity keys

Remove Subject From Location

Removes structural entities from a subject.

Required Permission

Delete:SubjectLocation

Endpoint: DELETE api/v1/subject/{subjectId}/structuralEntities?keys=structuralEntityKey

Where:

subjectId is AireFrame's internal identifier for the subject
keys is the structural entity key to remove the subject from.
- Multiple keys can be provided, e.g. ?keys=key1&keys=key2

Subject Portal API

Get Subject Portal Users

Returns the users who have access to the subject via the subject access portal, given that subject access has been enabled.

Required Permission

View:SubjectAccessInvite

Endpoint: GET api/v1/subject/{subjectId}/subjectAccessUsers

Where:

subjectId is AireFrame's internal identifier for the subject

Optional paging query params:

Paging:
- After: String
- Before: String
- First: Integer
- Last: Integer
- OrderBy: String
- OrderDirection: Ascending or Descending

Example response

json

{
  "edges": [
    {
      "cursor": "MDpBcHByb3ZlZCBVc2VyOjdiMTc3ZDEyLWE2N2MtNDJhMS04NmFhLTNjMTBiZTgxZDMxNw==",
      "node": {
        "displayName": "User 1",
        "email": "user1@example.com",
        "id": "7b177d12-a67c-42a1-86aa-3c10be81d317",
        "inviteMethod": "SelfAccess"
      }
    },
    {
      "cursor": "MDpJbnZpdGVkIFN1YmplY3RTZWxmQWNjZXNzVXNlcjo0MDdkZWMzMC1lODg3LTQ4MWMtOTdhYS0wODMwMDdmM2NkMWI=",
      "node": {
        "displayName": "User 2",
        "email": "user2@example.com",
        "id": "407dec30-e887-481c-97aa-083007f3cd1b",
        "inviteMethod": "ThirdParty"
      }
    }
  ],
  "pageInfo": {
    "endCursor": "MTpcbnVsbDo3Yjc1Y2JhZi00YTI3LTQ2ZWMtOWJmNS1jZDk1ZTViNDQ5MTA=",
    "hasNextPage": false,
    "hasPreviousPage": false,
    "startCursor": "MDpBcHByb3ZlZCBVc2VyOjdiMTc3ZDEyLWE2N2MtNDJhMS04NmFhLTNjMTBiZTgxZDMxNw==",
    "totalCount": 2
  }
}

Response codes:

403 indicates that the client does not have the required permission.
404 indicates the subject could not be found.

Invite Subject To Portal

Invites a subject to use the subject portal, given that it has been enabled - see here.

Required Permission

Create:SubjectAccessInvite

Endpoint: POST api/v1/subject/{subjectId}/invite

Body:

json

["user@example.com"]

Where:

subjectId is AireFrame's internal identifier for the subject
The body is an optional array of emails for third party users to invite.
- If this is provided, third-party access must be enabled.
- If this is not provided, self-access must be enabled.

Example responses:

200 indicates a successful invitation.
403 indicates that the client does not have the required permission.
404 indicates the subject could not be found.
409 indicates the subject portal is not configured or the subject does not have values for the matching field(s) required for the invitation.

Remove Access to Portal

Removes a subjects or third party users access to the subject portal.

Required Permission

Delete:SubjectAccessInvite

Endpoint: DELETE api/v1/subject/{subjectId}/invite

Where:

subjectId is AireFrame's internal identifier for the subject

Supported Query Params:

thirdPartyUserEmails - an optional array of emails for third party users to remove access to the subject portal.
- If this is provided, third-party access must be enabled.
- If this is not provided, self-access must be enabled.

Example responses:

200 indicates a successful invitation.
403 indicates that the client does not have the required permission.
404 indicates the subject could not be found.
409 indicates the subject portal is not configured or the subject does not have values for the matching field(s) required for the invitation.

Subject Record API

Upload PDF

Multipart upload of a PDF document to be added to the subject's record.

Required Permission

Create:SubjectRecordItem

Endpoint: POST api/v1/subjects/{subjectId}/file/upload

Body (multipart/form-data):

file - The file to upload
title - The title of the document
effectiveDate - The effective date of the document (ISO 8601 format)

Where:

subjectId is the unique identifier for the subject

Example responses

200 - The file was successfully uploaded
400 - The request was invalid, e.g. missing required fields or file too large - see response message for details
403 - The client does not have the required permission
404 - The subject could not be found
415 - The file type is not supported

User API

Get Users

By default returns all active users. Results can be modified using the query parameters.

Endpoint: GET api/v1/users

Required Permission

List:User

Supported Query Params:

searchTerm - For searching users by name
includeInactive - For including inactive users
withAccessToSubjectId - For filtering down to users who have access to the subject via groups and the associated structural entities. Note: this is the AireFrame subjectId

Example response:


[{
    id: "user-identifier",
    displayName: "Test User"
}]

Add User to Groups

Required Permission

Create:UserGroup

Endpoint: POST api/v1/users/{userId}/groups

Body:

[{groupKey1}, {groupKey2}]

Where:

userId is the AireIdentity identifier for the user
Body contains a json array of the group keys to add the user to

Remove User from Groups

Required Permission

Delete:UserGroup

Endpoint: Delete api/v1/users/{userId}/groups?groupKey={groupKey1}&groupKey={groupKey2}

Where:

userId is the AireIdentity identifier for the user
groupKey(s) are the keys of the group to remove the user from

Structural Entity API

Get Structural Entities

Required Permission

List:StructuralEntity

Endpoint: GET api/v1/structuralEntity

Query Parameters (All optional):

Filtering:
- ParentKey: String
- Depth: Integer
- SearchTerm: String
- SubjectAssignable: Boolean
- StructureTypeKey: String
Paging:
- After: String
- Before: String
- First: Integer (Defaults to 20 if First or Last is not provided)
- Last: Integer
- OrderBy: String
- OrderDirection: Ascending or Descending

Example response:

json

{
  "PageInfo": {
    "HasNextPage": false,
    "HasPreviousPage": false,
    "StartCursor": "e060a545-b6cc-4c80-bad9-440484538627",
    "EndCursor": "f8a2dd4c-aa4e-4215-a830-316543fed34a",
    "TotalCount": 1
  },
  "Edges": [
    {
      "Node": {
        "Key": "e060a545-b6cc-4c80-bad9-440484538627",
        "DisplayName": "name",
        "ParentKey": null,
        "Depth": 1,
        "StructureType": {
          "Name": "name",
          "Key": "f36068c0-5b87-4b43-b3e0-6ee56d4865c2",
          "SubjectAssignable": true,
          "CustomFields": []
        },
        "CustomFieldValues": []
      },
      "Cursor": "e060a545-b6cc-4c80-bad9-440484538627"
    }
  ]
}

Get StructuralEntity By Key

Returns details about a structural entity that matches a given key.

Required Permission

View:StructuralEntity

Endpoint: GET api/v1/structuralEntity/{structuralEntityKey}

Where:

structuralEntityKey is the unique key for the structural entity

Example response:


{
  "Key": "e060a545-b6cc-4c80-bad9-440484538627",
  "DisplayName": "name",
  "ParentKey": null,
  "Depth": 1,
  "StructureType": {
    "Name": "name",
    "Key": "f36068c0-5b87-4b43-b3e0-6ee56d4865c2",
    "SubjectAssignable": true,
    "CustomFields": []
  },
  "CustomFieldValues": []
}

Upsert (Create/Update) Structural Entity

Required Permission

Create:StructuralEntity - If the structural entity does not exist

Edit:StructuralEntity - If the structural entity already exists

Endpoint: PUT api/v1/structuralEntity

Body:

{
    "Key": string,
    "DisplayName": string,
    "ParentKey": string (optional),
    "StructureTypeKey": string,
    "CustomFieldValues": [
        {
            "Key": string,
            "Value": {
                "<DataType>": {
                    "Value": <Value>
                }
            }
        }
    ]
}

Where:

Key is the key for the existing structural entity
DisplayName is the new display name for the existing structural entity
ParentKey is the key of the new parent to this structural entity
StructureTypeKey is the key of the related structure type
CustomFieldValues is an array of key-values pairs for the custom fields from the structure type
- Key references the assossiated custom field on the structure type
- Value is an object containing:
  - Boolean (object): Contains a Value property for a boolean value.
  - String (object): Contains a Value property for string data.
  - Integer (object): Contains a Value property for an integer value.
  - Decimal (object): Contains a Value property for a decimal value.
  - DateTime (object): Contains a Value property for a date time value.
  - Date (object): Contains a Value property for a date value.
  - Time (object): Contains a Value property for a time value.
  - UserIdentifier (object): Contains a Value property for a user identifier.

Example Request

{
    "Key": "name",
    "DisplayName": "Name",
    "ParentKey": "parent-key",
    "StructureTypeKey": "structure-type-key",
    "CustomFieldValues": [
        {
            "Key": "city",
            "Value": {
                "String": {
                    "Value": "London"
                }
            }
        }
    ]
}

The Response will be the updated Structural Entity:

{
  "Key": "9718d040-5f2d-4a56-9771-9140a06e460e",
  "DisplayName": "New Name",
  "ParentKey": null,
  "Depth": 1,
  "StructureType": {
    "Name": "name",
    "Key": "188913dc-95cf-408b-ae52-cea05aee921c",
    "SubjectAssignable": true,
    "CustomFields": [
      {
        "Name": "City",
        "Key": "city",
        "Type": "text",
        "Required": false
      }
    ]
  },
  "CustomFieldValues": [
    {
      "Field": {
        "Name": "City",
        "Key": "city",
        "Type": "text",
        "Required": false
      },
      "Value": {
        "$type": "string",
        "DataType": "String",
        "Value": "London",
        "ValueText": "London"
      }
    }
  ]
}

Returns:

201 Created - If the Structural Entity was created.
200 Ok - If the Structural Entity was updated.

Bulk Upsert (Create/Update) Structural Entities

Creates or updates multiple structural entities in a single request. Entities are processed in topological order so that parent entities are always upserted before their children, even if they appear later in the request body.

Required Permission

Create:StructuralEntity - For any structural entity in the batch that does not exist

Edit:StructuralEntity - For any structural entity in the batch that already exists

Endpoint: PUT api/v1/structuralEntity/bulk

Body:

json

[
  {
    "Key": "string",
    "DisplayName": "string",
    "ParentKey": "string (optional)",
    "StructureTypeKey": "string",
    "CustomFieldValues": [
      {
        "Key": "string",
        "Value": {
          "<DataType>": {
            "Value": "<Value>"
          }
        }
      }
    ]
  }
]

Where each item in the array follows the same schema as the single upsert endpoint:

Key is the key for the structural entity
DisplayName is the display name for the structural entity
ParentKey is the optional key of the parent structural entity (may reference another entity in the same batch)
StructureTypeKey is the key of the related structure type
CustomFieldValues is an array of key-value pairs for the custom fields from the structure type
- Key references the associated custom field on the structure type
- Value is an object containing one of:
  - Boolean (object): Contains a Value property for a boolean value.
  - String (object): Contains a Value property for string data.
  - Integer (object): Contains a Value property for an integer value.
  - Decimal (object): Contains a Value property for a decimal value.
  - DateTime (object): Contains a Value property for a date time value.
  - Date (object): Contains a Value property for a date value.
  - Time (object): Contains a Value property for a time value.
  - UserIdentifier (object): Contains a Value property for a user identifier.

Example Request

json

[
  {
    "Key": "region-north",
    "DisplayName": "North Region",
    "ParentKey": null,
    "StructureTypeKey": "region-type-key",
    "CustomFieldValues": []
  },
  {
    "Key": "office-leeds",
    "DisplayName": "Leeds Office",
    "ParentKey": "region-north",
    "StructureTypeKey": "office-type-key",
    "CustomFieldValues": [
      {
        "Key": "city",
        "Value": {
          "String": {
            "Value": "Leeds"
          }
        }
      }
    ]
  }
]

Returns:

204 No Content - If all structural entities were successfully upserted.
400 Bad Request - If the request body fails validation.
403 Forbidden - If the client does not have the required permission for any entity in the batch.
404 Not Found - If a StructureTypeKey referenced in the batch does not exist.

Delete StructuralEntity

Attempts to delete a structural entity that matches a given key.

Required Permission

Delete:StructuralEntity

Endpoint: DELETE api/v1/structuralEntity/{structuralEntityKey}

Where:

structuralEntityKey is the unique key for the structural entity

Returns:

204 No Content - If the structural entity was deleted.
409 Conflict - If the structural entity cannot be deleted.

Deletion failure reasons include:

The structural entity has child structural entities
The structural entity has subjects assigned

Transfer Subjects Between Structural Entities

Queues a job to transfer subjects from a source structural entity to a destination structural entity.

Required Permission

Edit:SubjectLocation

Endpoint: POST api/v1/structuralEntity/{destinationStructuralEntityKey}/subjects/transfer

Body:

json

{
  "SourceStructuralEntityKey": "source-key",
  "TransferMode": "Copy"
}

Where:

destinationStructuralEntityKey is the unique key of the destination structural entity (route parameter).
SourceStructuralEntityKey is the unique key of the source structural entity.
TransferMode controls how assignments are handled and can be:
- Copy (default) - Subjects are copied to the destination.
- Move - Subjects are moved from source to destination.

Returns:

202 Accepted - If the transfer job is successfully queued.
404 Not Found - If either the source or destination structural entity key does not exist.

Structure Type API

Get Structure Types

Required Permission

List:StructuralEntity

Endpoint: GET api/v1/structureType

Query Parameters (All optional):

Filtering:
- SearchTerm: String
- SubjectAssignable: Boolean
Paging:
- After: String
- Before: String
- First: Integer (Defaults to 20 if First or Last is not provided)
- Last: Integer
- OrderBy: String
- OrderDirection: Ascending or Descending

Example response:

json

{
  "PageInfo": {
    "HasNextPage": false,
    "HasPreviousPage": false,
    "StartCursor": "f36068c0-5b87-4b43-b3e0-6ee56d4865c2",
    "EndCursor": "f36068c0-5b87-4b43-b3e0-6ee56d4865c2",
    "TotalCount": 1
  },
  "Edges": [
    {
      "Node": {
        "Name": "Ward",
        "Key": "f36068c0-5b87-4b43-b3e0-6ee56d4865c2",
        "SubjectAssignable": true,
        "CustomFields": []
      },
      "Cursor": "f36068c0-5b87-4b43-b3e0-6ee56d4865c2"
    }
  ]
}

Get Structure Type By Key

Returns details about a structure type that matches a given key.

Required Permission

View:StructuralEntity

Endpoint: GET api/v1/structureType/{structureTypeKey}

Where:

structureTypeKey is the unique key for the structure type

Example response:

json

{
  "Name": "Ward",
  "Key": "f36068c0-5b87-4b43-b3e0-6ee56d4865c2",
  "SubjectAssignable": true,
  "CustomFields": []
}

Upsert (Create/Update) Structure Type

Creates or updates a structure type.

Required Permission

Create:StructuralEntity - If the structure type does not exist Edit:StructuralEntity - If the structure type already exists

Endpoint: PUT api/v1/structureType

Body:

json

{
  "Name": "Ward",
  "Key": "f36068c0-5b87-4b43-b3e0-6ee56d4865c2",
  "SubjectAssignable": true,
  "CustomFields": [
    {
      "TypeKey": "Text",
      "Name": "City",
      "Key": "city",
      "Required": false
    }
  ]
}

Where:

Name is the name of the structure type
Key is the unique key for the structure type
SubjectAssignable indicates whether subjects can be assigned to structural entities of this structure type
CustomFields is an array of custom field definitions for the structure type
- TypeKey is the key for the custom field type, e.g. Text for text
- Name is the name of the custom field
- Key is the unique key for the custom field
- Required indicates whether the custom field is required or not

The allowable TypeKey values are:

Date
DateTime
Email
PhoneNumber
Text
Number
Time
UserIdentifier

Returns:

201 Created - If the Structure Type was created.
200 Ok - If the Structure Type was updated.

Bulk Upsert (Create/Update) Structure Types

Creates or updates multiple Structure Types in a single request. A maximum of 20 structure types can be upserted at once.

Required Permission

Create:StructuralEntity - If a structure type in the list does not exist Edit:StructuralEntity - If a structure type in the list already exists

Endpoint: PUT api/v1/structureType/bulk

Body:

json

[
  {
    "Name": "Ward",
    "Key": "ward",
    "SubjectAssignable": true,
    "CustomFields": [
      {
        "TypeKey": "Text",
        "Name": "City",
        "Key": "city",
        "Required": false
      }
    ]
  },
  {
    "Name": "Hospital",
    "Key": "hospital",
    "SubjectAssignable": false,
    "CustomFields": []
  }
]

Where each item in the array contains:

Name is the name of the structure type
Key is the unique key for the structure type
SubjectAssignable indicates whether subjects can be assigned to structural entities of this structure type
CustomFields is an array of custom field definitions for the structure type
- TypeKey is the key for the custom field type, e.g. Text for text
- Name is the name of the custom field
- Key is the unique key for the custom field
- Required indicates whether the custom field is required or not

The allowable TypeKey values are the same as for the single upsert above.

Returns:

204 No Content - If all structure types were successfully created or updated.
400 Bad Request - If the request body is invalid, e.g. empty, more than 20 structure types provided, duplicate keys in the batch, or an item fails validation.
403 Forbidden - If the client does not have the required permission for any of the operations.

Delete Structure Type By Key

Deletes a structure type that matches a given key.

Required Permission

Delete:StructuralEntity

Endpoint: DELETE api/v1/structureType/{structureTypeKey}

Where:

structureTypeKey is the unique key for the structure type

Returns:

204 No Content - If the structure type was deleted.
404 Not Found - If the structure type is not found via the structureTypeKey.
409 Conflict - If the structure type is in use by one or more structural entities.

Group API

Get Groups

Required Permission

List:Group

Endpoint: GET api/v1/group

Query Parameters (All optional):

Filtering:
- SearchTerm: String
Paging:
- After: String
- Before: String
- First: Integer (Defaults to 20 if First or Last is not provided)
- Last: Integer
- OrderBy: String
- OrderDirection: Ascending or Descending

Example response:

json

{
  "PageInfo": {
    "HasNextPage": true,
    "HasPreviousPage": false,
    "StartCursor": "e30wOkRlZmF1bHQ6MjE=",
    "EndCursor": "e30wOkRlZmF1bHQ6MjE=",
    "TotalCount": 4
  },
  "Edges": [
    {
      "Node": {
        "Key": "my-group-key",
        "DisplayName": "My Group",
        "StructuralEntityKeys": ["se1", "se2"]
      },
      "Cursor": "e30wOkRlZmF1bHQ6MjE="
    }
  ]
}

Get Group By Key

Returns details about a group that matches a given key.

Required Permission

View:Group

Endpoint: GET api/v1/group/{groupKey}

Where:

groupKey is the unique key for the group

Example response:

json

{
  "Key": "my-group-key",
  "DisplayName": "My Group",
  "StructuralEntityKeys": ["se1", "se2"]
}

Delete Group By Key

Deletes a group that matches a given key.

Required Permission

Delete:Group

Endpoint: DELETE api/v1/group/{groupKey}

Where:

groupKey is the unique key for the group

Returns:

204 No Content - If the group was deleted.
404 Not Found - If the group is not found via the groupKey.

Upsert (Create/Update) Group

Creates or updates a Group.

Required Permission

Create:Group - If the structure type does not exist Edit:Group - If the structure type already exists

Endpoint: PUT api/v1/group

Body:

json

{
  "Name": "group-1",
  "Key": "group-1-key",
  "StructuralEntityKeys": ["SEK-1"]
}

Where:

Name is the name of the Group
Key is the unique key for the Group
StructuralEntityKeys is an array of Structural Entity Keys that belong to the Group

Returns:

201 Created - If the group was created.
200 Ok - If the group was updated.

Bulk Upsert (Create/Update) Groups

Creates or updates multiple Groups in a single request. A maximum of 20 groups can be upserted at once.

Required Permission

Create:Group - If a group in the list does not exist Edit:Group - If a group in the list already exists

Endpoint: PUT api/v1/group/bulk

Body:

json

[
  {
    "Name": "group-1",
    "Key": "group-1-key",
    "StructuralEntityKeys": ["SEK-1"]
  },
  {
    "Name": "group-2",
    "Key": "group-2-key",
    "StructuralEntityKeys": ["SEK-1", "SEK-2"]
  }
]

Where each item in the array contains:

Name is the name of the Group
Key is the unique key for the Group
StructuralEntityKeys is an array of Structural Entity Keys that belong to the Group

Returns:

204 No Content - If all groups were successfully created or updated.
400 Bad Request - If the request body is invalid, e.g. more than 20 groups provided or a group fails validation.
403 Forbidden - If the client does not have the required permission for any of the operations.

Data Set API

Refresh Data Set

Endpoint: POST api/v1/dataSet/{dataExtractKey}/refresh

Where:

dataExtractKey is the key of the data extract you want to refresh the data set for

Returns:

200 OK - If the data set was successfully refreshed
404 Not Found - If the data extract key does not exist

API ​

Authentication ​

Subject API ​

Get Subjects ​

Get Subject By Id ​

Update Subject By Id ​

Upsert (Create/Update) Subject ​

Bulk Upsert (Create/Update) Subjects ​

Subject Location API ​

Add Subject To Location ​

Remove Subject From Location ​

Subject Portal API ​

Get Subject Portal Users ​

Invite Subject To Portal ​

Remove Access to Portal ​

Subject Record API ​

Upload PDF ​

User API ​

Get Users ​

Add User to Groups ​

Remove User from Groups ​

Structural Entity API ​

Get Structural Entities ​

Get StructuralEntity By Key ​

Upsert (Create/Update) Structural Entity ​

Example Request ​

Bulk Upsert (Create/Update) Structural Entities ​

Example Request ​

Delete StructuralEntity ​

Transfer Subjects Between Structural Entities ​

Structure Type API ​

Get Structure Types ​

Get Structure Type By Key ​

Upsert (Create/Update) Structure Type ​

Bulk Upsert (Create/Update) Structure Types ​

Delete Structure Type By Key ​

Group API ​

Get Groups ​

Get Group By Key ​

Delete Group By Key ​

Upsert (Create/Update) Group ​

Bulk Upsert (Create/Update) Groups ​

Data Set API ​

Refresh Data Set ​

API

Authentication

Subject API

Get Subjects

Get Subject By Id

Update Subject By Id

Upsert (Create/Update) Subject

Bulk Upsert (Create/Update) Subjects

Subject Location API

Add Subject To Location

Remove Subject From Location

Subject Portal API

Get Subject Portal Users

Invite Subject To Portal

Remove Access to Portal

Subject Record API

Upload PDF

User API

Get Users

Add User to Groups

Remove User from Groups

Structural Entity API

Get Structural Entities

Get StructuralEntity By Key

Upsert (Create/Update) Structural Entity

Example Request

Bulk Upsert (Create/Update) Structural Entities

Example Request

Delete StructuralEntity

Transfer Subjects Between Structural Entities

Structure Type API

Get Structure Types

Get Structure Type By Key

Upsert (Create/Update) Structure Type

Bulk Upsert (Create/Update) Structure Types

Delete Structure Type By Key

Group API

Get Groups

Get Group By Key

Delete Group By Key

Upsert (Create/Update) Group

Bulk Upsert (Create/Update) Groups

Data Set API

Refresh Data Set