External APIs

Overview

Authentication

Cureatr API can be accessed over HTTPS with Basic HTTP Auth (the Authentication header for the requests, very standard for REST-like API).

An API user id and an api key need to be provisioned for an organization to access the API. To request API access, please contact your Client Services representative or support@cureatr.com . You will need to provide the description of the API use case, a contact email for the API account, and a name for the account.

You can find the documentation on Basic HTTP Auth here: http://en.wikipedia.org/wiki/Basic_access_authentication#Client_side. Note that Basic HTTP Auth requires the Api User ID and Api Key to be Base64 encoded in the Authorization header.

Parameters

Some APIs require parameters to be passed using HTTP form data encoding, others require the parameters to be passed via raw JSON, and some support both forms. Please look at the documentation and examples for guidance.

Responses

Unless specifically indicated in the documentation, you can expect for all API calls to return JSON responses.

A valid API call will have an return code of HTTP 200 OK, and will contain a status key in the JSON response that indicates whether the operation completed successfully or not.

  • status: ok indicates that the operation completed successfully

  • status: error indicates that an error has occurred, and additional information about the error is available under the message JSON key

Additionally, some reporting-type API calls may return HTTP 204 No Content to indicate that the response was blank because no results were produced

Invalid API calls may have one the following HTTP return codes

  • 400 - bad request; most likely the parameters don’t conform to the specification

  • 401 - unauthorized; no valid authorization user id and key provided

  • 403 - forbidden; client can not perform requested action

  • 404 - not found; invalid API endpoint specified

  • 500 - internal error; should not be encountered during normal operation

  • 503 - service unavailable; API servers are over capacity, please retry later

Testing

These API endpoints can be used to validate the API credentials and get familiar with parameters and responses

Test API endpoint

api_test(request)
GET /api/2015-02-01/util/test/{id}
POST /api/2015-02-01/util/test/{id}
PUT /api/2015-02-01/util/test/{id}

This simple API can be used for testing authentication and parameter enccoding

For POST and PUT, Content-type can be one of

  • ‘application/x-www-form-urlencoded’ (form post)

  • ‘application/json’ (JSON)

  • ‘application/xml’ (XML)

The body content should be encoded accordingly.

POST and PUT optional parameters

  • ‘message’: if provided, the value will be reflected back in the response

  • ‘error’: if provided, the return status will be an “error” instead of “ok”. This simulates “expected” API errors.

Sample usage:

curl -k -u $USER_ID:$API_KEY https://$CUREATR/api/2015-02-01/util/test/1
  {"status": "ok", "message": "GET OK", "id": "1"}

curl -k -u $USER_ID:$API_KEY https://$CUREATR/api/2015-02-01/util/test/1 -d "message=hello"
  {"status": "ok", "message": "hello", "id": "1"}

curl -k -u $USER_ID:$API_KEY https://$CUREATR/api/2015-02-01/util/test/1 -d "message=hello" -d "error=1"
  {"status": "error", "message": "hello", "id": "1"}

curl -k -u $USER_ID:$API_KEY https://$CUREATR/api/2015-02-01/util/test/1 -H 'Content-type:application/json' -d '{"message": "hello"}'
  {"status": "ok", "message": "hello", "id": "1"}

curl -k -u $USER_ID:$API_KEY https://$CUREATR/api/2015-02-01/util/test/1 -H 'Content-type:application/xml' -d '<message>hello</message>'
  {"status": "ok", "message": "hello", "id": "1"}

Example

Creating a thread (via curl and pretty-printing the response with python):

curl -u $USER_ID:$API_KEY https://api.cureatr.com/api/2014-08-01/thread/create -d subject=hi -d patient_name=bob -d message=hey \
-d recipients=foo@example.com -d recipients=bar@example.com -d recipients=baz@cureatr.com| python -m json.tool

API Modules

User APIs

counters(request)
GET /api/2016-11-01/user/counters/<user_id>
GET /api/2016-11-01/user/counters/<ou:user_id>

Return unread/unseen counters for user

