Osma API

Introduction
Authentication
Errors
Pagination
Webhooks
Metadata
Idempotency
Versioning
Rate Limits
Request IDs
Core resources
Tasks
Members
Users
Files
Osma API
Introduction
Authentication
Errors
Pagination
Webhooks
Metadata
Idempotency
Versioning
Rate Limits
Request IDs
Core resources
Tasks
The task object
Create a task
Get one task
Update a task
Delete a task
List all tasks
Members
The member object
Create a member
Get one member
Update a member
Delete a member
List all members
Users
The user object
Get one user
List all users
Files
Get one file

Introduction

The Osma API lets you integrate your own systems so you can manage all your Osma data automatically.

The API provides a set of endpoints that follow the REST principals. It accepts JSON-formatted request bodies and returns JSON responses as well as standard HTTP response status codes.

In addition to REST endpoints, you can configure webhooks to provide you with real-time updates when certain events are triggered.

Osma’s API can be used in “test mode” and “live mode”. Test mode enables you to test your integration without “polluting” any data in live mode. The API key you use to authenticate a request determines which mode the request will be processed in.

OpenAPI Specifications
get
https://api.osma.com/spec/openapi.yaml
get
https://api.osma.com/spec/openapi.json

Authentication

Osma’s API uses API keys to authenticate requests, that you must pass as the osma-api-key request header. You can view and manage your API keys in the Osma Dashboard.

There are two kinds of API keys: live mode (prefixed with sk_live_) and test mode (prefixed with sk_test_). Most resources contain a boolean field called live_mode that represents which mode they were created in. Note that some resources, such as users, are identical in both modes.

Authenticated Request
curl --request GET \
     --url https://api.osma.com/tasks \
     --header 'osma-api-key: sk_test_27NecW2jYLhV2gkB5lby1F22Fxv'

Errors

To provide a predictable integration experience, the API uses a consistent format for all errors returned. These are returned in the response body in addition to the standard HTTP response status codes.

Attributes
type
enum
The category of error.
Possible enum values
api_error
Something went wrong on Osma's end. Status will be in the 5xx range.
invalid_request_error
The request is invalid. The `code` and `params` fields will provide more detail. Status will be in the 4xx range.
idempotency_error
Invalid idempotency or a request was made with an existing idempotency key but different parameters.
rate_limit_error
The rate limit for the endpoint has been exceeded by the organization making the request.
code
enum
Possible enum values
parameter_missing
One or more parameters required for the request are missing.
resource_not_found
A resource requested or required for the request could not be found.
resource_already_exists
The resource trying to be created already exists.
task_template_not_found
A task_template referenced in the request could not be found. Double check the ID provided, and make sure the ID provided is in the same mode (live/test).
user_not_found
A user referenced in the request could not be found. Double check the ID provided, and make sure the ID provided is in the same mode (live/test).
user_not_permitted
A user referenced in the request is not permitted to be assigned to the resource.
member_not_found
A member referenced in the request could not be found. Double check the ID provided, and make sure the ID provided is in the same mode (live/test).
invalid_status
The status of one or more resources in the request is incompatible with the operation.
message
string
A human readable explanation of the error.
params
array
An array containing additional information if the error is related to one or more invalid request parameters.
Child properties
param
string
The object key of the parameter that has failed validation.
message
string
A human readable explanation of why validation failed.
Response
{
  "message": "Invalid request parameter(s)",
  "type": "invalid_request_error",
  "params": [
    {
      "param": "date_of_birth",
      "message": "date_of_birth must be a valid ISO 8601 date string"
    }
  ]
}

Webhooks

Osma’s API provides the ability to setup webhooks to notify your systems when an event occurs (for example when a task is completed). A webhook event consists of a POST request with a JSON payload to an endpoint of your choice (the "webhook endpoint").

Webhook endpoints can be registered and managed through the Osma Dashboard. They can be registered in test or live mode and configured to “listen” for one or more specific events. Webhook endpoints must use https.

