Optify
API Documentation for Optify Public API
Models
APIKey
An API Key for interacting with this API
| Property | Description | Type | Required |
|---|---|---|---|
| key_prefix | string | false | |
| last_used_at | Most recent timestamp for when this key was used | string | false |
| name | Human readable label for this key | string | false |
| secret_key | string | false |
Engagement
| Property | Description | Type | Required |
|---|---|---|---|
| api_metadata | API Metadata | map | false |
| client_user_id | Client User ID | string | false |
| coach_options_user_ids | Coach Options User IDs | array(any) | false |
| coach_profile_id | Coach Profile ID | string | false |
| coach_selected_at | Coach Selected At Date | string | false |
| coach_selection_allowed_at | Coach Selection Allowed At Date | string | false |
| coach_user_id | Coach User ID | string | false |
| custom_fields | Custom Fields | map | false |
| end_reason | End Reason | string | false |
| ended_at | Date the engagement ends. Set from the program's end date when the engagement is created; once the engagement is closed, the date it ended. May be null. | string | false |
| event_ids | Event IDs | array(any) | false |
| id | Engagement ID | string | false |
| inserted_at | Creation timestamp | string | false |
| is_closed | Is Closed? | boolean | false |
| is_coach_assigned | Is Coach Assigned? | boolean | false |
| is_coach_selection_allowed | Is Coach Selection Allowed? | boolean | false |
| program_id | Program ID | string | false |
| updated_at | Update timestamp | string | false |
| welcomed_at | Welcomed At Date | string | false |
EngagementCreateRequest
Body for POST /_api/engagements/
| Property | Description | Type | Required |
|---|---|---|---|
| api_metadata | Opaque API metadata object; defaults to {} | map | false |
| client_user_id | Client User ID (must have the client role) | string | true |
| ended_at | Date the engagement ends. Defaults to the program's end date when omitted; send null to create the engagement with no end date. | string | false |
| program_id | Program ID | string | true |
EngagementIndexResponse
| Property | Description | Type | Required |
|---|---|---|---|
| engagements | List of Engagements | array(Engagement) | false |
| message | Status Message | string | false |
| page_number | Current page number | integer | false |
| results_per_page | Number of results per page | integer | false |
| status | HTTP status code | integer | false |
| total_pages | Total number of pages | integer | false |
| total_results | Total number of results | integer | false |
EngagementUpdateRequest
Body for PATCH /_api/engagements/:id. Every field is optional and only provided fields are changed. Any other field returns a 400. The program and the client cannot be changed - that is a different engagement. Neither can the coach, the coach selection, the welcome, or the closing of an engagement: each of those has side effects of its own.
| Property | Description | Type | Required |
|---|---|---|---|
| api_metadata | Opaque API metadata object | map | false |
| ended_at | Date the engagement ends. Send null to clear it. A closed engagement keeps the date it ended: the date cannot be changed once it is set, though it can still be set on an engagement closed without one. Changing it does not close the engagement - it stays open, the coach keeps access, and it is still counted as active. | string | false |
EngagementWelcomeRequest
Body for POST /_api/engagements/:id/welcome
| Property | Description | Type | Required |
|---|---|---|---|
| suppress_notification | When false (the default) the client is emailed a program invitation and the engagement waits for them to register. When true no invitation is sent and the client is moved past the registration step so the engagement can start right away; they can still set a password through a password reset. The coach is notified either way. | boolean | false |
Event
| Property | Description | Type | Required |
|---|---|---|---|
| api_metadata | API Metadata | map | false |
| assessment_title | Assessment Title | string | false |
| client_user_id | Client User ID | string | false |
| coach_agreed | Coach Agreed? | boolean | false |
| coach_user_id | Coach User ID | string | false |
| coaching_topic_ids | Coaching Topic IDs | array(any) | false |
| completed_at | Completed At Date | string | false |
| duration_minutes | Meeting Duration | integer | false |
| ends_at | Ends At Date | string | false |
| engagement_id | Engagement ID | string | false |
| engagement_sort_order | Engagement Sort Order | integer | false |
| event_type | Event Type | string | false |
| id | Event ID | string | false |
| inserted_at | Creation timestamp | string | false |
| is_completed | Is Event Completed? | boolean | false |
| is_meeting_visible_to_client | Is Meeting Visible To Client? | boolean | false |
| meeting_type | Meeting Type | string | false |
| missed_meeting | Missed Meeting? | boolean | false |
| program_id | Program ID | string | false |
| responded_at | Survey Responded At Date | string | false |
| response | Survey Response | string | false |
| starts_at | Starts At Date | string | false |
| title | Meeting Title | string | false |
| updated_at | Update timestamp | string | false |
EventIndexResponse
| Property | Description | Type | Required |
|---|---|---|---|
| events | List of Events | array(Event) | false |
| message | Status Message | string | false |
| page_number | Current page number | integer | false |
| results_per_page | Number of results per page | integer | false |
| status | HTTP status code | integer | false |
| total_pages | Total number of pages | integer | false |
| total_results | Total number of results | integer | false |
EventUpdateRequest
Body for PATCH /_api/events/:id. Only api_metadata can be updated. Omit api_metadata to leave the stored value unchanged. A null value stores {}. Any other field is rejected with a 400. The event status does not change.
| Property | Description | Type | Required |
|---|---|---|---|
| api_metadata | API Metadata. Must be an object; null is stored as {}. | map | false |
Program
| Property | Description | Type | Required |
|---|---|---|---|
| api_metadata | API Metadata | map | false |
| coach_user_ids | Coach User IDs | array(any) | false |
| coaching_topic_ids | Program Coaching Topic IDs | array(any) | false |
| custom_fields | Custom Fields | map | false |
| description | Program Description | string | false |
| details | Program Details | string | false |
| end_at | End Date | string | false |
| engagement_ids | Engagement IDs | array(any) | false |
| id | Program ID | string | false |
| inserted_at | Creation timestamp | string | false |
| is_closed | Is Closed? | boolean | false |
| manager_user_ids | Manager User IDs | array(any) | false |
| name | Program Name | string | false |
| point_of_contact_user_id | Point of Contact User ID | string | false |
| sponsor_company | Sponsor Company | string | false |
| sponsor_manager | Sponsor Manager | string | false |
| sponsor_user_ids | Sponsor User IDs | array(any) | false |
| start_at | Start Date | string | false |
| updated_at | Update timestamp | string | false |
ProgramIndexResponse
| Property | Description | Type | Required |
|---|---|---|---|
| message | Status Message | string | false |
| page_number | Current page number | integer | false |
| programs | List of Programs | array(Program) | false |
| results_per_page | Number of results per page | integer | false |
| status | HTTP status code | integer | false |
| total_pages | Total number of pages | integer | false |
| total_results | Total number of results | integer | false |
ProgramUpdateRequest
Body for PATCH /_api/programs/:id. Only api_metadata can be updated. Omit api_metadata to leave the stored value unchanged. A null value stores {}. Any other field is rejected with a 400.
| Property | Description | Type | Required |
|---|---|---|---|
| api_metadata | API Metadata. Must be an object; null is stored as {}. | map | false |
Questionnaire
| Property | Description | Type | Required |
|---|---|---|---|
| api_metadata | API Metadata | map | false |
| completed_at | Completed At | string | false |
| engagement_id | Engagement ID | string | false |
| id | Questionnaire ID | string | false |
| inserted_at | Creation timestamp | string | false |
| is_completed | Is Completed? | boolean | false |
| question_answer_pairs | Question Answer Pairs | array(any) | false |
| updated_at | Update timestamp | string | false |
QuestionnaireIndexResponse
| Property | Description | Type | Required |
|---|---|---|---|
| message | Status Message | string | false |
| page_number | Current page number | integer | false |
| questionnaires | List of Questionnaires | array(Questionnaire) | false |
| results_per_page | Number of results per page | integer | false |
| status | HTTP status code | integer | false |
| total_pages | Total number of pages | integer | false |
| total_results | Total number of results | integer | false |
QuestionnaireUpdateRequest
Body for PATCH /_api/questionnaires/:id. Only api_metadata can be updated. Omit api_metadata to leave the stored value unchanged. A null value stores {}. Any other field is rejected with a 400.
| Property | Description | Type | Required |
|---|---|---|---|
| api_metadata | API Metadata. Must be an object; null is stored as {}. | map | false |
User
| Property | Description | Type | Required |
|---|---|---|---|
| api_metadata | API Metadata | map | false |
| client_engagement_ids | Engagement IDs as a client | array(any) | false |
| coach_engagement_ids | Engagement IDs as a coach | array(any) | false |
| coach_option_engagement_ids | Engagement IDs as a coach option | array(any) | false |
| coach_profile_id | Coach profile ID | string | false |
| coach_program_ids | Program IDs as a coach | array(any) | false |
| Email address | string | false | |
| first_name | First name | string | false |
| id | User ID | string | false |
| inserted_at | Creation timestamp | string | false |
| is_active | Has one or more active roles | boolean | false |
| is_admin | User is a program manager | boolean | false |
| is_client | User is a client | boolean | false |
| is_coach | User is a coach | boolean | false |
| is_sponsor | User is a sponsor | boolean | false |
| last_name | Last name | string | false |
| logged_in_at | Last logged in timestamp | string | false |
| manager_program_ids | Program Ids as a program manager | array(any) | false |
| registered_at | Registration timestamp | string | false |
| updated_at | Update timestamp | string | false |
UserCreateRequest
Body for POST /_api/users. Roles are set via is_coach/is_client/is_sponsor - at least one must be true. The admin role cannot be assigned through this endpoint: is_admin: true is rejected with a 400.
| Property | Description | Type | Required |
|---|---|---|---|
| api_metadata | API Metadata | map | false |
| Email address | string | true | |
| first_name | First name | string | true |
| is_admin | Read-only. The admin role is never granted through the public API: true is rejected with a 400, false asks for nothing and is allowed. | boolean | false |
| is_client | Grant the client role | boolean | false |
| is_coach | Grant the coach role | boolean | false |
| is_sponsor | Grant the sponsor role | boolean | false |
| last_name | Last name | string | true |
UserDeactivateRequest
Body for POST /_api/users/:id/deactivate. Removes every role from the user, which leaves them with no access and reported as is_active: false.
| Property | Description | Type | Required |
|---|---|---|---|
| reason | Why the user is being deactivated. Recorded on the audit log. Defaults to "deactivated by API" when omitted. Limited to 255 characters. | string | false |
UserIndexResponse
| Property | Description | Type | Required |
|---|---|---|---|
| message | Status Message | string | false |
| page_number | Current page number | integer | false |
| results_per_page | Number of results per page | integer | false |
| status | HTTP status code | integer | false |
| total_pages | Total number of pages | integer | false |
| total_results | Total number of results | integer | false |
| users | List of Users | array(User) | false |
UserUpdateRequest
Body for PATCH /_api/users/:id. Every field is optional and only provided fields are changed; unknown fields are ignored. Roles cannot be changed through this endpoint - is_coach/is_client/is_sponsor are granted once at creation and is_admin never is. is_active cannot be set here either - POST /_api/users/:id/deactivate takes a user's roles away. Sending one of these that matches what the user already is is allowed and does nothing, so a caller may write back the whole user object; sending one that asks for a change is rejected with a 400.
| Property | Description | Type | Required |
|---|---|---|---|
| api_metadata | API Metadata | map | false |
| Email address. Also updates the shared identity. Rejected when the user belongs to more than one provider. | string | false | |
| first_name | First name | string | false |
| is_active | Read-only, derived from whether the user holds any role. May be sent back unchanged; any other value is rejected with a 400. Use POST /_api/users/{id}/deactivate to take a user's roles away. | boolean | false |
| is_admin | Read-only. The admin role is never set through the public API. May be sent back unchanged; any other value is rejected with a 400. | boolean | false |
| is_client | Read-only. May be sent back unchanged; a value that does not match the roles the user already holds is rejected with a 400. | boolean | false |
| is_coach | Read-only. May be sent back unchanged; a value that does not match the roles the user already holds is rejected with a 400. | boolean | false |
| is_sponsor | Read-only. May be sent back unchanged; a value that does not match the roles the user already holds is rejected with a 400. | boolean | false |
| last_name | Last name | string | false |
Auth
Show Me
/me with a valid token, returns the current user's information
GET /me
content-type: application/vnd.optify.APIKey+json;v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"updated_at": "2020-01-01T00:00:00Z",
"status": 200,
"secret_key": null,
"name": "Top Secret Key",
"message": "OK",
"last_used_at": null,
"key_preview": "none",
"key_prefix": "opt_",
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000"
}
/me with an invalid request format, returns a helpful error
GET /me
content-type: application/vnd.optify.APIKey+json;v=1
Response
401
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 401,
"message": "Missing API Key"
}
/me with an invalid token, returns an error
GET /me
content-type: application/vnd.optify.APIKey+json;v=1
authorization: api-key NONSENSE
Response
403
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 403,
"message": "Invalid API Key"
}
Return info about current API key.
Request
GET /_api/me
Responses
| Status | Description | Schema |
|---|
Engagement
Create an Engagement
create/2 creates an engagement with defaults
POST /engagements
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"program_id": "00000000-0000-0000-0000-000000000000",
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {
"dsi_participant_id": "dsi-123"
}
}
Response
201
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"status": 201,
"program_id": "00000000-0000-0000-0000-000000000000",
"message": "Created",
"is_coach_selection_allowed": false,
"is_coach_assigned": false,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": "2030-01-01T00:00:00Z",
"end_reason": null,
"custom_fields": {},
"coach_user_id": null,
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {
"dsi_participant_id": "dsi-123"
}
}
create/2 creates an engagement with an explicit end date
POST /engagements
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"program_id": "00000000-0000-0000-0000-000000000000",
"ended_at": "2031-01-01T00:00:00Z",
"client_user_id": "00000000-0000-0000-0000-000000000000"
}
Response
201
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"status": 201,
"program_id": "00000000-0000-0000-0000-000000000000",
"message": "Created",
"is_coach_selection_allowed": false,
"is_coach_assigned": false,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": "2031-01-01T00:00:00Z",
"end_reason": null,
"custom_fields": {},
"coach_user_id": null,
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
}
Create an Engagement. ended_at defaults to the program's end date if omitted.
Request
POST /_api/engagements/
Parameters
| Parameter | Description | In | Type | Required | Default | Example |
|---|---|---|---|---|---|---|
| body | Engagement create attributes | body | EngagementCreateRequest | true |
Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Created | Engagement |
| 400 | Bad Request | |
| 404 | Not Found | |
| 409 | Conflict |
A paginated list of Engagements
allows PUT requests to support more parameters
PUT /engagements
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"sort": "asc:inserted_at",
"results_per_page": 3,
"closed": "false"
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 5,
"total_pages": 2,
"status": 200,
"results_per_page": 3,
"page_number": 1,
"message": "OK",
"engagements": [
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": null,
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
},
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": null,
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
},
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": null,
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
}
]
}
by default, returns up to 50 engagements per page in the provider
GET /engagements
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 5,
"total_pages": 1,
"status": 200,
"results_per_page": 50,
"page_number": 1,
"message": "OK",
"engagements": [
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": null,
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
},
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": null,
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
},
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": null,
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
},
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": null,
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
},
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": null,
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
}
]
}
accepts results_per_page parameter
GET /engagements?results_per_page=5
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 6,
"total_pages": 2,
"status": 200,
"results_per_page": 5,
"page_number": 1,
"message": "OK",
"engagements": [
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": null,
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
},
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": null,
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
},
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": null,
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
},
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": null,
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
},
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": null,
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
}
]
}
accepts page_number parameter
GET /engagements?results_per_page=1&page_number=2
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 2,
"total_pages": 2,
"status": 200,
"results_per_page": 1,
"page_number": 2,
"message": "OK",
"engagements": [
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2018-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": "Just didn't work out",
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
}
]
}
limits results_per_page to 100
GET /engagements?results_per_page=101
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
400
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 400,
"message": "Bad Request",
"errors": {
"request": [
"Page size of 101 above limit of 100"
]
}
}
accepts sorting parameters
GET /engagements?sort=asc_nulls_first:end_reason
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 4,
"total_pages": 1,
"status": 200,
"results_per_page": 50,
"page_number": 1,
"message": "OK",
"engagements": [
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": null,
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
},
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": null,
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
},
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": "A reason",
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
},
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"program_id": "00000000-0000-0000-0000-000000000000",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": "Just wasn't working out",
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
}
]
}
rejects invalid sorting parameters
GET /engagements?sort=asc(fake_column)
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
400
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 400,
"message": "Bad Request",
"errors": {
"request": [
"Invalid sort field format `asc(fake_column)`. Expected `direction:field`"
]
}
}
List of Engagements
Request
GET /_api/engagements/
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | EngagementIndexResponse |
A single Engagement
with a valid id, returns that engagement
GET /engagements/00000000-0000-0000-0000-000000000000
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"status": 200,
"program_id": "00000000-0000-0000-0000-000000000000",
"message": "OK",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": true,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": null,
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {
"dsi_participant_id": "dsi-123"
}
}
with an invalid id, returns a 404
GET /engagements/00000000-0000-0000-0000-000000000000
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
404
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 404,
"message": "Not Found"
}
with an invalid id type, returns a 400
GET /engagements/non-uuid-garbage
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
400
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 400,
"message": "Bad Request",
"errors": {
"request": [
"id is invalid"
]
}
}
Request
GET /_api/engagements/{id}
Parameters
| Parameter | Description | In | Type | Required | Default | Example |
|---|---|---|---|---|---|---|
| id | Engagement ID | path | string | true |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | Engagement |
| 400 | Bad Request | |
| 404 | Not Found |
Update an Engagement
update/2 updates the end date and the api metadata
PATCH /engagements/00000000-0000-0000-0000-000000000000
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"ended_at": "2031-06-01T00:00:00Z",
"api_metadata": {
"dsi_participant_id": "dsi-456"
}
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"welcomed_at": null,
"updated_at": "2020-01-01T00:00:00.000000",
"status": 200,
"program_id": "00000000-0000-0000-0000-000000000000",
"message": "OK",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": "2031-06-01T00:00:00Z",
"end_reason": null,
"custom_fields": {},
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {
"dsi_participant_id": "dsi-456"
}
}
Update an Engagement. Only ended_at and api_metadata can be updated. Both are optional; an omitted field keeps its stored value. Any other field in the body returns a 400. Changing the end date of a closed engagement returns a 409. Setting ended_at does not close the engagement.
Request
PATCH /_api/engagements/{id}
Parameters
| Parameter | Description | In | Type | Required | Default | Example |
|---|---|---|---|---|---|---|
| id | Engagement ID | path | string | true | ||
| body | Engagement update attributes | body | EngagementUpdateRequest | true |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | Engagement |
| 400 | Bad Request | |
| 404 | Not Found | |
| 409 | Conflict | |
| 500 | Internal Server Error |
Welcome a client into their program
welcome/2 welcomes the client and returns the engagement
POST /engagements/00000000-0000-0000-0000-000000000000/welcome
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"welcomed_at": "2020-01-01T00:00:00Z",
"updated_at": "2020-01-01T00:00:00.000000",
"status": 200,
"program_id": "00000000-0000-0000-0000-000000000000",
"message": "OK",
"is_coach_selection_allowed": false,
"is_coach_assigned": null,
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_ids": [],
"ended_at": null,
"end_reason": null,
"custom_fields": {},
"coach_user_id": null,
"coach_selection_allowed_at": null,
"coach_selected_at": null,
"coach_profile_id": null,
"coach_options_user_ids": [],
"client_user_id": "00000000-0000-0000-0000-000000000000",
"api_metadata": {}
}
Welcome the client into their program. The engagement is marked as welcomed, the coach waiting to be assigned to it is assigned, the program's initial resources are given to the client, and the client and the coach are notified. Send suppress_notification: true to start the engagement without emailing the client an invitation. An engagement that is already welcomed is left alone and answered with 200, so retrying a request that already went through does not send a second invitation. Do not send two welcome requests for the same engagement at the same time: the check runs before the welcome, so both can pass it.
Request
POST /_api/engagements/{id}/welcome
Parameters
| Parameter | Description | In | Type | Required | Default | Example |
|---|---|---|---|---|---|---|
| id | Engagement ID | path | string | true | ||
| body | Welcome options | body | EngagementWelcomeRequest | false |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | Engagement |
| 400 | Bad Request | |
| 404 | Not Found | |
| 409 | Conflict |
Event
A paginated list of Events
allows PUT requests to support more parameters
PUT /events
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"sort": "asc:inserted_at",
"results_per_page": 3
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 5,
"total_pages": 2,
"status": 200,
"results_per_page": 3,
"page_number": 1,
"message": "OK",
"events": [
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": "Meeting #0",
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": false,
"meeting_type": "one-on-one",
"is_meeting_visible_to_client": true,
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "meeting",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": 30,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_agreed": null,
"client_user_id": "00000000-0000-0000-0000-000000000000",
"assessment_title": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": "Meeting #0",
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": false,
"meeting_type": "one-on-one",
"is_meeting_visible_to_client": true,
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "meeting",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": 30,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_agreed": null,
"client_user_id": "00000000-0000-0000-0000-000000000000",
"assessment_title": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": "Meeting #0",
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": false,
"meeting_type": "one-on-one",
"is_meeting_visible_to_client": true,
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "meeting",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": 30,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_agreed": null,
"client_user_id": "00000000-0000-0000-0000-000000000000",
"assessment_title": null,
"api_metadata": {}
}
]
}
test is_completed flag on events
PUT /events
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"sort": "asc:inserted_at"
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 4,
"total_pages": 1,
"status": 200,
"results_per_page": 50,
"page_number": 1,
"message": "OK",
"events": [
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": "Meeting #0",
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": false,
"meeting_type": "one-on-one",
"is_meeting_visible_to_client": true,
"is_completed": true,
"inserted_at": "2024-01-01T12:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "meeting",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": 60,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_agreed": null,
"client_user_id": "00000000-0000-0000-0000-000000000000",
"assessment_title": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": "Meeting #0",
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": false,
"meeting_type": "one-on-one",
"is_meeting_visible_to_client": true,
"is_completed": false,
"inserted_at": "2024-01-02T12:00:01Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "meeting",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": 60,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_agreed": null,
"client_user_id": "00000000-0000-0000-0000-000000000000",
"assessment_title": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": null,
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": null,
"meeting_type": null,
"is_meeting_visible_to_client": null,
"is_completed": false,
"inserted_at": "2024-01-03T12:00:02Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "survey",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": null,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": null,
"coach_agreed": null,
"client_user_id": null,
"assessment_title": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": null,
"starts_at": null,
"response": "some response",
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": null,
"meeting_type": null,
"is_meeting_visible_to_client": null,
"is_completed": true,
"inserted_at": "2024-01-04T12:00:03Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "survey",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": null,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": null,
"coach_agreed": null,
"client_user_id": null,
"assessment_title": null,
"api_metadata": {}
}
]
}
test is_completed filter on events
PUT /events
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"sort": "asc:inserted_at",
"is_completed": "true"
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 2,
"total_pages": 1,
"status": 200,
"results_per_page": 50,
"page_number": 1,
"message": "OK",
"events": [
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": "Meeting #0",
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": false,
"meeting_type": "one-on-one",
"is_meeting_visible_to_client": true,
"is_completed": true,
"inserted_at": "2024-01-01T12:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "meeting",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": 60,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_agreed": null,
"client_user_id": "00000000-0000-0000-0000-000000000000",
"assessment_title": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": null,
"starts_at": null,
"response": "some response",
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": null,
"meeting_type": null,
"is_meeting_visible_to_client": null,
"is_completed": true,
"inserted_at": "2024-01-04T12:00:03Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "survey",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": null,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": null,
"coach_agreed": null,
"client_user_id": null,
"assessment_title": null,
"api_metadata": {}
}
]
}
test is_completed filter on events
PUT /events
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"sort": "asc:inserted_at",
"is_completed": "false"
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 2,
"total_pages": 1,
"status": 200,
"results_per_page": 50,
"page_number": 1,
"message": "OK",
"events": [
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": "Meeting #0",
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": false,
"meeting_type": "one-on-one",
"is_meeting_visible_to_client": true,
"is_completed": false,
"inserted_at": "2024-01-02T12:00:01Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "meeting",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": 60,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_agreed": null,
"client_user_id": "00000000-0000-0000-0000-000000000000",
"assessment_title": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": null,
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": null,
"meeting_type": null,
"is_meeting_visible_to_client": null,
"is_completed": false,
"inserted_at": "2024-01-03T12:00:02Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "survey",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": null,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": null,
"coach_agreed": null,
"client_user_id": null,
"assessment_title": null,
"api_metadata": {}
}
]
}
test is_meeting_visible_to_client filter on events for true
PUT /events
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"sort": "asc:inserted_at",
"is_meeting_visible_to_client": "true"
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 1,
"total_pages": 1,
"status": 200,
"results_per_page": 50,
"page_number": 1,
"message": "OK",
"events": [
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": "Meeting #0",
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": false,
"meeting_type": "one-on-one",
"is_meeting_visible_to_client": true,
"is_completed": false,
"inserted_at": "2024-01-01T12:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "meeting",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": 60,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_agreed": null,
"client_user_id": "00000000-0000-0000-0000-000000000000",
"assessment_title": null,
"api_metadata": {}
}
]
}
test is_meeting_visible_to_client filter on events for false
PUT /events
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"sort": "asc:inserted_at",
"is_meeting_visible_to_client": "false"
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 1,
"total_pages": 1,
"status": 200,
"results_per_page": 50,
"page_number": 1,
"message": "OK",
"events": [
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": "Meeting #0",
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": false,
"meeting_type": "one-on-one",
"is_meeting_visible_to_client": false,
"is_completed": false,
"inserted_at": "2024-01-02T12:00:01Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "meeting",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": 60,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_agreed": null,
"client_user_id": "00000000-0000-0000-0000-000000000000",
"assessment_title": null,
"api_metadata": {}
}
]
}
test is_completed sorting on events
PUT /events
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"sort": "asc:is_completed,asc:inserted_at"
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 4,
"total_pages": 1,
"status": 200,
"results_per_page": 50,
"page_number": 1,
"message": "OK",
"events": [
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": "Meeting #0",
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": false,
"meeting_type": "one-on-one",
"is_meeting_visible_to_client": true,
"is_completed": false,
"inserted_at": "2024-01-02T12:00:01Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "meeting",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": 60,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_agreed": null,
"client_user_id": "00000000-0000-0000-0000-000000000000",
"assessment_title": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": null,
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": null,
"meeting_type": null,
"is_meeting_visible_to_client": null,
"is_completed": false,
"inserted_at": "2024-01-03T12:00:02Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "survey",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": null,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": null,
"coach_agreed": null,
"client_user_id": null,
"assessment_title": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": "Meeting #0",
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": false,
"meeting_type": "one-on-one",
"is_meeting_visible_to_client": true,
"is_completed": true,
"inserted_at": "2024-01-01T12:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "meeting",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": 60,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_agreed": null,
"client_user_id": "00000000-0000-0000-0000-000000000000",
"assessment_title": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": null,
"starts_at": null,
"response": "some response",
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": null,
"meeting_type": null,
"is_meeting_visible_to_client": null,
"is_completed": true,
"inserted_at": "2024-01-04T12:00:03Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "survey",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": null,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": null,
"coach_agreed": null,
"client_user_id": null,
"assessment_title": null,
"api_metadata": {}
}
]
}
test is_completed sorting on events
PUT /events
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"sort": "desc:is_completed,asc:inserted_at"
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 4,
"total_pages": 1,
"status": 200,
"results_per_page": 50,
"page_number": 1,
"message": "OK",
"events": [
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": "Meeting #0",
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": false,
"meeting_type": "one-on-one",
"is_meeting_visible_to_client": true,
"is_completed": true,
"inserted_at": "2024-01-01T12:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "meeting",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": 60,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_agreed": null,
"client_user_id": "00000000-0000-0000-0000-000000000000",
"assessment_title": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": null,
"starts_at": null,
"response": "some response",
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": null,
"meeting_type": null,
"is_meeting_visible_to_client": null,
"is_completed": true,
"inserted_at": "2024-01-04T12:00:03Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "survey",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": null,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": null,
"coach_agreed": null,
"client_user_id": null,
"assessment_title": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": "Meeting #0",
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": false,
"meeting_type": "one-on-one",
"is_meeting_visible_to_client": true,
"is_completed": false,
"inserted_at": "2024-01-02T12:00:01Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "meeting",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": 60,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_agreed": null,
"client_user_id": "00000000-0000-0000-0000-000000000000",
"assessment_title": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": null,
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": null,
"meeting_type": null,
"is_meeting_visible_to_client": null,
"is_completed": false,
"inserted_at": "2024-01-03T12:00:02Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "survey",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": null,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": null,
"coach_agreed": null,
"client_user_id": null,
"assessment_title": null,
"api_metadata": {}
}
]
}
List of Events
Request
GET /_api/events/
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | EventIndexResponse |
A single Event
with a valid id, returns that event
GET /events/00000000-0000-0000-0000-000000000000
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": "Meeting #0",
"status": 200,
"starts_at": "2020-01-01T00:00:00Z",
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": false,
"message": "OK",
"meeting_type": "one-on-one",
"is_meeting_visible_to_client": true,
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "meeting",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": "2020-01-01T00:00:00Z",
"duration_minutes": 60,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_agreed": null,
"client_user_id": "00000000-0000-0000-0000-000000000000",
"assessment_title": null,
"api_metadata": {}
}
with an invalid id, returns a 404
GET /events/00000000-0000-0000-0000-000000000000
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
404
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 404,
"message": "Not Found"
}
with an invalid id type, returns a 400
GET /events/non-uuid-garbage
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
400
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 400,
"message": "Bad Request",
"errors": {
"request": [
"id is invalid"
]
}
}
Request
GET /_api/events/{id}
Parameters
| Parameter | Description | In | Type | Required | Default | Example |
|---|---|---|---|---|---|---|
| id | Event ID | path | string | true |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | Event |
Update an Event within the provider
update/2 updates an event's api_metadata
PATCH /events/00000000-0000-0000-0000-000000000000
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"api_metadata": {
"external_id": "EXT-2"
}
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"updated_at": "2020-01-01T00:00:00.000000",
"title": "Meeting #0",
"status": 200,
"starts_at": null,
"response": null,
"responded_at": null,
"program_id": "00000000-0000-0000-0000-000000000000",
"missed_meeting": false,
"message": "OK",
"meeting_type": "one-on-one",
"is_meeting_visible_to_client": true,
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"event_type": "meeting",
"engagement_sort_order": 0,
"engagement_id": "00000000-0000-0000-0000-000000000000",
"ends_at": null,
"duration_minutes": 30,
"completed_at": null,
"coaching_topic_ids": [],
"coach_user_id": "00000000-0000-0000-0000-000000000000",
"coach_agreed": null,
"client_user_id": "00000000-0000-0000-0000-000000000000",
"assessment_title": null,
"api_metadata": {
"external_id": "EXT-2"
}
}
Updates the api_metadata of an Event. Only api_metadata can be updated. Omit it to leave the stored value unchanged. Any other field in the body returns a 400. The event status does not change.
Request
PATCH /_api/events/{id}
Parameters
| Parameter | Description | In | Type | Required | Default | Example |
|---|---|---|---|---|---|---|
| id | Event ID | path | string | true | ||
| body | Event update attributes | body | EventUpdateRequest | true |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | Event |
| 400 | Bad Request | |
| 404 | Not Found | |
| 409 | Conflict |
Program
A paginated list of Programs
allows PUT requests to support more parameters
PUT /programs
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"sort": "asc:inserted_at",
"results_per_page": 3,
"closed": "false"
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 5,
"total_pages": 2,
"status": 200,
"results_per_page": 3,
"programs": [
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "Program Name 0",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "Program Name 0",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "Program Name 0",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
}
],
"page_number": 1,
"message": "OK"
}
by default, returns up to 50 programs per page in the provider
GET /programs
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 5,
"total_pages": 1,
"status": 200,
"results_per_page": 50,
"programs": [
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "Program Name 0",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "Program Name 0",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "Program Name 0",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "Program Name 0",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "Program Name 0",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
}
],
"page_number": 1,
"message": "OK"
}
accepts results_per_page parameter
GET /programs?results_per_page=5
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 6,
"total_pages": 2,
"status": 200,
"results_per_page": 5,
"programs": [
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "Program Name 0",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "Program Name 0",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "Program Name 0",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "Program Name 0",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "Program Name 0",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
}
],
"page_number": 1,
"message": "OK"
}
accepts page_number parameter
GET /programs?results_per_page=1&page_number=2
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 2,
"total_pages": 2,
"status": 200,
"results_per_page": 1,
"programs": [
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "First Program",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2018-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
}
],
"page_number": 2,
"message": "OK"
}
limits results_per_page to 100
GET /programs?results_per_page=101
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
400
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 400,
"message": "Bad Request",
"errors": {
"request": [
"Page size of 101 above limit of 100"
]
}
}
accepts sorting parameters
GET /programs?sort=asc_nulls_first:name
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 4,
"total_pages": 1,
"status": 200,
"results_per_page": 50,
"programs": [
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "A Program",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "B Program",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "C Program",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00.000000",
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "D Program",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {}
}
],
"page_number": 1,
"message": "OK"
}
rejects invalid sorting parameters
GET /programs?sort=asc(fake_column)
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
400
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 400,
"message": "Bad Request",
"errors": {
"request": [
"Invalid sort field format `asc(fake_column)`. Expected `direction:field`"
]
}
}
List of Programs
Request
GET /_api/programs/
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | ProgramIndexResponse |
A single Program
with a valid id, returns that program
GET /programs/00000000-0000-0000-0000-000000000000
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"updated_at": "2020-01-01T00:00:00.000000",
"status": 200,
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "Program Name 0",
"message": "OK",
"manager_user_ids": [],
"is_closed": true,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {
"netsuite_id": "NS-1001"
}
}
with an invalid id, returns a 404
GET /programs/00000000-0000-0000-0000-000000000000
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
404
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 404,
"message": "Not Found"
}
with an invalid id type, returns a 400
GET /programs/non-uuid-garbage
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
400
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 400,
"message": "Bad Request",
"errors": {
"request": [
"id is invalid"
]
}
}
Request
GET /_api/programs/{id}
Parameters
| Parameter | Description | In | Type | Required | Default | Example |
|---|---|---|---|---|---|---|
| id | Program ID | path | string | true |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | Program |
Update a Program within the provider
update/2 updates a program's api_metadata
PATCH /programs/00000000-0000-0000-0000-000000000000
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"api_metadata": {
"external_id": "EXT-2"
}
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"updated_at": "2020-01-01T00:00:00.000000",
"status": 200,
"start_at": null,
"sponsor_user_ids": [],
"sponsor_manager": null,
"sponsor_company": "Company 0",
"point_of_contact_user_id": null,
"name": "Program Name 0",
"message": "OK",
"manager_user_ids": [],
"is_closed": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_ids": [],
"end_at": null,
"details": null,
"description": null,
"custom_fields": {},
"coaching_topic_ids": [],
"coach_user_ids": [],
"api_metadata": {
"external_id": "EXT-2"
}
}
Updates the api_metadata of a Program. Only api_metadata can be updated. Omit it to leave the stored value unchanged. Any other field in the body returns a 400.
Request
PATCH /_api/programs/{id}
Parameters
| Parameter | Description | In | Type | Required | Default | Example |
|---|---|---|---|---|---|---|
| id | Program ID | path | string | true | ||
| body | Program update attributes | body | ProgramUpdateRequest | true |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | Program |
| 400 | Bad Request | |
| 404 | Not Found | |
| 409 | Conflict | |
| 500 | Internal Server Error |
Questionnaire
A paginated list of Questionnaires
allows PUT requests to support more parameters
PUT /questionnaires
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"sort": "asc:inserted_at",
"results_per_page": 3,
"is_completed": "false"
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 5,
"total_pages": 2,
"status": 200,
"results_per_page": 3,
"questionnaires": [
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
}
],
"page_number": 1,
"message": "OK"
}
by default, returns up to 50 questionnaires per page in the provider
GET /questionnaires
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 100,
"total_pages": 2,
"status": 200,
"results_per_page": 50,
"questionnaires": [
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
}
],
"page_number": 1,
"message": "OK"
}
accepts results_per_page parameter
GET /questionnaires?results_per_page=5
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 6,
"total_pages": 2,
"status": 200,
"results_per_page": 5,
"questionnaires": [
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
}
],
"page_number": 1,
"message": "OK"
}
accepts page_number parameter
GET /questionnaires?results_per_page=1&page_number=2
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 2,
"total_pages": 2,
"status": 200,
"results_per_page": 1,
"questionnaires": [
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": true,
"inserted_at": "2018-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
}
],
"page_number": 2,
"message": "OK"
}
limits results_per_page to 100
GET /questionnaires?results_per_page=101
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
400
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 400,
"message": "Bad Request",
"errors": {
"request": [
"Page size of 101 above limit of 100"
]
}
}
accepts sorting parameters
GET /questionnaires?sort=desc_nulls_first:completed_at
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"total_results": 4,
"total_pages": 1,
"status": 200,
"results_per_page": 50,
"questionnaires": [
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": "2018-01-01T00:00:03Z",
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": "2018-01-01T00:00:02Z",
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": "2018-01-01T00:00:01Z",
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00",
"question_answer_pairs": [],
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": "2018-01-01T00:00:00Z",
"api_metadata": {}
}
],
"page_number": 1,
"message": "OK"
}
rejects invalid sorting parameters
GET /questionnaires?sort=asc(fake_column)
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
400
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 400,
"message": "Bad Request",
"errors": {
"request": [
"Invalid sort field format `asc(fake_column)`. Expected `direction:field`"
]
}
}
List of Questionnaires
Request
GET /_api/questionnaires/
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | QuestionnaireIndexResponse |
A single Questionnaire
with a valid id, returns that questionnaire
GET /questionnaires/00000000-0000-0000-0000-000000000000
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"updated_at": "2020-01-01T00:00:00",
"status": 200,
"question_answer_pairs": [],
"message": "OK",
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {}
}
with an invalid id, returns a 404
GET /questionnaires/00000000-0000-0000-0000-000000000000
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
404
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 404,
"message": "Not Found"
}
with an invalid id type, returns a 400
GET /questionnaires/non-uuid-garbage
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
400
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 400,
"message": "Bad Request",
"errors": {
"request": [
"id is invalid"
]
}
}
Request
GET /_api/questionnaires/{id}
Parameters
| Parameter | Description | In | Type | Required | Default | Example |
|---|---|---|---|---|---|---|
| id | Questionnaire ID | path | string | true |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | Questionnaire |
Update a Questionnaire within the provider
update/2 updates a questionnaire's api_metadata
PATCH /questionnaires/00000000-0000-0000-0000-000000000000
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"api_metadata": {
"external_id": "EXT-2"
}
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"updated_at": "2020-01-01T00:00:00",
"status": 200,
"question_answer_pairs": [],
"message": "OK",
"is_completed": false,
"inserted_at": "2020-01-01T00:00:00",
"id": "00000000-0000-0000-0000-000000000000",
"engagement_id": "00000000-0000-0000-0000-000000000000",
"completed_at": null,
"api_metadata": {
"external_id": "EXT-2"
}
}
Updates the api_metadata of a Questionnaire. Only api_metadata can be updated. Omit it to leave the stored value unchanged. Any other field in the body returns a 400.
Request
PATCH /_api/questionnaires/{id}
Parameters
| Parameter | Description | In | Type | Required | Default | Example |
|---|---|---|---|---|---|---|
| id | Questionnaire ID | path | string | true | ||
| body | Questionnaire update attributes | body | QuestionnaireUpdateRequest | true |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | Questionnaire |
| 400 | Bad Request | |
| 404 | Not Found | |
| 409 | Conflict |
User
Create a User within the provider
create/2 creates a user and returns the full payload
POST /users
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"last_name": "User",
"is_client": true,
"first_name": "Created",
"email": "created@example.com",
"api_metadata": {
"employee_id": "E-1",
"dsi_person_id": "DSI-9"
}
}
Response
201
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"updated_at": "2020-01-01T00:00:00Z",
"status": 201,
"registered_at": null,
"message": "Created",
"manager_program_ids": [],
"logged_in_at": null,
"last_name": "User",
"is_sponsor": false,
"is_coach": false,
"is_client": true,
"is_admin": false,
"is_active": true,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"first_name": "Created",
"email": "created@example.com",
"coach_program_ids": [],
"coach_profile_id": null,
"coach_option_engagement_ids": [],
"coach_engagement_ids": [],
"client_engagement_ids": [],
"api_metadata": {
"employee_id": "E-1",
"dsi_person_id": "DSI-9"
}
}
Create a User. Roles are set via is_coach/is_client/is_sponsor - at least one must be true. The admin role cannot be assigned via this endpoint: is_admin: true is rejected with a 400.
Request
POST /_api/users/
Parameters
| Parameter | Description | In | Type | Required | Default | Example |
|---|---|---|---|---|---|---|
| body | User attributes | body | UserCreateRequest | true |
Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Created | User |
| 400 | Bad Request | |
| 409 | Conflict |
Deactivate a User within the provider
deactivate/2 removes every role and returns the user
POST /users/00000000-0000-0000-0000-000000000000/deactivate
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"reason": "left the company"
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"updated_at": "2020-01-01T00:00:00Z",
"status": 200,
"registered_at": null,
"message": "OK",
"manager_program_ids": [],
"logged_in_at": null,
"last_name": "Smith",
"is_sponsor": false,
"is_coach": false,
"is_client": false,
"is_admin": false,
"is_active": false,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"first_name": "Jane",
"email": null,
"coach_program_ids": [],
"coach_profile_id": null,
"coach_option_engagement_ids": [],
"coach_engagement_ids": [],
"client_engagement_ids": [],
"api_metadata": {}
}
Deactivate a User by removing every role they hold. The user is left with no roles and is reported as is_active: false. Removed roles are kept as inactive roles so an admin can restore them later. A user cannot give up a role while an engagement still depends on it, so every open engagement the user is the coach or the client on is closed first, with the end_reason "Ended Early - Coach Deactivated" or "Ended Early - Client Deactivated", and every coach offer naming the user on an engagement whose client has not picked a coach yet is withdrawn. An offer on an engagement whose client already picked a coach is left in place.
Request
POST /_api/users/{id}/deactivate
Parameters
| Parameter | Description | In | Type | Required | Default | Example |
|---|---|---|---|---|---|---|
| id | User ID | path | string | true | ||
| body | Deactivation details | body | UserDeactivateRequest | false |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | User |
| 400 | Bad Request | |
| 404 | Not Found |
A paginated list of Users
allows PUT requests to support more parameters
PUT /users
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"sort": "asc:inserted_at",
"results_per_page": 3
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"users": [
{
"updated_at": "2020-01-01T00:00:00Z",
"registered_at": null,
"manager_program_ids": [],
"logged_in_at": null,
"last_name": "Smith",
"is_sponsor": false,
"is_coach": false,
"is_client": true,
"is_admin": false,
"is_active": true,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"first_name": "Jane",
"email": null,
"coach_program_ids": [],
"coach_profile_id": null,
"coach_option_engagement_ids": [],
"coach_engagement_ids": [],
"client_engagement_ids": [],
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00Z",
"registered_at": null,
"manager_program_ids": [],
"logged_in_at": null,
"last_name": "Smith",
"is_sponsor": false,
"is_coach": false,
"is_client": true,
"is_admin": false,
"is_active": true,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"first_name": "Jane",
"email": null,
"coach_program_ids": [],
"coach_profile_id": null,
"coach_option_engagement_ids": [],
"coach_engagement_ids": [],
"client_engagement_ids": [],
"api_metadata": {}
},
{
"updated_at": "2020-01-01T00:00:00Z",
"registered_at": null,
"manager_program_ids": [],
"logged_in_at": null,
"last_name": "Smith",
"is_sponsor": false,
"is_coach": false,
"is_client": true,
"is_admin": false,
"is_active": true,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"first_name": "Jane",
"email": null,
"coach_program_ids": [],
"coach_profile_id": null,
"coach_option_engagement_ids": [],
"coach_engagement_ids": [],
"client_engagement_ids": [],
"api_metadata": {}
}
],
"total_results": 5,
"total_pages": 2,
"status": 200,
"results_per_page": 3,
"page_number": 1,
"message": "OK"
}
List of Users
Request
GET /_api/users/
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | UserIndexResponse |
A single User
with a valid id, returns that user
GET /users/00000000-0000-0000-0000-000000000000
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"updated_at": "2020-01-01T00:00:00Z",
"status": 200,
"registered_at": null,
"message": "OK",
"manager_program_ids": [],
"logged_in_at": null,
"last_name": "Smith",
"is_sponsor": false,
"is_coach": true,
"is_client": false,
"is_admin": true,
"is_active": true,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"first_name": "Jane",
"email": null,
"coach_program_ids": [],
"coach_profile_id": "00000000-0000-0000-0000-000000000000",
"coach_option_engagement_ids": [],
"coach_engagement_ids": [],
"client_engagement_ids": [],
"api_metadata": {
"dsi_person_id": "dsi-123"
}
}
with an invalid id, returns a 404
GET /users/00000000-0000-0000-0000-000000000000
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
404
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 404,
"message": "Not Found"
}
with an invalid id type, returns a 400
GET /users/non-uuid-garbage
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
Response
400
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"status": 400,
"message": "Bad Request",
"errors": {
"request": [
"id is invalid"
]
}
}
Request
GET /_api/users/{id}
Parameters
| Parameter | Description | In | Type | Required | Default | Example |
|---|---|---|---|---|---|---|
| id | User ID | path | string | true |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | User |
Update a User within the provider
update/2 updates first_name and last_name
PATCH /users/00000000-0000-0000-0000-000000000000
content-type: v=1
authorization: api-key 00000000-0000-0000-0000-000000000000
{
"last_name": "Person",
"first_name": "Updated"
}
Response
200
content-type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: EXAMPLE-REQUEST-ID
{
"updated_at": "2020-01-01T00:00:00Z",
"status": 200,
"registered_at": null,
"message": "OK",
"manager_program_ids": [],
"logged_in_at": null,
"last_name": "Person",
"is_sponsor": false,
"is_coach": false,
"is_client": true,
"is_admin": false,
"is_active": true,
"inserted_at": "2020-01-01T00:00:00Z",
"id": "00000000-0000-0000-0000-000000000000",
"first_name": "Updated",
"email": "original@example.com",
"coach_program_ids": [],
"coach_profile_id": null,
"coach_option_engagement_ids": [],
"coach_engagement_ids": [],
"client_engagement_ids": [],
"api_metadata": {}
}
Update a User. All fields are optional; only provided fields change and unknown fields are ignored. Roles cannot be changed through this endpoint: an is_coach/is_client/is_sponsor/is_admin/is_active field that asks for anything other than what the user already is is rejected with a 400 rather than ignored. Name and email cannot be changed for a user that belongs to more than one provider.
Request
PATCH /_api/users/{id}
Parameters
| Parameter | Description | In | Type | Required | Default | Example |
|---|---|---|---|---|---|---|
| id | User ID | path | string | true | ||
| body | User update attributes | body | UserUpdateRequest | true |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | User |
| 400 | Bad Request | |
| 404 | Not Found | |
| 409 | Conflict |