NAV
shell
  • Introduction
  • Authentication
  • Users
  • Trainings
  • Background Checks
  • Tags
  • Webhooks
  • Errors
  • Introduction

    Welcome to the MinistrySafe and Abuse Prevention Systems API.

    You can use this API to assign trainings, manage trainings, and deliver our content and quizzes in your own system.

    Authentication

    To authorize, use this code:

    # With shell, you can just pass the correct header with each request
    curl "api_endpoint_here"
      -H "Authorization: Token token=myapitoken"
    

    Make sure to replace myapitoken with your API key.

    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"

    Users

    Get All Users

    curl "https://safetysystem.abusepreventionsystems.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]",
          "external_id": "111",
          "score": 80,
          "complete_date": "2016-08-17T17:07:07.292Z",
          "user_type": "employee",
          "direct_login_url": "https://safetysystem.abusepreventionsystems.com/trainings/quiz?t=jds95h2lslf92nl4klsd02n3",
          "tags": [
              "Tag-1",
              "Tag-2",
              "Tag-3"
          ]
        },
        {
          "id": 139,
          "first_name": "John",
          "last_name": "Doe",
          "email": "[email protected]",
          "external_id":"123",
          "score": 100,
          "complete_date": "2016-08-03T01:59:32.622Z",
          "user_type": "volunteer",
          "direct_login_url": "https://safetysystem.abusepreventionsystems.com/trainings/quiz?t=jds95h2j4labhHH4klsd02n3",
          "tags": [
              "Tag-4",
              "Tag-5"
          ]
        }
      ]
    

    Retrieves a list of users. Users will be returned up to 100 at a time. This endpoint supports paging. 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.abusepreventionsystems.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 String. Only users having this tag will be returned

    Get a User

    curl "https://safetysystem.abusepreventionsystems.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]",
      "external_id": "111",
      "score": 80,
      "complete_date": "2016-08-17T17:07:07.292Z",
      "user_type": "employee",
      "direct_login_url": "https://safetysystem.abusepreventionsystems.com/trainings/quiz?t=jds95h2lslf92nl4klsd02n3",
      "tags": [
          "Tag-1",
          "Tag-2"
      ]
    }
    

    This endpoint retrieves a specific user.

    HTTP Request

    GET https://safetysystem.abusepreventionsystems.com/api/v2/users/<ID>

    URL Parameters

    Parameter Description
    ID The ID of the user to retrieve

    Create a User

    curl "https://safetysystem.abusepreventionsystems.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",
      "user_type": "employee",
      "direct_login_url": "https://safetysystem.ministrysafe.com/trainings/quiz?t=7671cf713e382812b749dbed2aa52f438ffc815f278a6c41",
      "external_id": "123",
      "tags": []
    

    Example Error Response:

      "errors": {
        "first_name": ["You must provide a first name"],
        "last_name": ["You must provide a last name"]
      }
    

    This endpoint creates a new user.

    HTTP Request

    POST https://safetysystem.abusepreventionsystems.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
    email Yes The user's email address
    user_type No ['employee', 'volunteer']
    external_id No You can optionally assign a user an ID for use in integration with your own system

    Update a User

    curl "https://safetysystem.abusepreventionsystems.com/api/v2/users/1"
      -X PUT
      -H "Authorization: Token token=myapitoken"
      -d "user[first_name]=Tim"
    

    Example Success Response:

      "id": 1,
      "first_name": "Tim",
      "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",
      "tags": [
          "Tag-1",
          "Tag-2"
      ]
    

    Example Error Response:

      "errors": {
        "first_name": ["You must provide a first name"],
        "last_name": ["You must provide a last name"]
      }
    

    HTTP Request

    This endpoint updates a user.

    PUT https://safetysystem.abusepreventionsystems.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
    email No New user's email
    tag_list No Nw user's tag list

    Deactivate a User

    curl "https://safetysystem.abusepreventionsystems.com/api/v2/users/2"
      -X DELETE
      -H "Authorization: Token token=myapitoken"
    
      No Content Body
    

    This endpoint deletes a specific user.

    HTTP Request

    DELETE https://safetysystem.abusepreventionsystems.com/api/v2/users/<ID>

    URL Parameters

    Parameter Description
    ID The ID of the user to delete

    Trainings

    Get All Trainings for a User

    curl "https://safetysystem.abusepreventionsystems.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": "employee-id",
            "first_name": "John",
            "last_name": "Sawyer"
        }
      }
    

    Retrieves all trainings that have been assigned to a user.

    HTTP Request

    GET https://safetysystem.abusepreventionsystems.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

    Assign a training to a User

    curl "https://safetysystem.abusepreventionsystems.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": "employee-id",
          "first_name": "John",
          "last_name": "Sawyer"
      }
    

    Example Error Response:

      { "message": "Invalid survey code" }
    

    Assigns the specified training to a user.

    HTTP Request

    POST https://safetysystem.abusepreventionsystems.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 will be automatically sent to the trainee (default is false)

    Survey Types

    code description
    standard our standard 2021 Sexual Abuse Awareness Training
    youth our Youth Sports Sexual Abuse Awareness Training
    camp our Camp-Focused Sexual Abuse Awareness Training
    spanish our Spanish Sexual Abuse Awareness Training
    daycare our Daycare-Focused Sexual Abuse Awareness Training
    education our Education-Focused Sexual Abuse Awareness Training
    youth_ministry our Youth Ministry Sexual Abuse Awareness Training
    skillful_screening our Skillful Screening Training
    parent_training our Parent Training
    california the training specifically including the new California legal requirements
    peer_to_peer_training our Peer-to-Peer Sexual Abuse Training
    harassment our Preventing Sexual Harassment Training

    Resend a training

    curl "https://safetysystem.abusepreventionsystems.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" }
    

    Resends the specified training to a user.

    HTTP Request

    POST https://safetysystem.abusepreventionsystems.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

    Get All Trainings

    curl "https://safetysystem.abusepreventionsystems.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": "employee-id",
          "first_name": "John",
          "last_name": "Doe"
        }
      }
    

    Retrieves all trainings that have been assigned to users in the organization.

    HTTP Request

    GET https://safetysystem.abusepreventionsystems.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)

    Background Checks

    Get All Background Checks

    curl "https://safetsystem.abusepreventionsystems.com/api/v2/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",
          "applicant_interface_url": "http://theresults.com/form-for-applicant-to-complete",
          "results_url": "http://theresults.com/unique-results-link",
          "user_id": 2121,
          "level": 3
        },
        {
          "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": 2132,
          "level": 1
        }
      ]
    

    Retrieves a list of background checks for your organization. Background Checks will be returned up to 100 at a time. This endpoint supports paging. The default page is 1. To retrieve the next hundred users, change the page param to 2, 3, 4 etc.

    HTTP Request

    GET https://safetsystem.abusepreventionsystems.com/api/v2/background_checks

    Query Parameters

    Parameter Default Description
    page 1 the page of background_checks that will be returned
    start_date The starting date to filter background checks that were assigned on or after
    end_date The ending date to filter background checks that were assigned on or before

    Get a Background Check

    curl "https://safetsystem.abusepreventionsystems.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",
      "applicant_interface_url": "http://theresults.com/form-for-applicant-to-complete",
      "results_url": "http://theresults.com/unique-results-link",
      "user_id": 2121,
      "level": 3
    }
    

    This endpoint retrieves a specific background check record.

    HTTP Request

    GET https://safetsystem.abusepreventionsystems.com/api/v2/background_checks/<ID>

    URL Parameters

    Parameter Description
    ID The ID of the background check to retrieve

    Create a Background Check

    curl "https://safetsystem.abusepreventionsystems.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"]
      }
    

    This endpoint creates a new background check.

    HTTP Request

    POST https://safetsystem.abusepreventionsystems.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 their details. If false, all the applicant's information is required to 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 zipcode 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*** the two letter code of the applicant's drivers license state
    email 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 Whether the applicant is over 13 years of age
    employee_type No string ['current', 'prospective']

    * 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

    Archive a Background Check

    curl "https://safetsystem.abusepreventionsystems.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" }
    

    This endpoint archives a background check.

    HTTP Request

    PUT https://safetsystem.abusepreventionsystems.com/api/v2/background_checks/<ID>/archive

    URL Parameters

    Parameter Description
    ID The ID of the background check to archive

    Get Available Levels

    curl "https://safetsystem.abusepreventionsystems.com/api/v2/background_checks/available_levels"
      -X GET
      -H "Authorization: Token token=myapitoken"
    

    Example Success Response:

      [1, 2, 3, 4, 5, 6, 7]
    

    Each organization could have different levels that are available to their users. This endpoint returns the background check levels that are available to order on a user.

    HTTP Request

    GET https://safetsystem.abusepreventionsystems.com/api/v2/available_levels

    Tags

    Get All Tags

    curl "https://safetsystem.abusepreventionsystems.com/api/v2/tags"
      -H "Authorization: Token token=myapitoken"
    

    The command above returns JSON structured like this:

      [
        {
          "name": "Tag A"
        },
        {
          "name": "Tag B"
        }
      ]
    

    Retrieves a list of tags of your organization. Tags will be returned up to 100 at a time. This endpoint supports paging. The default page is 1. To retrieve the next hundred tags, change the page param to 2, 3, 4 etc.

    HTTP Request

    GET https://safetsystem.abusepreventionsystems.com/api/v2/tags

    Query Parameters

    Parameter Default Description
    page 1 the page of tags that will be returned

    Webhooks

    Quizzes

    Implementation

    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.abusepreventionsystems.com/path/to/certificate"
      }
    

    Webhooks are triggered upon successful completion of a training by a user, and can be configured in your developer console.

    If webhooks are enabled, when a trainee completes a quiz, we send a http POST request to the URLs you choose to specify.

    Background checks

    Implementation

    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",
      }
    

    Webhooks are triggered when the background check is ready to be reviewed, and can be configured in your developer console.

    If webhooks are enabled, when a background check is ready, we send a http POST request to the URLs you choose to specify.

    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.