Each webhook endpoint is assigned a “signing secret”. Each webhook event (request to your endpoint) will contain a request header called osma-signature. In combination these can be used to validate that a webhook event was sent by Osma, and can be used to prevent replay attacks.

Requests to webhook endpoints that fail will be retried on an exponential backoff schedule.

Webhook Event Attributes
id
string
KSUID
Unique identifier for the webhook event.
event
enum
The event that triggered the webhook.
Possible enum values
tasks.created
tasks.updated
tasks.completed
tasks.deleted
created_at
string
ISO 8601 Timestamp
Timestamp when the webhook event was triggered.
data
object
The resource for which the webhook was triggered, for example a task object.

Metadata

All resources that are updatable, such as members and tasks, contain a metadata object field that you can store custom key-value pairs on. This is useful for storing your own reference IDs.

Each metadata object can contain up to 50 keys. Key names can be up to 50 characters long, and values up to 500 characters long.

Request
curl --request POST \
     --url https://api.osma.com/members/mem_28bnB4MCh2qygiyaHQ6jNGUbl10 \
     --header 'osma-api-key: sk_test_27NecW2jYLhV2gkB5lby1F22Fxv' \
     --data '{
        "metadata": {
          "internal_member_id": "92cb3caf-00ea-4e24-8c30-32e23d2253d5"
        }
      }'
Response
{
  "id": "mem_28bnB4MCh2qygiyaHQ6jNGUbl10",
  "created_at": "2022-05-02T12:20:13.080819+00:00",
  "updated_at": "2022-05-02T12:20:13.080819+00:00",
  "name": "Daisy Demo",
  "email": "daisy@osma.com",
  "status": "active",
  "status_transitions": [],
  "date_of_birth": "1993-09-16",
  "biological_sex": "female",
  "gender_identity": null,
  "live_mode": false,
  "metadata": {
    "internal_member_id": "92cb3caf-00ea-4e24-8c30-32e23d2253d5"
  }
}

Idempotency

The API supports idempotency on all POST (create / update) requests via the HTTP idempotency header. When the header is provided, POST requests can be retried without the risk of duplicate resources being created (or other side effects). The API caches the first response (even if it was an error) and returns it on subsequent requests with the same idempotency key.

Idempotency keys are created by the API consumer and can be any unique string up to 255 characters long, such as UUIDs. When retrying an idempotent request, the parameters must remain the same or the API returns an error.

Request
curl --request POST \
     --url https://api.osma.com/tasks \
     --header 'osma-api-key: sk_test_27NecW2jYLhV2gkB5lby1F22Fxv'
     --header 'idempotency-key: 534fee46-cbaa-4bb7-b5ae-cee5bae4679d'
     --data '{
        ...
      }'

Versioning

As of today, no backwards-incompatible changes have been made to the API. When they are made, the Osma API will use ISO-8601 dates to represent new version.

The default API version of an organization can be managed in the Osma dashboard, which will affect all subsequent API requests. However, this can be overridden by setting the osma-api-version header to a specific ISO-8601 date. This means backwards-incompatible changes to the API can be handled incrementally per-endpoint.

Request
curl --request GET \
     --url https://api.osma.com/tasks \
     --header 'osma-api-key: sk_test_27NecW2jYLhV2gkB5lby1F22Fxv'
     --header 'osma-api-version: 2022-05-22'

Rate Limits

Osma’s API uses rate limits to prevent unexpected bursts of traffic. Each endpoint is limited to 100 requests per second in live mode, and 20 requests per second in test mode.

When exceeded, the API will return an error with HTTP status code 429.

These limits can be increased if required - please contact Osma support to request this.

Error Response
{
  "type": "rate_limit_error",
  "message": "Rate limit exceeded",
  "status_code": 429
}

Request IDs

