Back to top

envisionme.co.za - API

The envisionme.co.za API breakdown.

OAuth

The Login Flow:

  1. Checking login status
  2. Logging people in
  3. Confirming identity
  4. Storing access tokens and login status

Checking login status

Apps using our SDKs can check whether someone has already logged in using built-in functions. All other web apps must create their own way of storing when a person has logged in, and when that indicator is not there, proceed on the assumption that they are logged out. If someone is logged out, then your app should redirect them to the Login dialog at an appropriate time — for example if they click a login button.

Logging People In

Whether someone is not logged into your app or not logged into envisionme.co.za, you can use the Login dialog to prompt them to do both (SSO). If they aren’t logged into envisionme.co.za, they’ll be prompted to login and then move onto logging into your app. This is automatically detected, so you don’t need to do anything extra to enable this behavior.

Invoking the Login Dialog

Your app must initiate a redirect to an endpoint which will display the Login Dialog:

https://api.envisionme.co.za/oauth/authorize?
    client_id={app-id}
   &redirect_uri={redirect-uri}

Please see Authorize call for more information.

For server-side login, the code parameter is also an indicator that the person using it has already logged in. If it’s not present in the request data, the person needs to be redirected to the Login dialog. Note that redirecting someone who has already logged in to the Login dialog will immediately redirect them back to your app with the response_type included. Checking for the presence of the code parameter just makes the login flow more efficient.

response_type. Determines whether the response data included when the redirect back to the app occurs is in URL parameters or fragments. See the Confirming Identity section to choose which type your app should use. This can be one of:

  • code. Response data is included as URL parameters and contains code parameter (an encrypted string unique to each login request). This is the default behaviour if this parameter is not specified.

  • token. Response data is included as a URL fragment and contains an access token

Handling Login dialog response

At this point in the login flow, the person will see the Login dialog and will have a choice of whether to cancel or to let the app access their data.

If the person using the app chooses ALLOW on the Login dialog, they grant to your app.

In all cases, the browser returns to the app, and response data indicating whether someone connected or cancelled is included. When your app uses the redirect method as above, the redirect_uri your app returns to will be appended with URL parameters or fragments (as per the chosen response_type), which must be captured.

Because of the various combinations of code languages that could be used in web apps, our guide doesn’t show specific examples. However most modern languages will be capable of URL parsing, as follows:

Client-side JavaScript can capture URL fragments (for example jQuery BBQ), whereas URL parameters can be captured by both client-side and server-side code (for example $_GET in PHP, jQuery.deparam in jQuery BBQ, querystring.parse in Node.js or urlparse in Python).

Cancelled login

If people using your app don’t accept the Login dialog and clicks Cancel, they’ll be redirected to the following:

YOUR_REDIRECT_URI?error=access_denied

Confirming identity

Now that your app has authenticated and received the response from the Login dialog, it should perform a check to authenticate that the logged in person is the same person who began the login process.

Because the OAuth flow involves browsers being redirected to URLs in your app from the Login dialog, traffic could directly access this URL with made-up fragments or parameters. If your app assumed these were valid parameters, the made-up data would be used by your app for potentially malicious purposes. As a result, your app should confirm that the person using the app is the same person that you have response data for before generating an access token for them. Confirming identity is accomplished in different ways depending on the response_type received above:

  • When code is received, it has to be exchanged using an endpoint that can make this confirmation.

  • When token is received, it should be used to make an API call to an inspection endpoint that will indicate who the token was generated for and by which app.

Note that you can also generate your own state parameter and use it with your login request to provide CSRF protection.

Exchanging code for an access token

To get an access token, make an HTTP POST request to the following OAuth endpoint: POST https://api.envisionme.co.za/oauth/access_token

Please see Access Token for information.

The response you will receive from this endpoint, if successful, is:

access_token={access-token}&refresh_token=null

refresh_token is currently hardcoded to null but may be implemented in future to allow for expiration of access tokens.

If it is not successful, you’ll receive an explanatory error message.

Storing access tokens and login status

At this point in the flow, you have someone authenticated and logged in. Your app is ready to make API calls on their behalf. Before doing so, it should store the access token and the login status of the person using the app.

Storing access tokens

After your app receives the access token from the previous step, the token should be stored so it’s available to all parts of the app when it makes API calls. There is no specific process here, however in general it’s best to add the token as a session variable to identify that browser session with a particular person. Also, the app should store the token in a database along with the user_id to identify it.

Tracking login status

Again, your app should store a person’s login status, which helps during page to page navigation to avoid having to make additional calls to the Login dialog. Setting a session variable is the most common way to do this, but whatever procedure you chose, modify your login status checking to account for it.

Authorize

Kick of the authorization process.

Authorize
GET/oauth/authorize{?client_id,redirect_uri,state,response_type}

Parameters
HideShow
client_id
number (required) Example: 10

App/client ID as assigned by envisionme.co.za.

redirect_uri
string (required) Example: http://www.example.com/callback

The URL that you want to redirect the person logging in back to.

state
string (optional) Example: xyz123

An arbitrary unique string created by your app to guard against Cross-site Request Forgery.

