Before diving into the steps outlined in this Getting Started guide, you may want to visit the General page for an overview of the WorkN APIs.

This getting started guide will help you make your first request to the WorkN APIs. Follow the steps below to start calling the API:

Get access to the WorkN APIs. Obtain your access token. Authorize your request. Submit an example request and review a response.

Step 1: Get Access to WorkN APIs

To use WorkN APIs, an API user must be created. The API user is always created in WorkN for each marketplace upon its creation. Once the API user is created, necessary credentials are provided in a secure manner.

Required Credentials

To make calls to WorkN APIs listed on this website, you will use the following credentials provided by WorkN:

• Username: The API user's username. Use it to make a Log In call to obtain a user access token.
• Password: The API user's password. Use it to make a Log In call to obtain a user access token.

After obtaining access to WorkN APIs and receiving the credentials, you can proceed to obtain an access token.

Step 2: Optain your access token

Every request to WorkN APIs must be authenticated using an access token, a unique string of characters used to authenticate and authorize API requests. Typically, this token is included in the Authorization header of HTTP requests to provide access to protected resources.

To obtain a valid token for all subsequent authenticated calls, the initial request you make is a POST call to the Log In endpoint, providing the required information. The call must be made for an API User that has been configured and granted permissions to make API calls within the system.

Request

POST https://prod1.serveture.com/public-api/user_login/

Request Headers

The following table describes each parameter that must be included in the request header.

Request Body

The following table describes each parameter in the request body.

Example Request

{
  "method": "POST",
  "url": "http://prod1.serveture.com/public-api/user_login/",
  "headers": {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Token <place token returned from Login endpoint here>"
    },
  "body": {
    "username": "string",
    "password": "string"
  }
}

Example Response

{
  "success": true,
  "message": "Successful Call!",
  "token": "8ebd63e6c7381ab4368dbbe400h9374c544aeed8"
}

⚠️

The example response above provides a shortened version of the response code. In addition to the token, upon successful authorization, you will always receive additional information about the marketplace your API user is authorized for (market_place_info), including lists of enterprises (enterprise_list) and branches (branch_list). For details, check the Log In endpoint documentation.

Response Definitions

The following table describes each item in the example response.

Step 3: Authorize your request

Once you've obtained an access token, you can authorize the request.

⚠️

Every API call to WorkN APIs will require specifying an authorization header.

Request Authorization

To authorize a request, include the access token obtained in the previous step in the Authorization header of your request. When adding the Authorization header to your requests, add the following key-value pair:

⚠️

Make sure you format the value of the token as follows: the word "Token" followed by a space and your token returned from Log In endpoint.

Step 4: Submit a request and review a response

Before you can call any other endpoints, let’s make a call to retrieve a list of attributes. This call provides essential information about the specific realm's configuration, enabling you to understand its structure and proceed with making further API requests.

Request

POST http://prod1.serveture.com/public-api/list_attributes

Request Headers

The following table describes each parameter that must be included in the request header.

Request Body

The following table describes each parameter in the request body.

Example Request

The following request retrieves a list of attributes for the Worker Registration realm.

{
  "method": "POST",
  "url": "http://prod1.serveture.com/public-api/user_login/",
  "headers": {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Token <place token returned from Login endpoint here>"
  },
  "body": {
    "realm_list": [
      1
    ],
    "user_id": 0,
    "enterprise_id": 0
  }
}

Example Response

The following response provides an example of a list of attributes for the Worker Registration realm. It contains attributes of the text and password types.

{
    "message": "Success!",
    "attrib_list": [
        {
            "display_name": "First Name",
            "name": "first_name",
            "default_text": "",
            "max_length": 50,
            "attrib_id": 14,
            "realm": 1,
            "type": "text",
            "order": 6,
            "type_flags": {
                "read_only": false,
                "required": true,
                "type": 0,
                "display": true
            }
        },
        {
            "display_name": "Password",
            "name": "password",
            "default_text": "",
            "max_length": 50,
            "attrib_id": 13,
            "realm": 1,
            "type": "password",
            "order": 3,
            "type_flags": {
                "read_only": false,
                "required": true,
                "type": 0,
                "display": true
            }
        }
    ],
    "success": true
}

Response Definitions

Error Codes

This guide demonstrated how you can make a call to the Get Attribute List endpoint to get a list of attributes for a specific realm. Now, using that data, you can browse the API Reference documentation and explore calls to other WorkN endpoints.