Parameters:

  • user_id – user ID, or

  • uid – <ou:user_id>

Example Successful Response

{
    "status": "ok",
    "unseen": {"msg": 0, "ctn": 1},
    "unread": {"msg": 2, "ctn": 3}
}
search(request)
GET /api/2016-10-01/user/search

Search for users

Query Parameters:

  • service – The service to return users for.

Example Successful Response

{
  "status": "ok",
  "users": [
    {
      "last_name": "Smith",
      "managed": "Y",
      "features": "",
      "latest_agreement_version": "1.0",
      "time_created": "2015-08-25T14:51:04.740000",
      "has_password": "Y",
      "account_status": "",
      "location_detail": "",
      "id": "55dc80d8c5cc41034dc8081b",
      "city": "",
      "first_name": "Roger",
      "user_id": "rsmith@example.com",
      "covering_user_id": "",
      "title": "Medical Assistant",
      "associated_ou": "",
      "app_platform": "android",
      "state": "",
      "location": "",
      "app_version": "1337.1337.1337-1337",
      "status_message": "On duty",
      "email": "rsmith@example.com",
      "bounced_emails": "",
      "zip_code": "",
      "status": "off",
      "time_last_activity": "2016-08-29T17:51:20.340000",
      "legal_agreement": "tos",
      "specialty": "Dermatology",
      "services": [
        "First Call"
      ],
      "admin_permissions": "",
      "primary_ou": "cureatr",
      "reporting_tags": [],
      "time_first_login": "2015-08-25T14:53:04.778000",
      "has_pin": "Y",
      "acceptance_date": "2015-08-25 14:53:34"
    },
    {
      "last_name": "Trump",
      "managed": "",
      "features": "",
      "latest_agreement_version": "1.0",
      "time_created": "2015-09-01T19:50:17.949000",
      "has_password": "Y",
      "account_status": "",
      "location_detail": "",
      "id": "55e601795b3f051ad3c199f1",
      "city": "",
      "first_name": "Hillary",
      "user_id": "htrump@example.com",
      "covering_user_id": "",
      "title": "Nursing Student",
      "associated_ou": "",
      "app_platform": "android",
      "state": "",
      "location": "",
      "app_version": "1920.1920.1920-1920",
      "status_message": "Out to lunch",
      "email": "htrump@example.com",
      "bounced_emails": "",
      "zip_code": "",
      "status": "busy",
      "time_last_activity": "2016-10-06T20:24:04.485000",
      "legal_agreement": "tos",
      "specialty": "Dentistry",
      "services": [
        "4th floor A",
        "ER",
        "5th, 7th, 9th floor",
        "First Call"
      ],
      "admin_permissions": "admin-institution-updates:*|admin-user-audit:*|admin-institution-provisioning:*|admin-user-update-pager:*|admin-user-update-permissions:*|admin-ctn-reporting:*|admin-reporting:*|view-phi:*|admin-user-activation:*|admin-api-user-management:*|admin-ctn-management:*|admin-user-provisioning:*|filearea-write:*|filearea-read:*|admin-user-updates:*|admin-user-update-tags:*|inst-admin:*",
      "primary_ou": "cureatr",
      "reporting_tags": [
        "tag1",
        "tag2"
      ],
      "time_first_login": "2015-09-02T17:33:30.776000",
      "has_pin": "Y",
      "acceptance_date": "2015-09-02 17:34:50"
    }
  ]
}

Messaging APIs

messages(request)
GET /api/2014-08-01/thread/{thread_id}/messages

Retrieve messages for the thread identified by “thread_id”

Example Successful Response

{
    "status": "ok",
    "thread": {
        "id": "55198cb351c356a2de0603bf",
        "subject": "API integrations are the best",
        "patient_name": "... this is optional ...",
        "user_id": "55198cb351c356a2de0603ae",
        "messages": [
            {
                "content": "Message content",
                "id": "55198cb351c356a2de0603c1",
                "seq": 1,
                "time_created": "2015-04-02T22:42:59.848000",
                "user_id": "55198cb351c356a2de0603ae"
            },
            {
                "content": "..."
            }
        ]
    },
    "users": [
        {
            "email": "user1@amsconnect.co",
            "id": "5519b44451c356ab9a234a1e",
            "primary_ou": "cureatr",
            "user_id": "user1"
        },
        {
            "email": "..."
        }
    ]
}