Each request made to the API is associated with a request identifier, that the API returns in the request-id response header. Logs will be viewable in the Osma dashboard in the near future. Providing request ids when contacting support regarding API questions or issues helps to provide support quicker.

Tasks

This resource represents the tasks that are created and completed as part of your organization's workflows.

Each task is essentially an instance of a "task template". These templates are created in the Osma dashboard. They can be built using our no-code template builder, or they can be "renderless". Renderless tasks have an external_url field which represents where the task should be completed. For example, if you have a task to review a failed payment in Stripe, it could be the url to the failed payment in the stripe dashboard.

Endpoints
post
/tasks
get
/tasks/:id
post
/tasks/:id
delete
/tasks/:id
get
/tasks

The task object

Attributes
template
string
The API reference of the template this task should use. Can only be set when the task is created.
status
enum
Current status of this task resource. Defaults to ready.
Possible enum values
ready
in_progress
completed
deleted
assigned_to
string
KSUID
The id of the user the task is assigned to. Null when the task is unassigned.
created_by
string
If the task was created in the dashboard, the id of the user who created it. Null when the task was created via the API.
description
string
A short description to help identify the task to users. Visible in the dashboard.
parameters
object
The template parameters to use for this task.
data
object
Data created in the process of completing this task, such as the values of any input elements in the task template.
priority
enum
Possible enum values
routine
time_sensitive
high_priority
urgent
Additional Attributes
Expand all
id
string
KSUID
Unique identifier for the task resource.
created_at
string
ISO 8601 Timestamp
Timestamp representing when the task resource was created.
updated_at
string
ISO 8601 Timestamp
Timestamp representing when the task resource was last updated.
status_transitions
array
An array of objects representing transitions from one status to another.
Child properties
timestamp
string
ISO 8601 Timestamp
Timestamp when the transition occured.
from
string
Status of the resource prior to the transition.
to
string
Status of the resource after the transition.
member
string
KSUID
The id of the member the task is related to. Null when the task is not related to a member.
external_url
string
URL
For renderless templates, the external where the task should be completed.
live_mode
boolean
Whether the task resource exists in live mode. If false, the resource exists in test mode.
metadata
object
A key-value dictionary where API consumers can store metadata, such as their own reference IDs.

Task Object
{
  "id": "task_2BU1ecNdKXgRfRxPSjFDXfmv0tV",
  "template": "update_blood_pressure",
  "status": "in_progress",
  "priority": "routine",
  "member": "mem_2C7PFuvIgJJyrEnf9SxOgndg3Fv",
  "description": "Update member's blood pressure",
  "parameters": {},
  "data": {
    "blood_pressure": {
      "systolic": "120",
      "diastolic": "80"
    }
  },
  "external_url": null,
  "live_mode": false,
  "metadata": {}
  "created_at": "2022-07-04T14:45:45.338647+00:00",
  "updated_at": "2022-07-19T15:03:02.991466+00:00",
  "status_transitions": [
    {
      "to": "in_progress",
      "from": "ready",
      "timestamp": "2022-07-04T14:45:45.486051+00:00"
    }
  ]
}

Create a task

Request Parameters
template
string
Required
The API reference of the template this task should use. Can only be set when the task is created.
parameters
object
The template parameters to use for this task.
assigned_to
string
KSUID
The user to assign this task to. Will be shown as "unassigned" if left null.
priority
enum
Possible enum values
routine
time_sensitive
high_priority
urgent
description
string
A short description to help identify the task to users. Visible in the dashboard.
member
string
KSUID
The id of the member the task is related to.
More Parameters
Expand all
template_version
integer
The version of the template to use for this task. Defaults to the latest version.
external_url
string
URL
For renderless templates, the external where the task should be completed.
metadata
object
A key-value dictionary where API consumers can store metadata, such as their own reference IDs.
Returns

Returns a task object with HTTP status code 201 if successful or an error if one or more request parameters are invalid.

