Developer Resources
Introduction
Welcome to the MinistrySafe and Abuse Prevention Systems API.
You may use this API to assign Trainings, manage Trainings, Background Checks and deliver our content and quizzes in your own system.
Contact [email protected]Â for a sandbox account
Developers console url for staging environment: https://staging.ministrysafe.com/developers
Developers console url for production environment: https://safetysystem.ministrysafe.com/developers
Authentication
The API uses token authentication. We expect the API key to be included in all API requests to the server in a header that looks like this:
"Authorization" => "Token token=myapitoken"
You must replace myapitoken
 with your actual API key.
To authorize, use this code:
With shell, you can just pass the correct header with each request
Make sure to replace myapitoken with your API key.
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
-H "Authorization: Token token=myapitoken"
Users
Get All Users
Retrieves a list of Users. Users will be returned up to 100 at a time. This endpoint supports paging, and the default page is 1. To retrieve the next hundred Users, change the page param to 2, 3, 4 etc.
HTTP Request
GET https://safetysystem.ministrysafe.com/api/v2/users
Query Parameters
Parameter | Default | Description |
---|---|---|
page | 1 | The page of Users that will be returned |
external_id | Will filter the returned Users by external_id | |
search | Will filter the returned Users by a keyword search | |
tag | Only Users having this Tag will be returned |
curl "https://safetysystem.ministrysafe.com/api/v2/users"
-H "Authorization: Token token=myapitoken"
The command above returns JSON structured like this:
[
{
"id": 423,
"first_name": "Test",
"last_name": "User",
"email": "[email protected]",
"score": 80,
"complete_date": "2016-08-17T17:07:07.292Z",
"direct_login_url": "https://safetysystem.ministrysafe.com/trainings/quiz?t=jds95h2lslf92nl4klsd02n3",
"user_type": "employee",
"external_id": "111",
"employee_id": "111",
"tags": [
"Tag-1",
"Tag-2",
"Tag-3"
]
},
{
"id": 139,
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"score": 100,
"complete_date": "2016-08-03T01:59:32.622Z",
"direct_login_url": "https://safetysystem.ministrysafe.com/trainings/quiz?t=jds95h2lslf92nl4klsd02n3",
"user_type": "volunteer",
"external_id": "123",
"employee_id": "123",
"tags": [
"Tag-4",
"Tag-5"
]
}
]
Get All Users with Page
Retrieves a list of Users. Users will be returned up to 100 at a time. This endpoint supports paging, and the default page is 1. To retrieve the next hundred Users, change the page param to 2, 3, 4 etc. Compared to Get All Users, this endpoint includes the current page and total page count.
HTTP Request
GET https://safetysystem.ministrysafe.com/api/v2/users/with_page
Query Parameters
Parameter | Default | Description |
---|---|---|
page | 1 | The page of Users that will be returned |
external_id | Will filter the returned Users by external_id | |
search | Will filter the returned Users by a keyword search | |
tag | Only Users having this Tag will be returned |
curl "https://safetysystem.ministrysafe.com/api/v2/users/with_page"
-H "Authorization: Token token=myapitoken"
The command above returns JSON structured like this:
{
"users": [
{
"id": 423,
"first_name": "Test",
"last_name": "User",
"email": "[email protected]",
"score": 80,
"complete_date": "2016-08-17T17:07:07.292Z",
"direct_login_url": "https://safetysystem.ministrysafe.com/trainings/quiz?t=jds95h2lslf92nl4klsd02n3",
"user_type": "employee",
"external_id": "111",
"employee_id": "111",
"tags": [
"Tag-1",
"Tag-2",
"Tag-3"
]
},
{
"id": 139,
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"score": 100,
"complete_date": "2016-08-03T01:59:32.622Z",
"direct_login_url": "https://safetysystem.ministrysafe.com/trainings/quiz?t=jds95h2lslf92nl4klsd02n3",
"user_type": "volunteer",
"external_id": "123",
"employee_id": "123",
"tags": [
"Tag-4",
"Tag-5"
]
}
],
"page": 1,
"pages": 1
}
Get a User
This endpoint retrieves a specific User.
HTTP Request
GET https://safetysystem.ministrysafe.com/api/v2/users/<ID>
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the User to retrieve |
curl "https://safetysystem.ministrysafe.com/api/v2/users/2"
-H "Authorization: Token token=myapitoken"
The command above returns JSON structured like this:
{
"id": 423,
"first_name": "Test",
"last_name": "User",
"email": "[email protected]",
"score": 80,
"complete_date": "2016-08-17T17:07:07.292Z",
"direct_login_url": "https://safetysystem.ministrysafe.com/trainings/quiz?t=jds95h2lslf92nl4klsd02n3",
"user_type": "employee",
"external_id": "111",
"employee_id": "111",
"tags": [
"Tag-1",
"Tag-2"
]
}
Get a User (Detailed)
This endpoint retrieves a specific User with additional details.
HTTP Request
GET https://safetysystem.ministrysafe.com/api/v2/users/<ID>/detailed
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the User to retrieve |
curl "https://safetysystem.ministrysafe.com/api/v2/users/2/detailed"
-H "Authorization: Token token=myapitoken"
The command above returns JSON structured like this:
{
"id": 423,
"first_name": "Test",
"last_name": "User",
"email": "[email protected]",
"score": 80,
"complete_date": "2016-08-17T17:07:07.292Z",
"direct_login_url": "https://safetysystem.ministrysafe.com/trainings/quiz?t=jds95h2lslf92nl4klsd02n3",
"user_type": "employee",
"external_id": "111",
"employee_id": "111",
"tags": [
"Tag-1",
"Tag-2"
],
"trainings": [
{
"id": 4,
"winner": true,
"score": 80,
"created_at": "2018-01-30T19:22:11.675-06:00",
"complete_date": "2018-01-30T21:42:58.675-06:00",
"survey_name": "Sexual Abuse Awareness Training (2021)",
"survey_code": "standard",
"certificate_url": "http://safetysystem.ministrysafe.com/trainings/4?print=true",
"participant": {
"id": 423,
"employee_id": "111",
"first_name": "Test",
"last_name": "User"
}
}
],
"background_checks": [
{
"id": 7122,
"order_date": "2017-07-18T11:39:46.503-05:00",
"status": "complete",
"user_id": 432,
"level": 3,
"applicant_self_disclosed": true,
"applicant_self_disclosed_note": {
"id": 123,
"status": "pending",
"disclosure_status": "not_viewed",
"self_disclosed_notes": "They ate the last piece of pizza.",
"internal_notes": null
},
"tazwork_flagged": true,
"results_url": "http://theresults.com/unique-results-link",
"applicant_interface_url": "http://theresults.com/form-for-applicant-to-complete"
}
]
}
Get a User by Employee ID
This endpoint retrieves a specific User by their employee ID.
HTTP Request
GET https://safetysystem.ministrysafe.com/api/v2/users/by_employee_id/<employee_id>
URL Parameters
Parameter | Description |
---|---|
employee_id | The employee_id of the User to retrieve |
curl "https://safetysystem.ministrysafe.com/api/v2/users/by_employee_id/111"
-H "Authorization: Token token=myapitoken"
The command above returns JSON structured like this:
{
"id": 423,
"first_name": "Test",
"last_name": "User",
"email": "[email protected]",
"score": 80,
"complete_date": "2016-08-17T17:07:07.292Z",
"direct_login_url": "https://safetysystem.ministrysafe.com/trainings/quiz?t=jds95h2lslf92nl4klsd02n3",
"user_type": "employee",
"external_id": "111",
"employee_id": "111",
"tags": [
"Tag-1",
"Tag-2"
]
}
Get a User by Employee ID (Detailed)
This endpoint retrieves a specific User by their employee ID with additional details.
HTTP Request
GET https://safetysystem.ministrysafe.com/api/v2/users/by_employee_id/<employee_id>/detailed
URL Parameters
Parameter | Description |
---|---|
employee_id | The employee_id of the User to retrieve |
curl "https://safetysystem.ministrysafe.com/api/v2/users/by_employee_id/111/detailed"
-H "Authorization: Token token=myapitoken"
The command above returns JSON structured like this:
{
"id": 423,
"first_name": "Test",
"last_name": "User",
"email": "[email protected]",
"score": 80,
"complete_date": "2016-08-17T17:07:07.292Z",
"direct_login_url": "https://safetysystem.ministrysafe.com/trainings/quiz?t=jds95h2lslf92nl4klsd02n3",
"user_type": "employee",
"external_id": "111",
"employee_id": "111",
"tags": [
"Tag-1",
"Tag-2"
],
"trainings": [
{
"id": 4,
"winner": true,
"score": 80,
"created_at": "2018-01-30T19:22:11.675-06:00",
"complete_date": "2018-01-30T21:42:58.675-06:00",
"survey_name": "Sexual Abuse Awareness Training (2021)",
"survey_code": "standard",
"certificate_url": "http://safetysystem.ministrysafe.com/trainings/4?print=true",
"participant": {
"id": 423,
"employee_id": "111",
"first_name": "Test",
"last_name": "User"
}
}
],
"background_checks": [
{
"id": 7122,
"order_date": "2017-07-18T11:39:46.503-05:00",
"status": "complete",
"user_id": 432,
"level": 3,
"applicant_self_disclosed": true,
"applicant_self_disclosed_note": {
"id": 123,
"status": "pending",
"disclosure_status": "not_viewed",
"self_disclosed_notes": "They ate the last piece of pizza.",
"internal_notes": null
},
"tazwork_flagged": true,
"results_url": "http://theresults.com/unique-results-link",
"applicant_interface_url": "http://theresults.com/form-for-applicant-to-complete"
}
]
}
Create a User
This endpoint creates a new User
HTTP Request
GET POST https://safetysystem.ministrysafe.com/api/v2/users
User Attributes
Parameter | Required | Description |
---|---|---|
first_name | Yes | The first name of the User |
last_name | Yes | The last name of the User |
Yes | The User's email address | |
user_type | No | ['employee', 'volunteer'] |
external_id | No | As another option, you may assign a User an ID for use in integration with your own system. |
curl "https://safetysystem.ministrysafe.com/api/v2/users"
-X POST
-H "Authorization: Token token=myapitoken"
-d "user[first_name]=Tom&user[last_name]=Harrington&user[email][email protected]&user[external_id]=1234&tag_list=tag1,tag2,tag3"
Example Success Response:
{
"id": 315,
"first_name": "Tom",
"last_name": "Harrington",
"email": "[email protected]",
"score": 95,
"complete_date": "2016-08-17T17:07:07.292Z",
"direct_login_url": "https://safetysystem.ministrysafe.com/trainings/quiz?t=7671cf713e382812b749dbed2aa52f438ffc815f278a6c41",
"user_type": "employee",
"external_id": "123",
"employee_id": "123",
"tags": []
}
Example Error Response:
{
"errors": {
"first_name": [
"You must provide a first name"
],
"last_name": [
"You must provide a last name"
]
}
}
Update a User
This endpoint updates a User
HTTP Request
PUT https://safetysystem.ministrysafe.com/api/v2/users/<ID>
User Attributes
Parameter | Required | Description |
---|---|---|
first_name | No | New User's first name |
last_name | No | New User's last name |
No | New User's email | |
tag_list | No | New User's Tag list |
curl "https://safetysystem.ministrysafe.com/api/v2/users/1"
-X PUT
-H "Authorization: Token token=myapitoken"
-d "user[first_name]=Tim&tag_list=tag1,tag2,tag3"
Example Success Response:
204
Example Error Response:
{
"errors": {
"first_name": [
"You must provide a first name"
],
"last_name": [
"You must provide a last name"
]
}
}
Deactivate a User
This endpoint deletes a specific User.
HTTP Request
DELETE https://safetysystem.ministrysafe.com/api/v2/users/<ID>
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the User to delete |
curl "https://safetysystem.ministrysafe.com/api/v2/users/2"
-H "Authorization: Token token=myapitoken"
No Content Body
Trainings
Get All Trainings
Retrieves all Trainings that have been assigned to Users in the Organization.
HTTP Request
GET https://safetysystem.ministrysafe.com/api/v2/trainings
Query Parameters
Parameter | Required | Description |
---|---|---|
page | 1 | The page of Trainings that will be returned |
start_date | The start date for Background Check assignments (Format: mm/dd/yyyy) | |
end_date | The end date for Background Check assignments (Format: mm/dd/yyyy) |
curl "https://safetysystem.ministrysafe.com/api/v2/trainings"
-H "Authorization: Token token=myapitoken"
The command above returns JSON structured like this:
[
{
"id": 1,
"winner": true,
"score": 100,
"created_at": "2018-01-30T19:22:11.675-06:00",
"complete_date": "2018-01-30T21:42:58.675-06:00",
"survey_name": "Sexual Abuse Awareness Training (2021)",
"survey_code": "standard",
"certificate_url": "http://safetysystem.ministrysafe.com/trainings/4?print=true",
"participant": {
"id": 123,
"employee_id": "123",
"first_name": "John",
"last_name": "Doe"
}
}
]
Get All Trainings for a User
Retrieves all Trainings that have been assigned to a User.
HTTP Request
GET https://safetysystem.ministrysafe.com/api/v2/users/<ID>/trainings
Query Parameters
Parameter | Required | Description |
---|---|---|
ID | Yes | The ID of the User for whom you want to retrieve Trainings |
curl "https://safetysystem.ministrysafe.com/api/v2/users/2/trainings"
-H "Authorization: Token token=myapitoken"
The command above returns JSON structured like this:
[
{
"id": 12345,
"winner": true,
"score": 100,
"created_at": "2018-01-30T19:22:11.675-06:00",
"complete_date": "2018-01-30T21:42:58.675-06:00",
"survey_name": "Sexual Abuse Awareness Training (2021)",
"survey_code": "standard",
"certificate_url": "http://safetysystem.ministrysafe.com/trainings/4?print=true",
"participant": {
"id": 123,
"employee_id": "123",
"first_name": "John",
"last_name": "Sawyer"
}
}
]
Get All Trainings for a User by Employee ID
Retrieves all Trainings that have been assigned to a User.
HTTP Request
GET https://safetysystem.ministrysafe.com/api/v2/users/by_employee_id/<employee_id>/trainings
Query Parameters
Parameter | Required | Description |
---|---|---|
employee_id | Yes | The employee_id of the User for whom you want to retrieve Trainings |
curl "https://safetysystem.ministrysafe.com/api/v2/users/by_employee_id/123/trainings"
-H "Authorization: Token token=myapitoken"
The command above returns JSON structured like this:
[
{
"id": 12345,
"winner": true,
"score": 100,
"created_at": "2018-01-30T19:22:11.675-06:00",
"complete_date": "2018-01-30T21:42:58.675-06:00",
"survey_name": "Sexual Abuse Awareness Training (2021)",
"survey_code": "standard",
"certificate_url": "http://safetysystem.ministrysafe.com/trainings/4?print=true",
"participant": {
"id": 123,
"employee_id": "123",
"first_name": "John",
"last_name": "Sawyer"
}
}
]
Assign a Training to a User
HTTP Request
POST https://safetysystem.ministrysafe.com/api/v2/users/<ID>/assign_training
Query Parameters
Parameter | Required | Description |
---|---|---|
ID | Yes | The ID of the User to whom the Training will be assigned |
survey_code | No | The code for the Training that will be assigned |
send_email | No | Indicates whether an email is automatically sent to the Trainee (default is false ) |
upfront_payment | No | Indicates whether this is to be billed as self-pay (default is false ) |
Survey Types
code | description |
---|---|
standard |
The most recent Sexual Abuse Awareness Training |
youth |
Sexual Abuse Awareness Training - Youth Sports |
camp |
Sexual Abuse Awareness Training - Camp |
spanish |
Sexual Abuse Awareness Training - Spanish |
daycare |
Sexual Abuse Awareness Training - Daycare |
education |
Sexual Abuse Awareness Training - Education |
youth_ministry |
Sexual Abuse Awareness Training - Youth Ministry |
skillful_screening |
Skillful Screening Training |
parent_training |
Parent/Guardian Training |
california |
Sexual Abuse Awareness Training (CA)* |
peer_to_peer_training |
Peer-to-Peer Sexual Abuse Training |
harassment |
Preventing Sexual Harassment Training (for Supervisors) |
* This Training specifically includes new California legal requirements
curl "https://safetysystem.ministrysafe.com/api/v2/users/2/assign_training"
-X POST
-H "Authorization: Token token=myapitoken"
-d "survey_code=standard"
Example Success Response:
{
"id": 315,
"first_name": "Tom",
"last_name": "Harrington",
"email": "[email protected]",
"score": 95,
"complete_date": "2016-08-17T17:07:07.292Z",
"user_type": "employee",
"direct_login_url": "https://safetysystem.ministrysafe.com/trainings/quiz?t=7671cf713e382812b749dbed2aa52f438ffc815f278a6c41",
"external_id": "123",
"participant": {
"id": 123,
"employee_id": "123",
"first_name": "John",
"last_name": "Sawyer"
}
}
Example Error Response:
{
"message": "Invalid survey code"
}
Resend a Training
Resends the specified Training to a User.
HTTP Request
POST https://safetysystem.ministrysafe.com/api/v2/users/<ID>/resend_training
Query Parameters
Parameter | Required | Description |
---|---|---|
ID | Yes | The ID of the User to whom the Training will be resent |
survey_code | No | The code for the Training that will be resent |
curl "https://safetysystem.ministrysafe.com/api/v2/users/2/resend_training"
-X POST
-H "Authorization: Token token=myapitoken"
-d "survey_code=standard"
Example Success Response:
{
"id": 315,
"first_name": "Tom",
"last_name": "Harrington",
"email": "[email protected]",
"score": 95,
"complete_date": "2016-08-17T17:07:07.292Z",
"user_type": "employee",
"direct_login_url": "https://safetysystem.ministrysafe.com/trainings/quiz?t=7671cf713e382812b749dbed2aa52f438ffc815f278a6c41",
"external_id": "123"
}
Example Error Response:
{
"message": "Invalid survey code"
}
Get Available Survey Types
Each Organization may have different Survey Types or Trainings available to its Users. This endpoint returns the Survey Types available to assign to an Organization's User.
HTTP Request
GET https://safetysystem.ministrysafe.com/api/v2/survey_types
curl "https://safetysystem.ministrysafe.com/api/v2/survey_types"
-X GET
-H "Authorization: Token token=myapitoken"
Example Success Response:
[
"awareness",
"harassment",
"skillful_screening"
]
Background Checks
Get All Background Checks
Retrieves a list of Background Checks for your Organization. Background Checks will be returned up to 100 at a time. This endpoint supports paging, and the default page is 1. To retrieve the next hundred Users, change the page param to 2, 3, 4, etc.
HTTP Request
GET https://safetysystem.ministrysafe.com/api/v2/background_checks
Query Parameters
Parameter | Default | Description |
---|---|---|
user_id | The user_id to filter BackgroundChecks on (Format: int) | |
employee_id | The employee_id to filter BackgroundChecks on (Format: int) | |
start_date | The start date to filter Background Checks that were assigned on or after (Format: mm/dd/yyyy) | |
end_date | The end date to filter Background Checks that were assigned on or before (Format: mm/dd/yyyy) | |
page | 1 | The page of Background Checks that will be returned |
curl "https://safetysystem.ministrysafe.com/api/v2/background_checks"
-X POST
-H "Authorization: Token token=myapitoken"
The command above returns JSON structured like this:
[
{
"id": 7122,
"order_date": "2017-07-18T11:39:46.503-05:00",
"status": "complete",
"user_id": 2121,
"level": 3,
"applicant_self_disclosed": true,
"applicant_self_disclosed_note": {
"id": 123,
"status": "pending",
"disclosure_status": "not_viewed",
"self_disclosed_notes": "They ate the last piece of pizza.",
"internal_notes": null
},
"tazwork_flagged": true,
"results_url": "http://theresults.com/unique-results-link",
"applicant_interface_url": "http://theresults.com/form-for-applicant-to-complete"
}
]
Get All Background Checks for a User
This endpoint retrieves the Background Checks for a User.
HTTP Request
GET https://safetysystem.ministrysafe.com/api/v2/users/<ID>/background_checks
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the User for whom you want to retrieve Background Checks |
curl "https://safetysystem.ministrysafe.com/api/v2/users/7122/background_checks"
-H "Authorization: Token token=myapitoken"
The command above returns JSON structured like this:
[
{
"id": 7122,
"order_date": "2017-07-18T11:39:46.503-05:00",
"status": "complete",
"user_id": 2121,
"level": 3,
"applicant_self_disclosed": true,
"applicant_self_disclosed_note": {
"id": 123,
"status": "pending",
"disclosure_status": "not_viewed",
"self_disclosed_notes": "They ate the last piece of pizza.",
"internal_notes": null
},
"tazwork_flagged": true,
"results_url": "http://theresults.com/unique-results-link",
"applicant_interface_url": "http://theresults.com/form-for-applicant-to-complete"
}
]
Get All Background Checks for a User by Employee ID
This endpoint retrieves the Background Checks for a User by Employee ID.
HTTP Request
GET https://safetysystem.ministrysafe.com/api/v2/users/by_employee_id/<employee_id>/background_checks
URL Parameters
Parameter | Description |
---|---|
employee_id | The employee_id of the User for whom you want to retrieve Background Checks |
curl "https://safetysystem.ministrysafe.com/api/v2/users/by_employee_id/123/background_checks"
-H "Authorization: Token token=myapitoken"
The command above returns JSON structured like this:
[
{
"id": 7122,
"order_date": "2017-07-18T11:39:46.503-05:00",
"status": "complete",
"user_id": 2121,
"level": 3,
"applicant_self_disclosed": true,
"applicant_self_disclosed_note": {
"id": 123,
"status": "pending",
"disclosure_status": "not_viewed",
"self_disclosed_notes": "They ate the last piece of pizza.",
"internal_notes": null
},
"tazwork_flagged": true,
"results_url": "http://theresults.com/unique-results-link",
"applicant_interface_url": "http://theresults.com/form-for-applicant-to-complete"
}
]
Get a Background Check
This endpoint retrieves a specific Background Check record.
HTTP Request
GET https://safetysystem.ministrysafe.com/api/v2/background_checks/<ID>
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the Background Check to retrieve |
curl "https://safetysystem.ministrysafe.com/api/v2/background_checks/123"
-H "Authorization: Token token=myapitoken"
The command above returns JSON structured like this:
{
"id": 7122,
"order_date": "2017-07-18T11:39:46.503-05:00",
"status": "complete",
"user_id": 2121,
"level": 3,
"applicant_self_disclosed": true,
"applicant_self_disclosed_note": {
"id": 123,
"status": "pending",
"disclosure_status": "not_viewed",
"self_disclosed_notes": "They ate the last piece of pizza.",
"internal_notes": null
},
"tazwork_flagged": true,
"results_url": "http://theresults.com/unique-results-link",
"applicant_interface_url": "http://theresults.com/form-for-applicant-to-complete"
}
Create a Background Check
This endpoint creates a new Background Check.
HTTP Request
POST https://safetysystem.ministrysafe.com/api/v2/background_checks
Background Check Attributes
Parameter | Required | Type | Description |
---|---|---|---|
user_id | Yes | integer | The ID of the User for whom the Background Check will be ordered |
level | No* | integer | The level of the Background Check being ordered |
custom_background_check_package_code | No* | string | The code of the custom Background Check package being requested |
quickapp | Yes | boolean | If true, an email will be sent to the applicant to fill out details. If false, all applicant information must be submitted in the initial request. |
first_name | No** | string | The first name of the applicant |
last_name | No** | string | The last name of the applicant |
address | No** | string | The street address of the applicant's residence |
city | No** | string | The city of the applicant's residence |
county | No** | string | The county of the applicant's residence |
state | No** | string | The two letter state code of the applicant's residence |
zip | No** | string | The zip code of the applicant's residence |
ssn | No** | string | The Social Security Number of the applicant |
dob | No** | string format "MM/DD/YYYY" | The applicant's date of birth |
driver_license | No*** | string | The applicant's drivers license number |
driver_license_state | No*** | string | The two letter code of the applicant's drivers license state |
No** | string | The email address of the applicant | |
user_type | No | string | ['employee', 'volunteer'] |
child_serving | No | boolean | Designates whether the User is in a child-serving role |
salary_range | No | string | ['under_20k', '20k_25k', '25k_75k', '75k_plus'] |
age_over_13 | No | boolean | Designates whether the applicant is over 13 years of age |
employee_type | No | string | ['current', 'prospective'] |
applicant_self_disclosed | No | boolean | Designates whether the applicant self discloses |
applicant_self_disclosed_notes | No | string | The applicant's notes if self disclosed |
* One of either level
 or custom_background_check_package_code
 are required