Example Error Response

{
    "status": "error",
    "message": "not authorized"
}
page(request)
POST /api/2014-08-01/page

Relay a pager message to the user

Form Parameters:

  • message – The message to be delivered to the user

  • pager_number – The pager number of the user

Rather than a form POST, the API also accepts a JSON body containing the specified parameters.

Example Successful Response Paging a Single User

{
    "status": "ok",
    "message_id": "55198cb351c356a2de0603bf",
    "thread_id": "55198cb351c356a2de0603ae",
}

Example Successful Response Paging Multiple Users in a Service

{
    "status": "ok",
    "messages": [
        {
            "message_id": "55198cb351c356a2de0603bf",
            "thread_id": "55198cb351c356a2de0603ae",
        }, ...
    ]
}

Example Error Response

{
    "status": "error",
    "message": "No pager number provided"
}
thread_create_20140801(request)
POST /api/2014-08-01/thread/create

Create a new thread. Currently, the API user can only send messages to users within the same organization.

Form Parameters:

  • sender – (optional) The email of the sender. If it corresponds to a valid Cureatr account, the message will appear to come from that user instead of the API user.

  • subject – The subject of the thread

  • message – The message to be delivered to the recipients

  • recipients – one or multiple recipients to deliver the message to, identified by email addresses (for multiple recipients simply repeat this parameter multiple times)

  • services – (optional) Message members of this service

  • attachment_ids – (optional) ids of previously created attachments

  • patient_name – (optional) name of the patient that the message thread refers to

  • pid – (optional) master id of the patient that the message thread refers to

  • patient_event_id – (optional) id of the patient event that the message thread refers to

  • urgent – (optional) 1 to indicate an urgent message

  • validation – (optional) relaxed (default) or strict

Note

  • if validation=strict, then if any of the addresses are invalid (don’t match Cureatr accounts / accounts are locked / accounts are in a different institution / etc), a message will NOT be sent, and response will be {"status" : "error", "recipients_error" : [...]}

  • if validation=relaxed (default, if not specified), then if any emails are valid, the message is sent, and you get back {"status" : "ok", "thread_id" : "...", "message_id": "...", "recipients_ok" : [...], "recipients_error" : [...]}. If none of the recipients are valid, you get the error response.

Rather than a form POST, the API also accepts a JSON body containing the specified parameters. In that case, “recipients” needs to always be an array with 1 or more elements.

Example Successful Response

{
    "message_id": "53dbff5151c356e15d4fdd32",
    "recipients_error": [
        "foo@example.com",
        "bar@example.com"
    ],
    "recipients_ok": [
        "baz@amsconnect.co"
    ],
    "status": "ok",
    "thread_id": "53dbff5151c356e15d4fdd30"
}

Example Error Response

{
    "message": "Invalid Request",
    "reason": {
        "message": "Missing value",
        "subject": "Missing value"
    },
    "status": "error"
}

Controller for API calls for external services

attachment_get(request)
GET /api/2014-08-01/attachment/(attachment_id)

Retrieve an attachment record

Example Successful Response

{
    "status": "ok",
    "attachment": {
        "id": "55236f2951c356c8d0e5901b",
        "mime_type": "image/jpeg",
        "name": "picture.jpg",
        "size": 31337,
        "time_created": "2015-04-07T05:46:17.510801",
        "user_id": "55236f2951c356c8d0e5901a"
    }
}

Example Error Response

{
    "status": "error",
    "message": "invalid id"
}
attachment_save(request)
POST /api/2014-08-01/attachment

Create an attachment record.

The POST body should follow http://tools.ietf.org/html/rfc1867