Request
curl --request POST \
     --url https://api.osma.com/tasks \
     --header 'osma-api-key: sk_test_27NecW2jYLhV2gkB5lby1F22Fxv'
     --data '{
        "template": "update_blood_pressure",
        "description": "Update member's blood pressure",
        "member": "mem_2C7PFuvIgJJyrEnf9SxOgndg3Fv"
      }'
Response
{
  "id": "task_2BU1ecNdKXgRfRxPSjFDXfmv0tV",
  "template": "update_blood_pressure",
  "status": "ready",
  "priority": "routine",
  "member": "mem_2C7PFuvIgJJyrEnf9SxOgndg3Fv",
  "description": "Update member's blood pressure",
  "parameters": {},
  "data": {},
  "external_url": null,
  "live_mode": false,
  "metadata": {}
  "created_at": "2022-07-04T14:45:45.338647+00:00",
  "updated_at": "2022-07-04T14:45:45.338647+00:00",
  "status_transitions": []
}

Get one task

Retrieves a task based on the id provided in the URL. Returns a task object with HTTP status code 200 if a valid ID is provided or an error if no task is found in the same mode as the API key provided.

Request
curl --request GET \
     --url https://api.osma.com/tasks/task_2BU1ecNdKXgRfRxPSjFDXfmv0tV \
     --header 'osma-api-key: sk_test_27NecW2jYLhV2gkB5lby1F22Fxv'
Response
{
  "id": "task_2BU1ecNdKXgRfRxPSjFDXfmv0tV",
  "template": "update_blood_pressure",
  "status": "ready",
  "priority": "routine",
  "member": "mem_2C7PFuvIgJJyrEnf9SxOgndg3Fv",
  "description": "Update member's blood pressure",
  "parameters": {},
  "data": {},
  "external_url": null,
  "live_mode": false,
  "metadata": {}
  "created_at": "2022-07-04T14:45:45.338647+00:00",
  "updated_at": "2022-07-04T14:45:45.338647+00:00",
  "status_transitions": []
}

Update a task

Updates a task based on the id provided in the URL.

Request Parameters
template_version
integer
The version of the template to use for this task. Can only be changed if the task has status "ready".
parameters
object
The template parameters to use for this task. Can only be changed if the task has status "ready".
assigned_to
string
KSUID
The user to assign this task to.
priority
enum
Possible enum values
routine
time_sensitive
high_priority
urgent
description
string
A short description to help identify the task to users. Visible in the dashboard.
More Parameters
Expand all
external_url
string
URL
For renderless templates, the external where the task should be completed.
metadata
object
A key-value dictionary where API consumers can store metadata, such as their own reference IDs.
Returns

Returns a task object with HTTP status code 200 if successful or an error if one or more request parameters are invalid. 

Request
curl --request POST \
     --url https://api.osma.com/tasks/task_2BU1ecNdKXgRfRxPSjFDXfmv0tV \
     --header 'osma-api-key: sk_test_27NecW2jYLhV2gkB5lby1F22Fxv' \
     --data '{
        "priority": "high_priority"
      }'
Response
{
  "id": "task_2BU1ecNdKXgRfRxPSjFDXfmv0tV",
  "template": "update_blood_pressure",
  "status": "ready",
  "priority": "high_priority",
  "member": "mem_2C7PFuvIgJJyrEnf9SxOgndg3Fv",
  "description": "Update member's blood pressure",
  "parameters": {},
  "data": {},
  "external_url": null,
  "live_mode": false,
  "metadata": {}
  "created_at": "2022-07-04T14:45:45.338647+00:00",
  "updated_at": "2022-07-19T15:03:02.991466+00:00"
  "status_transitions": []
}

Delete a task

Soft deletes a task based on the id provided in the URL.

Returns

Returns a task object with HTTP status code 200 if successful. The status field will be changed to deleted and a new item will be added to status_transitions to reflect the change.