response_type
string (optional) Example: code

Determines whether the response data included when the redirect back to the app occurs is in URL parameters or fragments. See the Confirming Identity section to choose which type your app should use.

Choices: code token

Response  200
Response  303
HideShow
Headers
Location: {redirect_uri}?code={code}

Access token

Exchanging code for an access token

Access token
POST/oauth/access_token{?client_id,redirect_uri,client_secret,code}

Parameters
HideShow
client_id
number (required) Example: 10

App/client ID as assigned by envisionme.co.za.

redirect_uri
string (required) Example: http://www.example.com/callback

The URL that you want to redirect the person logging in back to. This URL will capture the access token and store the token and the person’s login status.

client_secret
string (optional) Example: xyz123

Your unique app secret. This app secret should never be included in client-side code or in binaries that could be decompiled. It is extremely important that it remains completely secret as it is the core of the security of your app and all the people using it.

code
string (optional) Example: 123abcde123

The parameter received from the Login Dialog redirect above. Response

Response  303
HideShow
Headers
Location: {redirect_uri}?access_token={access-token}&refresh_token=null

Jobs

Jobs node API spec.

Job List

List all jobs

Get jobs
GET/job{?count,company_uid,limit,province,mxit,nids,search,status,skip,uid}

Parameters
HideShow
count
boolean (optional) Default: null Example: 10

Change into count query with true.

company_uid
number (optional) Example: 10

Retrieve jobs matching company UID.

limit
number (optional) Default: 10 Example: 10

The maximum number of items to be returned.

province
string (optional) Example: The Northern Cape

South African province for jobs.

Choices: The Eastern Cape The Free State Gauteng KwaZulu-Natal Limpopo Mpumalanga The Northern Cape North West The Western Cape

mxit
boolean (optional) Example: true

Whether this is a job for Mxit.

nids
string (optional) Example: {2,3,4}

Comma seperated list of nids encapsulated by {}.

search
string (optional) Example: test string

A search string for jobs.

skip
number (optional) Default: 0 Example: 10

The number of items to skip.

status
number (optional) Default: 0 Example: 1

Whether the jobs to be retrieved should be active or expired.

Choices: 0 1

uid
number (optional) Example: 10

Retrieve jobs matching user UID.

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
[
  {
    "nid": 1,
    "title": "ON HOLD Test Analyst",
    "searchable_title": "on hold test analyst",
    "status": 1,
    "reference": "79143",
    "type": "Permanent",
    "position": "Testing & QA (IT)",
    "created": "1455919200000",
    "uid": 2753,
    "company_uid": 2753,
    "author_name": "ACME Inc.",
    "company_logo": "sites/default/files/profile-images/2753-1384430330.jpg",
    "company_name": "Acme Professional Placement Group",
    "job_description": "You're currently a Test Analyst with over 5 years experience and looking for a new challenge. Wait no longer, one of my best clients is looking for your expertise in the analysis space focusing on defining automated test requirements during analysis phase of the project. Let's elevate your career to the next level. Bring your Degree/Diploma in IT coupled with an ISEB/ISTQB certifications. \r\nTravel required: 0%",
    "salary": 750000,
    "salary_currency": "ZAR",
    "salary_type": "Annual",
    "city": "Johannesburg North",
    "province_name": "Gauteng",
    "country_name": "South Africa"
  },
  {
    "nid": 2,
    "title": "TEST - Acme (DO NOT DELETE)",
    "searchable_title": "test - acme (do not delete)",
    "status": 1,
    "reference": "70586",
    "type": "Part time",
    "position": "Data Capturer",
    "created": "1454709600000",
    "uid": 2783,
    "company_uid": 2783,
    "author_name": "Acme Staffing Solutions",
    "company_logo": "sites/default/files/profile-images/2783-1362336674.png",
    "company_name": "Acme Staffing Solutions",
    "job_description": "TEST\r\nTravel required: 0%",
    "salary": 6000,
    "city": "Johannesburg Central",
    "province_name": "Gauteng",
    "country_name": "South Africa"
  }
]

Job

Single Job object

Retrieve a Job
GET/jobs/{nid}

Parameters
HideShow
nid
number (required) Example: 1
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "nid": 1,
  "title": "ON HOLD Test Analyst",
  "searchable_title": "on hold test analyst",
  "status": 1,
  "reference": "79143",
  "type": "Permanent",
  "position": "Testing & QA (IT)",
  "created": "1455919200000",
  "uid": 2753,
  "company_uid": 2753,
  "author_name": "Acme Professional Placement Group",
  "company_logo": "sites/default/files/profile-images/2753-1384430330.jpg",
  "company_name": "Acme Professional Placement Group",
  "job_description": "You're currently a Test Analyst with over 5 years experience and looking for a new challenge. Wait no longer, one of my best clients is looking for your expertise in the analysis space focusing on defining automated test requirements during analysis phase of the project. Let's elevate your career to the next level. Bring your Degree/Diploma in IT coupled with an ISEB/ISTQB certifications.  \r\nReason for opening: undefined\r\nTravel required: 0%",
  "salary": 750000,
  "salary_currency": "ZAR",
  "salary_type": "Annual",
  "city": "Johannesburg North",
  "province_name": "Gauteng",
  "country_name": "South Africa"
}