Form Parameters:

  • attachment – Uploaded file data

Request Headers:

Example Successful Response

{
    "status": "ok",
    "attachment": {
        "id": "55236f2951c356c8d0e5901b",
        "mime_type": "image/jpeg",
        "name": "picture.jpg",
        "size": 31337,
        "time_created": "2015-04-07T05:46:17.510801",
        "user_id": "55236f2951c356c8d0e5901a"
    }
}
message_contents(request)
GET /api/2017-09-01/message/(message_id)/contents

Get contents of the message.

Example Successful Response

{
    "status": "ok",
    "message": {
        "id": "59b0503451c3562fc45a2c9e",
        "user_id": "5519b44451c356ab9a234a1e",
        "seq": 2,
        "content": "this is a test message",
        "time_created": "2015-01-27T08:21:57.770000+00:00"
    },
    "user": {
        "email": "user1@amsconnect.co",
        "id": "5519b44451c356ab9a234a1e",
        "primary_ou": "cureatr",
        "user_id": "user1"
    }
}

Example Error Response

{
    "status": "error",
    "message": "not authorized"
}
message_status(request)
GET /api/2014-08-01/message/(message_id)/status

Get read status of the message.

Example Successful Response

{
    "status": "ok",
    "statuses": [
        {
            "status": "read",
            "user": "alexkhomenko@amsconnect.co",
            "time_read": "2015-01-27T08:21:57.770000+00:00"
        }
    ]
}

Example Error Response

{
    "status": "error",
    "message": "not authorized"
}
post(request)
POST /api/2014-08-01/message

Post a message into the existing thread

Form Parameters:

  • thread_id – The id of the previously created thread

  • message – The message to be delivered to the recipients

  • attachment_ids – (optional) ids of previously created attachments

Rather than a form POST, the API also accepts a JSON body containing the specified parameters.

Example Successful Response

{
    "status": "ok",
    "message_id": "54db4f30d5593017978115e6"
}

Example Error Response

{
    "status": "error",
    "message": "not authorized"
}

User Management APIs

_create_user(params)
POST /api/2015-02-01/admin/users

Create a new user

Form Parameters:

  • first_name – First Name

  • last_name – Last Name

  • email – Email

  • specialty – Specialty

  • title – Title

  • user_id – (optional) Unique Identifier. If not set, will default to email

  • primary_ou – (optional) Primary Institution id, default is the API user’s primary_ou

  • sso – (optional) User authenticates via SSO, True or False (default)

  • managed – (optional) Specifies if user is managed by the institution, True (default) or False

  • associated_ou – (optional) Pipe-delimited list of OUs that the user can communicate with

  • admin_permissions – (optional) Pipe-delimited list of administrative permissions granted to the user, see Note for syntax

  • legal_agreement – (optional) Name of the custom legal agreement

  • send_activation_email – (optional) True (default) or False

  • pager_number – (optional) If pager integration enabled for the institution, associate a pager number.

  • tags – (optional) Pipe-delimited list of tags

  • location – (optional) Location

  • location detail – (optional) Location details

  • city – (optional) City

  • state – (optional) State

  • has_password – (optional) whether or not te user is managed or not

Note

  • Each admin_permission should be of the form <action>:<scope> where action specifies the granted action the user is allowed to perform and scope specifies the OU’s the grant applies to. Multiple OU’s can be specified be separating each with a / (see examples). If an OU is suffixed with a +, the grant will also apply to all child OU’s

Actions (one of)

  • inst-admin - user is able to manage the OU

  • view-phi - user is able to view PHI in admin

  • api-manage-accounts - user is able to use the API

Examples

  • inst-admin:cureatr

  • inst-admin:cureatr+

  • inst-admin:cureatr|view-phi:cureatr/kureatr

Example JSON Request

{
    "first_name": "John",
    "last_name": "Doe",
    "email": "jdoe@amsconnect.co",
    "primary_ou": "cureatr",
    "specialty": "Specialty",
    "title": "Title"
}

Example Successful Response

