API docs by Redocly

Shyft Integration API (1.0.0)

Download OpenAPI specification:

Welcome to the Shyft API!

Shyft Integration API is designed for helping data integration between Shyft and Shyft partners' systems. It provides a real time, two-way data synchronization solution.

Shyft Integration API can perform differently based on customer's configuration and requirements.

NOTES:

  • In parameters section, the letter R stands for Required.
  • All API examples show only essential data set.

Authentication

API keys are required to access Shyft integration APIs. Please contact Shyft's sales team if you do not have one.

API keys should be attached in API headers with key/value format listed below:

Header Value
X-Api-Key {{api_key}}
X-Api-Uuid {{api_uuid}}

Global Information

Global information are applicable for all APIs with same categories.

Headers

Name Values R Description
Version 6_0_0 * Version number. Ex: 6_0_0
Content-Type application/json *

API Response

Please ignore these attributes in API response, it is used by Shyft. 

"_associations_removed": true,
"_parent_object_id": null,

Success Codes

Success Code Meaning
200 Created -- Objet created.
201 Unauthorized -- Your API key is wrong.
204 No Content -- Success without returning resource.

Error Codes

Error Code Meaning
400 Bad Request -- Your is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The records requested is hidden for administrators only.
404 Not Found -- The specified record could not be found.
405 Method Not Allowed -- You tried to access a record with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The record requested has been removed from our servers.
422 Unprocessable Entity -- Invalid input data.
429 Too Many Requests -- You're requesting too many requests! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
502 Bad Gateway --
504 Gateway Timeout --
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Error Response Formats

422

{
    "errors": {
        "base": [
            "a private session for same two users already exists: 3034"
        ]
    }
}

422

{
    "errors": {
        "google_map_id": [
            "can't be blank"
        ],
        "time_zone": [
            "can't be blank"
        ],
        "longitude": [
            "can't be blank"
        ]
    }
}

404

{
    "errors": {
        "not_found": [
            "Couldn't find Post"
        ]
    }
}

500

{
    "errors": {
        "internal_server_error": [
            "Invalid nil value"
        ]
    }
}

Integration

Here are all APIs for data integration.

Integration > users

User Privilege stands for the connection between user and location.

Each user can be associated with many different locations, and each location can have many different users.

remove user privileges

Description

Remove specific user from the locations within your organization.

Path Params

Param Values R Description
internal_id employee ID * The global unique employee ID in your organization

Input

Attribute Values R Description
path Parameters
internal_id
required
string
query Parameters
string
header Parameters
X-Api-Key
string
Example: {{api_key}}
X-Api-Uuid
string
Example: {{api_uuid}}

Responses

Response samples

Content type
application/json
{ }

Integration > shifts

Shifts stands for the schedules already assigned to employees or need to be covered(open shifts).

bulk upsync shifts

Description

Synchronize multiple shifts (create, update, delete)

  • This API can import existing users' shifts.

  • This API can update existing shifts' changes.

  • This API can remove existing shifts.

  • This API can update existing shift or create it if not created yet.

  • With async_mode=false, the server will process the data immediately and return the processed data. It should only be used for small amount of data.

  • With async_mode=true, the server will process the data in background and return a job ID. The job processing result can be pulled by calling Action Job API.

Input

  • System prefer time format having zone attached (better be UTC) like 2018-04-01 09:00:00 UTC. Otherwise it will be treated as shift location 's local time in case like 2018-04-01 09:00:00.
Attribute Values R Description
_record_action create| update| delete| update_or_create * For update_or_create, it will update existing shift or create it if not found
shift_reference_id * Shift's global unique ID from partner's system
employee_id * Employee assigned to this shift. Not supply it for open shift
start_at * Shift's start time.
end_at * Shift's end time.
site_reference_id * Shift location's global unique ID from partner's system.
segments Sub Array If there are segments
segment_reference_id Segment's global unique ID
start_at Segment start time.
start_at Segment end time.
job_code Segment job code
department_code Segment department code
query Parameters
async_mode
boolean
Example: async_mode=true
header Parameters
X-Api-Key
string
Example: {{api_key}}
X-Api-Uuid
string
Example: {{api_uuid}}
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "shifts": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "shifts": [
    ]
}

Integration > action_jobs

get an action job status

Description

Get the job status by giving a action_job ID.

It will return the result of Job processed at background. For example, the API result for a bulk_upsync API called with async_mode=true

Path Params

Attribute Values R Description
action_job_id * The action_job ID got from other API called under async_mode=true

Input

Attribute Values R Description
path Parameters
action_job_id
required
string
header Parameters
X-Api-Key
string
Example: {{api_key}}
X-Api-Uuid
string
Example: {{api_uuid}}

Responses

Response samples

Content type
application/json
Example
{
  • "action_job": {
    }
}

Integration > employees

You can skip this section if your system is not using Shyft hosted SSO page.

bulk upsync employees

Description

Synchronize multiple employees (create, update, delete)

  • With async_mode=false, the server will process the data immediately and return the processed data. It should only be used for small amount of data.

  • With async_mode=true, the server will process the data in background and return a job ID. The job processing result can be pulled by calling Action Job API.

Input

Attribute Values R Description
query Parameters
async_mode
boolean
Example: async_mode=true
api_default_record_action
string
Example: api_default_record_action=update_or_create
header Parameters
X-Api-Key
string
Example: {{api_key}}
X-Api-Uuid
string
Example: {{api_uuid}}
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "employees": [
    ]
}