Terms

Term API spec.

Term List

List all terms

Get terms
GET/term{?q,vid,limit,skip,orderBy,asc}

Parameters
HideShow
q
string (required) Example: test string
vid
number (required) Example: 10

Choices: 33 31 10 24 27 19 12 25 14 13 7 28

limit
number (optional) Default: 10 Example: 5

The maximum number of items to be returned.

skip
number (optional) Default: 0 Example: 10

The number of items to skip.

orderBy
string (optional) Example: name

Order by value.

Choices: name tid

asc
boolean (optional) Example: true

Ascending true

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "hits": {
    "total": 25,
    "max_score": 4.8519278,
    "hits": [
      {
        "_index": "terms_v1",
        "_type": "term",
        "_id": "40929",
        "_score": 4.8519278,
        "_source": {
          "_id": 40929,
          "name": "Creating Test Plan",
          "synonyms": [
            "Creating Test Plans"
          ],
          "tid": 40929,
          "vid": 27
        }
      },
      {
        "_index": "terms_v1",
        "_type": "term",
        "_id": "20280",
        "_score": 1.4729428,
        "_source": {
          "_id": 20280,
          "name": "Test Management",
          "synonyms": [],
          "tid": 20280,
          "vid": 27
        }
      }
    ]
  }
}

Billing

Billing API spec.

Register Client

Register a new client on the billing server.

Register client
POST/register-client

Parameters
HideShow
client_id
string (required) Example: 1212

Application node nid.

first_name
string (required) Example: Peter

Company owner/contact person first name.

last_name
string (required) Example: Smith

Company owner/contact person last name.

company
string (required) Example: Envisionme Virtual Co. Pty Ltd

Legal company name.

email
string (required) Example: info@envisionme.co.za
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "hits": {
    "total": 25,
    "max_score": 4.8519278,
    "hits": [
      {
        "_index": "terms_v1",
        "_type": "term",
        "_id": "40929",
        "_score": 4.8519278,
        "_source": {
          "_id": 40929,
          "name": "Creating Test Plan",
          "synonyms": [
            "Creating Test Plans"
          ],
          "tid": 40929,
          "vid": 27
        }
      },
      {
        "_index": "terms_v1",
        "_type": "term",
        "_id": "20280",
        "_score": 1.4729428,
        "_source": {
          "_id": 20280,
          "name": "Test Management",
          "synonyms": [],
          "tid": 20280,
          "vid": 27
        }
      }
    ]
  }
}

Charge

Create a new charge on the billing server.

Charge
POST/charge

Parameters
HideShow
client_id
number (required) Example: 1212

Application node nid.

gateway_mode
number (required) Example: 1

1 = Live, 0 = Sandbox.

amount
decimal (required) Example: 200.50

The exact amount for the charge in ZAR (VAT included).

internal_id
string (required) Example: 123

App/site’s internal reference of person to be charged.

first_name
string (required) Example: John

Customer’s first name.

last_name
string (required) Example: Smith

Customer’s last name.

email
string (required) Example: info@envisionme.co.za

Customer’s e-mail address.

return_url
string (required) Example: http://mysite.com/after-payment

The URL to return to after the order was completed on Open Gateway. charge_id will be added to query string when returning to this URL.

cancel_url
string (required) Example: http://mysite.com/order-cancelled
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "response_code": [
    "100"
  ],
  "response_text": [
    "Subscription created."
  ],
  "not_completed": [
    ""
  ],
  "redirect": [
    "https://billing.envisionme.co.za/callback/payfast/form_redirect/1070"
  ],
  "charge_id": [
    "1070"
  ],
  "amount": [
    "500.00"
  ]
}

Charge

Get a charge by charge_id.

Charge
GET/charge

Parameters
HideShow
client_id
number (required) Example: 1212

Application node nid.

charge_id
number (required) Example: 132

ID returned when the charge was generated.

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": [
    "1059"
  ],
  "gateway_id": [
    "12"
  ],
  "date": [
    "2015-07-06T10:17:49+00:00"
  ],
  "amount": [
    "500.00"
  ],
  "card_last_four": [
    ""
  ],
  "status": [
    "ok"
  ],
  "refunded": [
    "0"
  ],
  "type": [
    "single_charge"
  ],
  "coupon": [
    ""
  ],
  "customer": [
    {
      "id": [
        "1059"
      ],
      "internal_id": [
        "313"
      ],
      "first_name": [
        "Peter"
      ],
      "last_name": [
        "John"
      ],
      "company": [
        ""
      ],
      "address_1": [
        ""
      ],
      "address_2": [
        ""
      ],
      "city": [
        ""
      ],
      "state": [
        ""
      ],
      "country": [
        ""
      ],
      "postal_code": [
        ""
      ],
      "email": [
        "address@example.com"
      ],
      "phone": [
        ""
      ],
      "date_created": [
        "2015-07-06T10:17:49+00:00"
      ],
      "status": [
        "deleted"
      ]
    }
  ]
}

Generated by aglio on 15 Sep 2019