{
    "status": "ok",
    "user": {
        "acceptance_date": "",
        "account_status": "",
        "admin_permissions": "",
        "app_platform": "",
        "app_version": "",
        "associated_ou": "",
        "city": "",
        "email": "jdoe@amsconnect.co",
        "first_name": "John",
        "has_password": "Y",
        "has_pin": "",
        "id": "551d78a051c356fc3c61b4ba",
        "last_name": "Doe",
        "latest_agreement_version": "",
        "legal_agreement": "",
        "location": "",
        "location_detail": "",
        "managed": "Y",
        "primary_ou": "cureatr",
        "specialty": "Specialty",
        "state": "",
        "time_created": "2015-04-02T17:13:04.596000",
        "title": "Title",
        "user_id": "jdoe@amsconnect.co",
        "covering_user_id": "",
        "services": ["First Floor", "Second Floor"],
        "status": "available",
        "status_message": "",
        "zip_code": ""
    }
}

Example Error Response

{
    "status": "error",
    "message": "A user with these credentials already exists"
}
_find_user(identifier)
GET /api/2015-02-01/admin/users/<user_id>
GET /api/2015-02-01/admin/users/<ou:user_id>

Get the user’s information

Parameters:

  • user_id – user ID, or

  • uid – <ou:user_id>

Note

  • Within the system, the user is uniquely identified by the UID which is a combination of institution and user identifier. The ‘user identifier’ will be either the user_id (if passed when creating the user) or the user’s email (if user_id is not explicitly set).

Example Successful Response

{
    "status": "ok",
    "user": {
        "acceptance_date": "",
        "account_status": "",
        "admin_permissions": "",
        "app_platform": "",
        "app_version": "",
        "associated_ou": "",
        "city": "",
        "email": "jdoe@amsconnect.co",
        "first_name": "John",
        "has_password": "Y",
        "has_pin": "",
        "id": "551d78a051c356fc3c61b4ba",
        "last_name": "Doe",
        "latest_agreement_version": "",
        "legal_agreement": "",
        "location": "",
        "location_detail": "",
        "managed": "Y",
        "primary_ou": "cureatr",
        "specialty": "Specialty",
        "state": "",
        "time_created": "2015-04-02T17:13:04.596000",
        "title": "Title",
        "user_id": "jdoe@amsconnect.co",
        "covering_user_id": "",
        "services": ["First Floor", "Second Floor"],
        "status": "available",
        "status_message": "",
        "zip_code": ""
    }
}

Example Error Response

{
    "status": "error",
    "message": "user [jjdoe@amsconnect.co] not found"
}
_update_user(identifier, params)
PUT /api/2015-02-01/admin/users/<user_id>
PUT /api/2015-02-01/admin/users/<ou:user_id>

Update a user

Parameters:

  • user_id – user ID, or

  • uid – <ou:user_id>

For regular updates, the parameters are one or more of the parameters from User Create, all optional.

To remove a pager, send in a special value as follows:

Form Parameters:

  • pager_number – remove

For Activating or Deactivating a user, send the ‘account_status’ parameter as follows:

Form Parameters:

  • account_status – active or inactive

To resend the activation email, send the ‘resend_activation_email’ parameter as follows:

Form Parameters:

  • resend_activation_email – True (default) or False

To update services:

Form Parameters:

  • services – List of services to assign user to.

To update an external user_id:

Form Parameters:

  • update_uid – if Y then use the email to find a user and change their user_id

To clear bounced email dropping:

Form Parameters:

  • bounced_emails – clears flag to drop emails to an email address associated with the user if an email had previously bounced

Note

  • Within the system, the user is uniquely identified by the UID which is a combination of institution and user identifier. The ‘user identifier’ will be either the user_id (if passed when creating the user) or the user’s email (if user_id is not explicitly set).

Example JSON Request

{
    "email": "jdoe@amsconnect.co",
    "specialty": "Specialty 1",
    "title": "Title 1",
    "services": ["First floor", "On Call"]
}

Example Successful Response