Request
curl --request DELETE \
     --url https://api.osma.com/tasks/task_2BU1ecNdKXgRfRxPSjFDXfmv0tV \
     --header 'osma-api-key: sk_test_27NecW2jYLhV2gkB5lby1F22Fxv'
Response
{
  "id": "task_2BU1ecNdKXgRfRxPSjFDXfmv0tV",
  "template": "update_blood_pressure",
  "status": "deleted",
  "priority": "routine",
  "member": "mem_2C7PFuvIgJJyrEnf9SxOgndg3Fv",
  "description": "Update member's blood pressure",
  "parameters": {},
  "data": {},
  "external_url": null,
  "live_mode": false,
  "metadata": {}
  "created_at": "2022-07-04T14:45:45.338647+00:00",
  "updated_at": "2022-07-19T15:03:02.991466+00:00",
  "status_transitions": [
    {
        "to": "in_progress",
        "from": "ready",
        "timestamp": "2022-07-04T14:45:45.486051+00:00"
    },
    {
        "to": "deleted",
        "from": "in_progress",
        "timestamp": "2022-07-19T14:55:41.103539+00:00"
    }
  ],
}

List all tasks

Retrieves a paginated list of task objects.

Parameters
limit
integer
Max
100
default
10
Optional
Maximum number of items to return.
starting_after
string
Optional
ID of the object to use as the pagination cursor.
ending_before
string
Optional
ID of the object to use as the pagination cursor.
Returns
has_next
boolean
Whether or not more resources exist when paginating with a cursor.
data
array
Array of task resources.
Request
curl --request GET \
     --url https://api.osma.com/tasks?limit=3 \
     --header 'osma-api-key: sk_test_27NecW2jYLhV2gkB5lby1F22Fxv'
Response
{
  "has_next": true
  "data": [
    {
      "id": "task_2BU1ecNdKXgRfRxPSjFDXfmv0tV",
      "template": "update_blood_pressure",
      "status": "ready",
      "priority": "routine",
      "member": "mem_2C7PFuvIgJJyrEnf9SxOgndg3Fv",
      "description": "Update member's blood pressure",
      "parameters": {},
      "data": {},
      "external_url": null,
      "live_mode": false,
      "metadata": {}
      "created_at": "2022-07-04T14:45:45.338647+00:00",
      "updated_at": "2022-07-04T14:45:45.338647+00:00",
      "status_transitions": []
    },
    {...},
    {...}
  ]
}

Members

This resource represents members that your organization serves. It lets you create tasks related to a member and keep track of workflows that relate to the same member.

Endpoints
post
/members
get
/members/:id
post
/members/:id
delete
/members/:id
get
/members

The member object

Attributes
name
string
The member's full name, including their last name, if applicable.
email
string
Email
The member's contact email. It must be unique.
status
enum
Current status of this member resource. Defaults to active.
Possible enum values
active
inactive
deleted
date_of_birth
string
ISO 8601 Date
The member's date of birth.
biological_sex
enum
The member's biological sex as defined by LOINC.
Possible enum values
male
female
other
Additional Attributes
Expand all
id
string
KSUID
Unique identifier for the member resource.
created_at
string
ISO 8601 Timestamp
Timestamp representing when the member resource was created.
updated_at
string
ISO 8601 Timestamp
Timestamp representing when the member resource was last updated.
status_transitions
array
An array of objects representing transitions from one status to another.
Child properties
timestamp
string
ISO 8601 Timestamp
Timestamp when the transition occured.
from
string
Status of the resource prior to the transition.
to
string
Status of the resource after the transition.
gender_identity
string
The member's personal gender identity, regardless of their biological sex.
live_mode
boolean
Whether the member resource exists in live mode. If false, the resource exists in test mode.
metadata
object
A key-value dictionary where API consumers can store metadata, such as their own reference IDs.

