Get Started

The HelloFlex APIs are HTTP-based RESTful APIs that use OAuth 2.0 for authorization. API request and response bodies are formatted in JSON.

Important: You cannot run the sample requests in this guide as-is. Replace call-specific parameters such as tokens and IDs with your own values.

Authentication and authorization

The HelloFlex REST API uses the OAuth 2.0 protocol to authorize calls. OAuth is an open standard that many companies use to provide secure access to protected resources.

When you create an app, HelloFlex generates a set of OAuth client ID and secret credentials for your app for requested environment. For more details please check to API User management documentation. You pass these credentials in the Authorization header in a get access token request.

In exchange for these credentials, the HelloFlex authorization server issues access tokens called bearer tokens that you use for authorization when you make REST API requests. A bearer token enables you to complete actions on behalf of, and with the approval of, the resource owner.

The access_token field in the get access token response contains a bearer token, indicated by the token_type of Bearer:

	"access_token": "<Access-Token>",
	"token_type": "Bearer",
	"expires_in": 3599

Include this bearer token in API requests in the Authorization header with the Bearer authentication scheme.

This sample request uses a bearer token to list news for a customer:

curl -X GET \
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer <Access-Token>' \

Access tokens have a finite lifetime. The expires_in field in the get access token response indicates the lifetime, in seconds, of the access token. For example, an expiry value of 3600 indicates that the access token expires in one hour from the time the response was generated.

To detect when an access token expires, write code to either:

  • Keep track of the expires_in value in the token response. The value is expressed in seconds.
  • Handle the HTTP 401 Unauthorized status code. The API endpoint issues this status code when it detects an expired token.

Before you create another token, re-use the access token until it expires.

API requests

To construct a REST API request, combine these components:

Component Description
The HTTP method
  • GET. Requests data from a resource.
  • POST. Submits data to a resource to process.
  • PUT. Updates a resource.
  • PATCH. Partially updates a resource.
  • DELETE. Deletes a resource.
The URL to the API service
  • Sandbox https://api.uat-helloflex.com.
  • Live https://api.helloflex.com.
The URI to the resource The resource to query, submit data to, update, or delete. For example, domainTypes/7/domainValues.
Query parameters Optional. Use to filter, limit the size of the data in an API response.
HTTP request headers Includes the Authorization header with the access token.
A JSON request body Required for most POST, PUT, and PATCH calls.

API responses

HelloFlex API calls return JSON response bodies that include information about the resource.

HTTP status codes

Each REST API request returns a success or error HTTP status code.


In the responses, HelloFlex returns these HTTP status codes for successful requests:

Status code Description
200 OK The request succeeded.
201 Created A POST method successfully created a resource. If the resource was already created by a previous execution of the same method, for example, the server returns the HTTP 200 OK status code.
204 No Content The server successfully executed the method but returns no response body.


In the responses for failed requests, HelloFlex returns HTTP 4XX or 5XX status codes.

In the responses, HelloFlex returns these HTTP status codes for failed requests:

Status code Cause
400 Bad Request The server could not understand the request.
401 Unauthorized The request requires authentication and the caller did not provide valid credentials.
403 Forbidden The client is not authorized to access this resource although it might have valid credentials.
404 Not Found The server did not find anything that matches the request URI. Either the URI is incorrect or the resource is not available.
405 Method Not Allowed The service does not support the requested HTTP method.
406 Not Acceptable The server cannot use the client-request media type to return the response payload.
415 Unsupported Media Type The API cannot process the media type of the request payload.
500 Internal Server Error A system or application error occurred. Although the client appears to provide a correct request, something unexpected occurred on the server.

Validation errors

For validation errors, HelloFlex returns the HTTP 400 Bad Request status code.

Sample of validation response:

	"Id": ["Value -1 is invalid."],
	"Lang": ["Should be valid ISO 639-1 language code."]

Make your first call

To make REST API calls, you need to get an access token.

1. Create a HelloFlex API client.
When you create an API client, HelloFlex generates a set of OAuth credentials.
2. Get an access token.
Pass the OAuth credentials in a get access token call.
In response, the HelloFlex authorization server issues an access token.
3. Make REST API calls.
Use the access token for authentication when you make REST API calls.

Get an access token

The get access token endpoint is /oauth2/token.

To get an access token, you pass your OAuth credentials in a get access token call. To make this call, you can use either cURL on the command line or the Postman app.

In response, the HelloFlex authorization server issues an access token.

Re-use the access token until it expires. When it expires, you can get a new token.

cURL example


  • If you use Windows, use a Bash shell to make cURL calls.
  • If you use a command-line tool other than cURL, set content-type to application/x-www-form-urlencoded.
  1. Download cURL for your environment.

  2. From the command line, run this command:

    curl -X POST \
    	-H "Accept: application/json" \
    	-d "client_id=<client_id>" \
    	-d "client_secret=<secret>" \
    	-d "grant_type=client_credentials" \
    	<token endpoint>


    <token endpoint> The get access token endpoint.
    <client_id> Your client ID.
    <secret> Your secret.
    grant_type The grant type. Set to client_credentials.
  3. View the sample response.

Postman example

  1. Download the latest version of Postman for your environment, and open Postman.

  2. Select the POST method.

  3. Enter the https://api.uat-helloflex.com/oauth2/token request URL.

  4. On the Body tab, select x-www-form-urlencoded and enter this information:

    Key Value
    grant_type client_credentials
    client_id Your client ID.
    client_secret Your secret.
  5. Click Send.

  6. View the sample response.

Sample response

	"access_token": "<Access-Token>",
	"token_type": "Bearer",
	"expires_in": 3599


access_token Your access token.
expires_in The number of seconds after which the token expires. Request another token when the current one expires.
token_type The token type.

Make REST API calls

With a valid access token, you can make REST API calls.

Add Authorization request header with value "Bearer <Access-Token>" where <Access-Token> is your access token.

This sample call returns public news and uses only the required input parameters. The access token in the call is an OAuth bearer token.

curl -X GET \
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer <Access-Token>' \

A successful call returns a JSON-formatted response body with public news.