The Okati Employee data API is used by vendor partners who need to read Okati employee data.

This guide provides an overview of the methods in the API plus examples showing how to use them. The guide is divided into the following sections:

• Working with this API – A technical overview of the API and its features
• API Reference – Summary of the API methods and how to call them
• Workflows – Examples showing API method usage
• Payload Details – Descriptions of the payloads used by the API

This API searches for and retrieves Okati employee data by employee ID or by SSO/IDP identifier.

This API supports the following use case that you can add to your business workflows:

• Use the GET /employees to search Okati employee data by employee ID.
• Use the POST /employees/by-idp-identifier to search Okati employee data by Single Sign-On (SSO)/(Identity Provider) IDP Identifier.

This is a RESTful API where you structure requests to the service with the following components:

• Method – The signature of an API method is comprised of an HTTP method (or verb) plus a URL pointing to the resource targeted by the request.
• HTTP headers – All methods require the headers described in the API Reference.
• Request body – Where required, format a method’s request body in JSON.

A method in the API is comprised of an HTTP method (such as GET) plus a URL that points to the resource being acted upon. The signature of a method is roughly outlined below:
Method Signature = HTTP Method + URL of resource
{httpMethod} https://{serviceHost}/{servicePath}/{endpointPath}

For details on configuring these components in the requests you make to the service, see the API Reference.

You must have a Fortellis Developer Network account before you can make requests to this API. Once you have an account, sign in to the Developer Network and register an app that uses this API. When you register an app, Fortellis assigns a set of authorization credentials and a Subscription ID to the app. Use these values to make requests to the API service.

Tip: For details on getting started with the Fortellis platform and making calls to Fortellis APIs, see Getting Started.

---

This API Reference gives an overview of the methods in the API and describes how to make requests to Okati Employee Data API.

This table outlines all the public methods in the API. The table abbreviates the method URLs. To complete each,prepend the endpoint with the API’s service URL (described below). Method Names give unique names to each API method and are used throughout the guide. See the Workflows section for examples that show how to use these methods.

HTTP Method + Endpoint	Method Name / Description
GET / employees	/employees Retrieve the Okati employee data by employeeId
POST / employees/by-idp-identifier	/by-idp-identifier Retrieve the Okati employee data by by-idp-identifier

Note: The API Specification is an OpenAPI file that acts as the contract between the API Publisher and the API user. Always refer to the declarations in the API specification in API Directory as the authoritative definition of the API.

All method URLs in this API use the following service URL, which is a combination of the host followed by the organization namespace and service base path:

Test:
https://api.fortellis.io/Okati-test/private/Okati/v1/employees/{employeeId}
https://api.fortellis.io/Okati-test/private/Okati/v1/employees/by-idp-identifier

Production:
https://api.fortellis.io/Okati/private/Okati/v1/employees/{employeeId}
https://api.fortellis.io/Okati/private/Okati/v1/employees/by-idp-identifier

In addition to the standard set of HTTP headers used to make a REST API request, all methods in this API use the following set of headers:

HTTP Header	Description
Subscription-Id	REQUIRED - A valid Subscription ID assigned to the user of the app making the request. App Publishers can retrieve the Subscription-Id values for the users of their app programmatically, and through the app’s Subscription Report on Developer Network.
Authorization	REQUIRED - This header provides the authorization needed to make requests to the API. Call the Fortellis identity server using the client credentials flow to create an OAuth 2.0 access token. Set the value of this header to the word “Bearer” followed by a space and a valid access token. Example: "Authorization: Bearer "
Request-Id	REQUIRED - A client-supplied universally unique identifier (UUID) string value that is unique for each request. This value is returned in the response so you can correlate the response to the request.
Accept	For GET requests - Indicates the content type(s) the client understands, expressed as MIME types. Set: "Accept: application/json"
Content-Type	For POST requests - Indicates the media type of the resource or data being sent by the client. Set: "Content-Type: application/json"

This API requires you to pass a Fortellis OAuth access token in the Authorization header of each request made to the service. Use the Client Credentials Flow to generate a Bearer token using the credentials assigned to your Fortellis app. For more, see Authorization on Fortellis.

Fortellis APIs issue required HTTP status and error codes as outlined in RFC 7231. If an error occurs during processing, the service returns an errorCode and a message associated with the error. Use the following tips to help troubleshoot errors.

Code	Message	Description
200	OK	The request was successfully received and processed.
204	No Content	The request was successfully processed, but there is no content to return in the response.
401	Unauthorized	Access token is expired or invalid This error indicates there is a problem with the authorization of the API request. Check the response payload for more information.
403	Forbidden	This error indicates there is likely a problem with the authorization of the API request. Check the response payload for more information.
500	Internal Server Error	An error occurred when the API server was processing your request. Wait a bit and retry the request. If the problem persists, contact API Support as listed in API Directory.

---

The use cases outlined in the sections below describe how you might incorporate each method of this API into your Okati Drive business processes.