{
    "status": "ok"
}

Example Error Response

{
    "status": "error",
    "message": "user [jjdoe@amsconnect.co] not found"
}
users_list(request)
GET /api/2015-02-01/admin/users

List users of an organization

Query Parameters:

  • ou – OU ID to list

  • children – true if list should include child institutions, false otherwise. Default true

  • format – csv or json (see note). Defaults to csv

Response Headers:

Note

  • CSV contents of the report will be streamed to the client as a chunked response and should be consumed until exhaustion

  • JSON contents will be streamed as a chunked response in a series of json lines separated by newlines (\n), see jsonlines.org for more details. Clients should expect one JSON encoded record per line of the response.

Institution Management APIs

institution_services_get(request)
GET /api/2018-04-01/admin/services/{ou}

Get the current services for an OU

Parameters:

  • ou – OU ID

Example Successful Response

{
    "status": "ok",
    "services": ["service one", "service two", ...]
}

Example Error Response

{
    "status": "error",
    "message": "not authorized"
}
institution_services_update(request)
PUT /api/2018-04-01/admin/services/{ou}

Update the list of services for an institution

Parameters:

  • ou – OU ID

Pass a JSON dict as a body containing the following parameters

Parameters:

  • services – updated list of services that replaces the existing ones. If services are removed, they are cleared from users and schedules that refer to them

  • user_updates – (optional) a dictionary of <old_service>:[<new_service1>, <new_service2>…] mappings that will update the existing services that users and schedules refer to

Example Successful Response

{
    "status": "ok",
    "services": ["service one", "service two", ...],
    "warnings": [
        "Service [service old] is currently in use with CTN subscription [sub_id]"
    ],
}

Example Error Response

{
    "status": "error",
    "message": "not authorized"
}

Patient Management APIs

Controller for API calls for external patient services

create_or_update(request)
POST /api/2014-08-01/patients

Create or update a patient record.

PUT /api/2014-08-01/patients/(pid)

Update the patient record identified by ‘pid’

Pass a JSON body containing the patient record.

The two fields below uniquely identify the patient in our system:

  • pid (required for POST) is the organization’s unique ID of the patient

  • primary_ou (optional) default is the API user’s primary_ou

Demographics fields. Required to create. All must be present to update.

