SAFE Swift API

This article is designed to show you the workflow for SAFE Application API. Below the diagram you will find the high-level steps to work with API.

Refer to our SAFE API reference documentation for more details.

Workflow using swimlane

Workflow in steps

Our APIs use the OAuth2.0 Client Credentials workflow. See the steps below:

For /ProcessFatigue

1. Generate Bearer Token.

   • the <your_client_secret> is URL encoded. You can use urlencoder.org to URL encode the client secret.
   • the <your_client_id>:<your_url_encoded_client_secret> string is base64 encoded
   • the content-type is x-www-form-urlencoded
   • the grant-type is client_credentials

   • the scope is frmsc_fast_safe_api

     Manually encoding?

     Use base64encode.org to encode or decode the string of <Your_ClientID>:<Your_URL_Encoded_ClientSecret>.

     Before encodingAfter encodingExample of Authorization header value

     5471E010-DDEE-4C98-FF8F-08DB2245E373:7rg6Gt+hUiobtXI9Jb37z2vtrhw1CEgDkwFZcMbN5Yc=
     

     NTQ3MUUwMTAtRERFRS00Qzk4LUZGOEYtMDhEQjIyNDVFMzczOjdyZzZHdCtoVWlvYnRYSTlKYjM3ejJ2dHJodzFDRWdEa3dGWmNNYk41WWM9
     

     Basic NTQ3MUUwMTAtRERFRS00Qzk4LUZGOEYtMDhEQjIyNDVFMzczOjdyZzZHdCtoVWlvYnRYSTlKYjM3ejJ2dHJodzFDRWdEa3dGWmNNYk41WWM9
     

2. Use the generated token for Bearer authorization in the /ProcessFatigue endpoint to generate a fatigue scores from the roster data you sent. Ensure:

   • the mandatory fields are filled.
   • the RosterData field is populated in the correct order.
     
     
3. If you get errors instead of fatigue scores, read the error carefully and resolve the payload errors.
   
   
4. If you get expected results, retry sending the request to this endpoint by setting a different scale against PreferredScale property of the payload.

For /ProcessFatigueRisk

1. Generate Bearer Token.

   • the <your_client_secret> is URL encoded. You can use urlencoder.org to URL encode the client secret.
   • the <your_client_id>:<your_url_encoded_client_secret> string is base64 encoded
   • the content-type is x-www-form-urlencoded
   • the grant-type is client_credentials

   • the scope is frmsc_fast_safe_risk_api

     Manually encoding?

     Use base64encode.org to encode or decode the string of <Your_ClientID>:<Your_URL_Encoded_ClientSecret>.

     Before encodingAfter encodingExample of Authorization header value

     5471E010-DDEE-4C98-FF8F-08DB2245E373:7rg6Gt+hUiobtXI9Jb37z2vtrhw1CEgDkwFZcMbN5Yc=
     

     NTQ3MUUwMTAtRERFRS00Qzk4LUZGOEYtMDhEQjIyNDVFMzczOjdyZzZHdCtoVWlvYnRYSTlKYjM3ejJ2dHJodzFDRWdEa3dGWmNNYk41WWM9
     

     Basic NTQ3MUUwMTAtRERFRS00Qzk4LUZGOEYtMDhEQjIyNDVFMzczOjdyZzZHdCtoVWlvYnRYSTlKYjM3ejJ2dHJodzFDRWdEa3dGWmNNYk41WWM9
     

2. Use the generated token for Bearer authorization in the /ProcessFatigueRisk endpoint to generate a fatigue and risk scores from the roster data you sent. Ensure:

   • the mandatory fields are filled.
   • the RosterData field is populated in the correct order.
     
     
3. If you get errors instead of fatigue and risk scores, read the error carefully and resolve the payload errors.
   
   
4. If you get expected results, retry sending the request to this endpoint by setting a different scale against PreferredScale property of the payload.

Payload

Request payload

The request payload is the same for both endpoints. See our API reference documentation for more information.

Schema

Example

{
    "RosterData": "Reference,OnDutyDate,OnDutyTime,StartAirport,OffDutyDate,OffDutyTime,EndAirport,HomeBase,TimeReference\r\nPilot1,12/05/2023,19:45,SNA,13/05/2023,04:07,RSW,SNA,2\r\nPilot1,13/05/2022,00:01,RSW,13/05/2022,20:05,SNA,SNA,2",
    "SleepData": [
        {
        "ScheduleName": "Pilot 1",
        "SleepStart": "2023-01-02T19:57:00Z",
        "SleepEnd": "2023-01-02T20:30:00Z"
        }
    ],
    "DateFormat": "dmy",
    "PreferredScale": "SP"
}

Response payload

See below for an example. See our API reference documentation or Results breakdown for more information.

For Fatigue Scores

{
    "scheduleScores": [
        {
            "schedule": "Pilot1",
            "fatigueScores": [
                5.146,
                5.026,
                4.943,
                4.885,
                4.809,
                4.782,
                4.757,
                4.683,
                4.655,
                4.624,
                ...
            ]
        }
    ],
    "errors": []
}

For Fatigue Risk Scores

{
  "schedule": "Pilot 1",
  "fatigueScores": [
    3.402,
    3.42,
    3.445,
    3.475,
    3.507,
    3.54,
    3.574,
    3.606,
    3.638,
    3.668,
    3.696,
    3.722,
    3.746,
    3.768,
    3.787,
    3.804,
    3.819,
    3.831,
    3.839,
    3.847,
    3.852,
    "..."
  ],
  "riskScores": [
    12.7382,
    16.520624336581236
  ]
}

Results breakdown

Each comma-separated number under fatigueScores property indicates the fatigue score (based on the scale you chose) at 15-minute intervals. The interval list is based on duty start and end times. Compare the score against the description of the scale given in Fatigue and Risk Scales.

Risk scores are part of our proprietary solution, and we will train you to read those scores during the onboarding process. On a high-level, the Risk scores are dependent on the number of duties per each employee. If the roster data had two duties for an employee, there would be 2 risk scores for that employee. You can learn more about Risk Scales in Fatigue and Risk Scales.