** Required if not doing a QuickApp (quickapp
=false
)
*** Required for levels 2, 4, 5, 6, 7, and some custom packages
curl "https://safetysystem.ministrysafe.com/api/v2/background_checks"
-X POST
-H "Authorization: Token token=myapitoken"
-d "background_check[user_id]=123&background_check[quickapp]=true&background_check[level]=1"
Example Success Response:
{
"id": 7423,
"order_date": "2018-01-16T10:54:02.585-06:00",
"status": "processing",
"applicant_interface_url": "http://theresults.com/form-for-applicant-to-complete",
"results_url": null,
"user_id": 123,
"level": 1
}
Example Error Response:
{
"errors": {
"first_name": [
"You must provide a first name"
],
"last_name": [
"You must provide a last name"
]
}
}
Archive a Background Check
This endpoint archives a Background Check.
HTTP Request
PUT https://safetysystem.ministrysafe.com/api/v2/background_checks/<ID>/archive
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the Background Check to archive |
curl "https://safetysystem.ministrysafe.com/api/v2/background_checks/123/archive"
-X PUT
-H "Authorization: Token token=myapitoken"
Example Success Response:
{
"id": 7423,
"order_date": "2018-01-16T10:54:02.585-06:00",
"status": "archived",
"applicant_interface_url": "http://theresults.com/form-for-applicant-to-complete",
"results_url": null,
"user_id": 123,
"level": 1
}
Example Error Response:
{
"message": "Background Check not found"
}
Get Available Levels
Each Organization may have different Levels available to its Users. This endpoint returns the Background Check Levels available to order on an Organization's User.
HTTP Request
GET https://safetysystem.ministrysafe.com/api/v2/available_levels
curl "https://safetysystem.ministrysafe.com/api/v2/background_checks/available_levels"
-X GET
-H "Authorization: Token token=myapitoken"
Example Success Response:
[
1,
2,
3,
4,
5
]
Get All Tags
Retrieves a list of Tags related to your Organization. Tags will be returned up to 100 at a time. This endpoint supports paging, and the default page is 1. To retrieve the next hundred Tags, change the page param to 2, 3, 4, etc.
HTTP Request
GET https://safetysystem.ministrysafe.com/api/v2/tags
Query Parameters
Parameter | Default | Description |
---|---|---|
page | 1 | The page of Tags that will be returned |
curl "https://safetysystem.ministrysafe.com/api/v2/tags"
-H "Authorization: Token token=myapitoken"
The command above returns JSON structured like this:
[
{
"name": "Tag A"
},
{
"name": "Tag B"
}
]
Webhooks
Quizzes
Implementation
Webhooks are triggered upon successful User completion of a Training and may be configured in your developer console.
If webhooks are enabled, we send an HTTP POST request to the URLs you specify when a Trainee completes a quiz.
The webhook posts a JSON body structured like this:
{
"user_id": "123",
"external_id": "111",
"score": 80,
"complete_date": "2016-08-17T17:07:07.292Z",
"survey_code": "standard",
"certificate_url": "https://safetysystem.ministrysafe.com/path/to/certificate"
}
Background Checks
Implementation
Webhooks are triggered when the Background Check is ready to be reviewed and may be configured in your developer console.
If webhooks are enabled, we send an HTTP POST request to the URLs you specify when a Background Check is ready for review.
The webhook posts a JSON body structured like this:
{
"id": "100",
"user_id": "123",
"email": "[email protected]",
"external_id": "111",
"results_url": "https://reports.ministrysafe.com/send/interchangeview/?parameters=values",
"complete_date": "2020-07-30T10:35:21.548Z"
}
Errors
The API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
403 | Forbidden -- You do not have access to the requested resource. |
404 | Not Found -- The specified record could not be found. |
500 | Internal Server Error -- We had a problem with our server. Try again later. |