Other fields

  • ssn patients social security number

  • medicaid_id patients Medicaid ID

  • pcm_enabled is a boolean, true (default) if this patient should be searchable for Patient-Centric Messaging, false if not

  • associated_ou (optional) a list of OUs in the primary OU’s hierarchy that this patient is visible in

  • consents (optional) array of consent specifications, consisting of “add:<authority>:<date>” and “remove:<authority>:<date>”

  • address (optional) consists of a street_address, street_other, city, state, zip, country. Either a zip or (street_address, city`, state, zip) are required.

  • home_phone (optional)

  • mobile_phone (optional)

  • email (optional)

  • preferred_language (optional) The ISO-639-1 alpha 2 code for the language, optionally followed by a hyphen and the ISO-3166-1 alpha 2 code for the region; e.g. “en” for English, or “en-us” for American English versus “en-gb” for United Kingdom English.

  • patient_attributes (optional) See cureatr.model.pii.PatientAttributes

Example JSON Request

{
    "pid": "777565",
    "primary_ou": "cureatr",
    "dob": "1972-11-02",
    "sex": "M",
    "name": {
        "prefix": "MR",
        "given": "HENRY",
        "middle": "S",
        "family": "WALLACE",
        "suffix": "JR"
    },
    "pids": [
        {"authority": "MRN", "identifier": "777565"},
        {"authority": "MPI", "identifier": "26WFR996"}
    ],
    "pcm_enabled": true,
    "associated_ou": [
        "cureatr:1234",
        "cureatr:5678",
        "cureatr:9090"
    ],
    "consents": ["add:hie-ny:03-04-2014", "remove:hie-ny:01-01-2014"],
    "address": {
        "street_address": "123 Any St.",
        "city": "Anytown",
        "state": "NY",
        "zip": "12345",
        "country": "us"
    }
}

Example Successful Response

{
    "status": "ok"
}
subscribe(request)
POST /api/2014-08-01/patients/(pid)/subscribe

Pass a JSON body containing the subscription data.

The two fields below uniquely identify the patient in our system:

  • pid in the url is the organization’s unique ID for the patient

  • primary_ou (optional) default is the API user’s primary_ou

Other fields:

  • sid (required) unique subscription id

  • tags (optional) array of tags to apply to subscription, if empty array then disable subscription

  • consents (optional) array of consent specifications, consisting of “add:<authority>:<date>” and “remove:<authority>:<date>”

Example JSON Request

{
    "primary_ou": "cureatr",
    "sid": "s3722",
    "tags": ["tag1", "tag2"],
    "consents": ["add:hie-ny:03-04-2014", "remove:hie-ny:01-01-2014"]
}
class PatientAttributes(storage=None, **kwargs)

Additional patient fields to sync to Salesforce

  • notes (optional) patient notes

  • control (optional) boolean, indicates patient is a control subject

  • email_consent (optional) boolean, True if this patient has consented to email. Default is False

  • pcp_name (optional) primary care provider full name

  • pcp_phone (optional) primary care provider phone number

  • pcp_npi (optional) primary care provider NPI number

  • pcp_address (optional) primary care provider street address

  • pcp_city (optional) primary care provider city

  • pcp_state (optional) primary care provider state

  • pcp_zip (optional) primary care provider zip

  • plan_group_id (optional) Group ID of the healthcare plan

  • sms_consent (optional) boolean, True if this patient has consented to sms. Default is False

Rx History APIs

Pager Management APIs

get_service_pagers(request)
GET /api/2019-03-01/pager/service

Get a list of pagers currently assigned to a service

Form Parameters:

  • iid – The institution id of the role, passed as a query parameter

Example Successful Response

{
    "status": "ok",
    "pagers": [
        {
            "pager_number": "...",
            "service": "..."
        },
        ...
    ]
}

Example Error Response

{
    "status": "error",
    "message": "..."
}
update_service_pager(request)
POST /api/2019-03-01/pager/service

Assign a pager number to a service

Form Parameters:

  • pager_number – The pager number of the user

  • iid – The institution id of the service

  • service – The name of the service, pass empty string to unset service from pager

Rather than a form POST, the API also accepts a JSON body containing the specified parameters.

Example Successful Response

{
    "status": "ok",
}

Example Error Response

{
    "status": "error",
    "message": "..."
}

Recipient Group Management APIs

create_recipient_group(request)
POST /api/2019-03-01/recipient_groups

Create a new recipient group

Form Parameters:

  • iid – The IID of the institution to create the recipient group under, only root IID allowed.

  • name – The name of the recipient group

  • recipient_ids – A list of recipients identified by their external user ids

Example Successful Response

{
    "status": "ok",
    "recipient_group": {}
}

Example Error Response

{
    "status": "error",
    "message": "..."
}
delete_recipient_group(request)
DELETE /api/2019-03-01/recipient_groups/{group id}

Delete a recipient group

Example Successful Response

{
    "status": "ok",
}

Example Error Response

{
    "status": "error",
    "message": "..."
}
list_recipient_groups(request)
GET /api/2019-03-01/recipient_groups

Get a list of recipient groups for an IID

Query Parameters:

  • iid – The IID of the institution containing the recipient groups

Example Successful Response

{
    "status": "ok",
    "recipient_groups": [{}, ...]
}

Example Error Response

{
    "status": "error",
    "message": "..."
}
update_recipient_group(request)
PUT /api/2019-03-01/recipient_groups/{group id}

Update a recipient group

Form Parameters:

  • name – The name of the recipient group

  • recipient_ids – A list of recipients identified by their external user ids

Example Successful Response

{
    "status": "ok",
    "recipient_group": {}
}

Example Error Response

{
    "status": "error",
    "message": "..."
}