Member Object
{
  "id": "mem_28bnB4MCh2qygiyaHQ6jNGUbl10",
  "created_at": "2022-05-02T12:20:13.080819+00:00",
  "updated_at": "2022-05-02T12:20:13.080819+00:00",
  "name": "Daisy Demo",
  "email": "daisy@osma.com",
  "status": "active",
  "status_transitions": [],
  "date_of_birth": "1993-09-16",
  "biological_sex": "female",
  "gender_identity": null,
  "live_mode": false,
  "metadata": {}
}

Create a member

Request Parameters
name
string
Required
The member's full name, including their last name, if applicable.
email
string
Email
Required
The member's contact email. It must be unique.
date_of_birth
string
ISO 8601 Date
The member's date of birth.
biological_sex
enum
The member's biological sex as defined by LOINC.
Possible enum values
male
female
other
gender_identity
string
The member's personal gender identity, regardless of their biological sex.
metadata
object
A key-value dictionary where API consumers can store metadata, such as their own reference IDs.
Returns

Returns a member object with HTTP status code 201 if successful or an error if one or more request parameters are invalid.

Request
curl --request POST \
     --url https://api.osma.com/members \
     --header 'osma-api-key: sk_test_27NecW2jYLhV2gkB5lby1F22Fxv'
     --data '{
        "name": "Daisy Demo",
        "email: "daisy@osma.com",
        "date_of_birth": "1993-09-16",
        "biological_sex": "female"
      }'
Response
{
  "id": "mem_28bnB4MCh2qygiyaHQ6jNGUbl10",
  "created_at": "2022-05-02T12:20:13.080819+00:00",
  "updated_at": "2022-05-02T12:20:13.080819+00:00",
  "reference_id": null,
  "name": "Daisy Demo",
  "email": "daisy@osma.com",
  "active": true,
  "date_of_birth": "1993-09-16",
  "biological_sex": "female",
  "gender": null,
  "live_mode": false,
  "metadata": {}
}

Get one member

Retrieves a member resource based on the id provided in the URL. Returns a member object with HTTP status code 200 if a valid ID is provided or an error if no member is found in the same mode as the API key provided.

Request
curl --request GET \
     --url https://api.osma.com/members/mem_28bnB4MCh2qygiyaHQ6jNGUbl10 \
     --header 'osma-api-key: sk_test_27NecW2jYLhV2gkB5lby1F22Fxv'
Response
{
  "id": "mem_28bnB4MCh2qygiyaHQ6jNGUbl10",
  "created_at": "2022-05-02T12:20:13.080819+00:00",
  "updated_at": "2022-05-02T12:20:13.080819+00:00",
  "name": "Daisy Demo",
  "email": "daisy@osma.com",
  "status": "active",
  "status_transitions": [],
  "date_of_birth": "1993-09-16",
  "biological_sex": "female",
  "gender_identity": null,
  "live_mode": false,
  "metadata": {}
}

Update a member

Updates a member based on the id provided in the URL.

Request Parameters
name
string
The member's full name, including their last name, if applicable.
email
string
Email
The member's contact email. It must be unique.
date_of_birth
string
ISO 8601 Date
The member's date of birth.
biological_sex
enum
The member's biological sex as defined by LOINC.
Possible enum values
male
female
other
gender_identity
string
The member's personal gender identity, regardless of their biological sex.
metadata
object
A key-value dictionary where API consumers can store metadata, such as their own reference IDs.
Returns

Returns a member object with HTTP status code 200 if successful or an error if one or more request parameters are invalid. 

Request
curl --request POST \
     --url https://api.osma.com/members/mem_28bnB4MCh2qygiyaHQ6jNGUbl10 \
     --header 'osma-api-key: sk_test_27NecW2jYLhV2gkB5lby1F22Fxv' \
     --data '{
        "email": "daisy_new_email@osma.com"
      }'