GET /employees searches and retrieves one or more Okati employee data records based on the path parameters, employeeId.

When you call GET /employees, supply a request payload with all the required attributes needed to retrieve Okati employee data plus any information you can add to populate the optional input attributes. The example below shows the writeable input parameters plus the headers needed to make the request.

URL Parameter	Type	Description
{employeeId}	path	REQUIRED- Id of the Okati employee.

// GET /employees/{employeeId} – request example:
curl -X GET " https://api.fortellis.io/Okati/private/Okati/v1/employees/{employeeId}"\
-H 'Authorization: Bearer <token>' \
-H 'Subscription-Id: <subscriptionId>' \
-H 'Request-Id: <requestId>'\
-H 'Accept: application/json'

When successful, GET /employees return the required responses from the path parameters along with other information. You should see your response body in the lower pane.

// GET /employees/{employeeId} – response example

{ "employeeId": "c47989bd-1a9e-486b-9137-aab901d43cb2",
"firstName": "Test",
"lastName": "Employee",
"isActive": true,
"isOff": false,
"idpIdentifier": "[email protected]",
"fromAddresses": [
{
"isDefault": true,
"address": "[email protected]",
"displayName": "TestEmployee"
} ]}

POST /employees/by-idp-identifier searches and retrieves one or more Okati employee data records based on the by-idp-identifier.

When you call POST /employees/by-idp-identifier, supply a request payload with all the required attributes needed to retrieve Okati employee data plus any information you can add to populate the optional input attributes. The example below shows the writeable input parameters plus the headers needed to make the request.

// POST /employees/by-idp-identifier – request example:
curl -X POST " https://api.fortellis.io/Okati/private/Okati/v1/employees/by-idp-identifier"\
-H 'Authorization: Bearer <token>' \
-H 'Subscription-Id: <subscriptionId>' \
-H 'Request-Id: <requestId>'\
-H 'Content-Type: application/json' \
-d '{"idpIdentifier": "[email protected]"}'

When successful, POST /employees/by-idp-identifier returns the required responses along with other information. You should see your response body in the lower pane.

// employees/by-idp-identifier – response example:
{ "employeeId": "c47989bd-1a9e-486b-9137-aab901d43cb2",
"firstName": "Test",
"lastName": "Employee",
"isActive": true,
"isOff": false,
"idpIdentifier": "[email protected]",
"fromAddresses": [
{
"isDefault": true,
"address": "[email protected]",
"displayName": "TestEmployee"
}]}

Okati Employee Data uses the attributes described below in its request and response payloads. ATTRIBUTE VALUES All payloads in this API are formatted in JSON. While not shown directly in the JSON examples, this API expects and returns specific data types in its attribute values. In attribute tables, Type lists the data type assigned to an attribute, coded as follows:

• str – A string value.
• int – An integer value.
• f.n – A float value with n number of digits.
• enum – A string value that uses a declared set of named constant values.
• bool – A Boolean flag with a value of true, false, or null.
• date – An ISO 8601 encoded date/time value. Example formats:
  • YYYY-MM-DD
  • YYYY-MM-DDThh:mm:ss-hh:ss
  • YYYY-MM-DDThh:mm:ss-hh:ssz
• time – an ISO 8601 encoded time value, for example: hh:mm:ss-hh.
• array – A list of elements.
• obj – An object type.
• uuid || guid – A 36-character universally unique identifier or globally unique identifier containing numbers, letters, and dashes.

Tip: All attributes are optional unless identified as being REQUIRED.

Attribute	Type	Description
employeeId	str	A unique identifier associated to the employee.
firstName	str	First name of the employee.
lastName	str	Last name of the employee.
isActive	bool	True/false whether the employee is active within the company.
isOff	bool	True/false whether this employee is currently working or not working (e.g., on leave or temporarily unavailable).
idpIdentifier	str	The identifier used for authentication via an Identity Provider (IDP) or Single Sign-On (SSO) system.
fromAddresses	array	An email address associated with the employee for sending email.
isDefault	bool	Flag to indicate if the employee email address is the default email sending from address.
address	str	The actual email address used for sending.
displayName	str	The name displays to recipients in their inbox when they receive an email from this address.

Attribute	Type	Description
data	obj	REQUIRED - Object that describes a Okati Employee.
employeeId	str	A unique identifier associated to the employee.
firstName	str	First name of the employee.
lastName	str	Last name of the employee.
isActive	bool	True/false whether the employee is active within the company.
isOff	bool	True/false whether this employee is currently working or not working (e.g., on leave or temporarily unavailable).
idpIdentifier	str	The identifier used for authentication via an Identity Provider (IDP) or Single Sign-On (SSO) system.
fromAddresses	array	An email address associated with the employee for sending email.
isDefault	bool	Flag to indicate if the employee email address is the default email sending from address.
address	str	The actual email address used for sending.
displayName	str	The name displays to recipients in their inbox when they receive an email from this address.

Document Version	Revision Date	Author	Comment
R01	TBD	R. Chowdhary	Initial Issuance v1