Response
{
  "id": "mem_28bnB4MCh2qygiyaHQ6jNGUbl10",
  "created_at": "2022-05-02T12:20:13.080819+00:00",
  "updated_at": "2022-07-19T16:12:50.142969+00:00",
  "name": "Daisy Demo",
  "email": "daisy_new_email@osma.com",
  "status": "active",
  "status_transitions": [],
  "date_of_birth": "1993-09-16",
  "biological_sex": "female",
  "gender_identity": null,
  "live_mode": false,
  "metadata": {}
}

Delete a member

Soft deletes a member based on the id provided in the URL.

Returns

Returns a member object with HTTP status code 200 if successful or an error if one or more request parameters are invalid. The status field will be changed to deleted and a new item will be added to status_transitions to reflect the change.

Request
curl --request DELETE \
     --url https://api.osma.com/members/mem_28bnB4MCh2qygiyaHQ6jNGUbl10 \
     --header 'osma-api-key: sk_test_27NecW2jYLhV2gkB5lby1F22Fxv'
Response
{
  "id": "mem_28bnB4MCh2qygiyaHQ6jNGUbl10",
  "created_at": "2022-05-02T12:20:13.080819+00:00",
  "updated_at": "2022-05-02T12:20:13.080819+00:00",
  "name": "Daisy Demo",
  "email": "daisy@osma.com",
  "status": "deleted",
  "status_transitions": [
    {
      "to": "deleted",
      "from": "active",
      "timestamp": "2022-07-19T15:20:43.075563+00:00"
    }
  ],
  "date_of_birth": "1993-09-16",
  "biological_sex": "female",
  "gender_identity": null,
  "live_mode": false,
  "metadata": {}

}

List all members

Retrieves a paginated list of member objects.

Parameters
limit
integer
Max
100
default
10
Optional
Maximum number of items to return.
starting_after
string
Optional
ID of the object to use as the pagination cursor.
ending_before
string
Optional
ID of the object to use as the pagination cursor.
Returns
has_next
boolean
Whether or not more resources exist when paginating with a cursor.
data
array
Array of members resources.
Request
curl --request GET \
     --url https://api.osma.com/members?limit=3 \
     --header 'osma-api-key: sk_test_27NecW2jYLhV2gkB5lby1F22Fxv'
Response
{
  "has_next": true
  "data": [
    {
      "id": "mem_28bnB4MCh2qygiyaHQ6jNGUbl10",
      "created_at": "2022-05-02T12:20:13.080819+00:00",
      "updated_at": "2022-05-02T12:20:13.080819+00:00",
      "name": "Daisy Demo",
      "email": "daisy@osma.com",
      "status": "active",
      "status_transitions": [],
      "date_of_birth": "1993-09-16",
      "biological_sex": "female",
      "gender_identity": null,
      "live_mode": false,
      "metadata": {}
    },
    {...},
    {...}
  ]
}

Users

The user resource represents the users added to your organization through the Osma dashboard. Currently, users can only be managed through the Osma dashboard. We do provide GET endpoints so that you can retrieve users' ids and their roles so that you can programatically assign tasks.

One key difference to other resources is that the users resource is identical in live and test mode.

Endpoints
get
/users/:id
get
/users

The user object

Attributes
email
string
Email
Email address of the user.
full_name
string
Full name of the user, including last name if applicable.
roles
array
An array of roles assigned to this user in the Osma dashboard.
Child properties
title
string
Title that describes the role, e.g. Pharmacist.
status
enum
Current status of this user resource.
Possible enum values
active
inactive
invited
Additional Attributes
Expand all
id
string
KSUID
Unique identifier for the user resource.
created_at
string
ISO 8601 Timestamp
Timestamp representing when the user resource was created.
updated_at
string
ISO 8601 Timestamp
Timestamp representing when the user resource was last updated.
status_transitions
array
An array of objects representing transitions from one status to another.
Child properties
timestamp
string
ISO 8601 Timestamp
Timestamp when the transition occured.
from
string
Status of the resource prior to the transition.
to
string
Status of the resource after the transition.

User Object
{
    "id": "mem_28bnB4MCh2qygiyaHQ6jNGUbl10",
    "created_at": "2022-05-02T12:20:13.080819+00:00",
    "updated_at": "2022-05-02T12:20:13.080819+00:00",
    "reference_id": null,
    "name": "Daisy Demo",
    "email": "daisy@osma.com",
    "active": true,
    "date_of_birth": "1993-09-16",
    "biological_sex": "female",
    "gender": null,
    "live_mode": false,
    "metadata": {}
}

Get one user

Retrieves a user resource based on the id provided in the URL. Returns a user object with HTTP status code 200 if a valid ID is provided or an error if no member is found in the same mode as the API key provided.

Request
curl --request GET \
     --url https://api.osma.com/members/mem_28bnB4MCh2qygiyaHQ6jNGUbl10 \
     --header 'osma-api-key: sk_test_27NecW2jYLhV2gkB5lby1F22Fxv'
Response
{
  "id": "mem_28bnB4MCh2qygiyaHQ6jNGUbl10",
  "created_at": "2022-05-02T12:20:13.080819+00:00",
  "updated_at": "2022-05-02T12:20:13.080819+00:00",
  "reference_id": null,
  "name": "Daisy Demo",
  "email": "daisy@osma.com",
  "active": true,
  "date_of_birth": "1993-09-16",
  "biological_sex": "female",
  "gender": null,
  "live_mode": false,
  "metadata": {}
}

List all users

Retrieves a paginated list of user objects.

Parameters
limit
integer
Max
100
default
10
Optional
Maximum number of items to return.
starting_after
string
Optional
ID of the object to use as the pagination cursor.
ending_before
string
Optional
ID of the object to use as the pagination cursor.
Returns
has_next
boolean
Whether or not more resources exist when paginating with a cursor.
data
array
Array of user resources.
Request
curl --request GET \
     --url https://api.osma.com/members?limit=3 \
     --header 'osma-api-key: sk_test_27NecW2jYLhV2gkB5lby1F22Fxv'
Response
{
  "has_next": true
  "data": [
    {
      "id": "mem_28bnB4MCh2qygiyaHQ6jNGUbl10",
      "created_at": "2022-05-02T12:20:13.080819+00:00",
      "updated_at": "2022-05-02T12:20:13.080819+00:00",
      "reference_id": null,
      "name": "Daisy Demo",
      "email": "daisy@osma.com",
      "active": true,
      "date_of_birth": "1993-09-16",
      "biological_sex": "female",
      "gender": null,
      "live_mode": false,
      "metadata": {}
    },
    {...},
    {...}
  ]
}

Files

Some tasks may include file upload components enabling users to upload files as they complete tasks. To enable retrieving these files, tasks include fileIds in the data object. The GET files/:id endpoint enables these files to be retrieved, by returning an expiring pre-signed URLs from which the file data can be downloaded.

Endpoints
get
/files/:id

Get one file

Returns
id
string
UUID V4
The ID of the file.
url
string
URL
A presigned, expiring URL enabling you to download the file's contents.
expiration
number
Expiration time of the URL in seconds.
Request
curl --request GET \
     --url https://api.osma.com/members/mem_28bnB4MCh2qygiyaHQ6jNGUbl10 \
     --header 'osma-api-key: sk_test_27NecW2jYLhV2gkB5lby1F22Fxv'
Response
{
  "id": "mem_28bnB4MCh2qygiyaHQ6jNGUbl10",
  "created_at": "2022-05-02T12:20:13.080819+00:00",
  "updated_at": "2022-05-02T12:20:13.080819+00:00",
  "reference_id": null,
  "name": "Daisy Demo",
  "email": "daisy@osma.com",
  "active": true,
  "date_of_birth": "1993-09-16",
  "biological_sex": "female",
  "gender": null,
  "live_mode": false,
  "metadata": {}
}