Introduction

This section gives you a step-by-step introduction to your first API call using our online in browser sandbox environment.
Keep in mind that data entered using this sandbox environment is shared between all users and is reset regulary.

Usual Server Responses Description

  • 200 OK - the request was successful (some API calls may return 201 instead).

  • 201 Created - the request was successful and a resource was created.

  • 204 No Content - the request was successful but there is no representation to return (i.e. the response is empty).

  • 400 Bad Request - the request could not be understood or was missing required parameters.

  • 401 Unauthorized - authentication failed or user doesn't have permissions for requested operation.

  • 403 Forbidden - access denied.

  • 404 Not Found - resource was not found.

  • 405 Method Not Allowed - requested method is not supported for resource.

How to use our API?

Step 1: Authenticate

The SD Connect API uses OAuth STS security. Which means that a token is required for each request. You can use the following login to request a token to the sandbox environment:

  • host: https://www.acc.sdworx.com/mcip-sts/connect/token
    client_id: SDConnectDemo
    client_secret: lSniE48jsgjaRRNU
    scope: acc_mcip-sts_be_kmo_filedrop.full
    scope: client_credentials

Request sample: Get token

POST /mcip-sts/connect/token HTTP/1.1
Host: www.acc.sdworx.com
Content-Type: application/x-www-form-urlencoded;charset=utf-8
 
grant_type=client_credentials&client_id=SDConnectDemo&client_secret=lSniE48jsgjaRRNU&scope=acc_mcip-sts_be_kmo_filedrop.full

Response sample: Token

{ 
   "access_token": "fbdd7de02df60b2416f69db368dbc004", 
   "expires_in": 3600, 
   "token_type": "Bearer" 
}

Try it!

  1. Go to the token endpoint page.

  2. Press the 'Try it' button. You will be directed to the sandbox environment.

  3. Scroll down and press 'send'.

You should receive a 200 OK response containing an access token.

Step 2: GET Resources

Warning: Query String Limit
Note that the query string from requests made to the servers are normally encoded.

Example
Original Request: $filter=(EmploymentId eq 'ABCD')
Encoded Request (Received by server): $filter=(EmploymentId%20eq%20%27ABCD%27)

Limit on encoded query string: 2048 characters

Get Person Info

Once you are in possession of a valid token, you can start making requests to the API. Since most of the requests also requires some person info, your second step will be to make a call to the person operation.

Before calling the people resource you will have to add an extra key-value pair to the header of the message.

Request sample: Get people

GET /mcip/mcip_filedrop_api_be/People HTTP/1.1 
Host: www.acc.sdworx.com 
Content-Type: application/json 
Authorization: Bearer fbdd7de02df60b2416f69db368dbc004

Response sample: List of people

{ 
   "@odata.context": "http://10.163.67.248/mcip/mcip_filedrop_api_be/$metadata#People", 
   "value": [ 
     { 
        "ExternalReference": "657", 
        "PersonLocalReferences": [], 
        "Id": "4fe93af5-66dc-4eb8-89b6-4031f1feb573", 
        "CreatedDate": "2017-07-13T06:52:47.4281424Z", 
        "ModifiedDate": null, 
        "DeletedDate": null 
     } 
   ] 
}

Try it!

  1. Go to the people endpoint page.

  2. Press the 'Try it' button. You will be directed to the sandbox environment.

  3. Add a new header property called 'Authorization' with value 'Bearer' followed by the token from step 1.

  4. Scroll down and press 'send'.

You should receive a 200 OK response containing a list of people.

Other GET Resources

After getting the key and in most cases the person id, you are ready to call more operations. The procedure is identical to the people call from step two. Just don't forget to call the right endpoint.

All information required for each request can be found on the endpoints page.

Try it!

A good starting point may be to inspect the standard OData $metadata endpoint. It gives you an overview of the API functionalities.

  1. Go to the $metadata endpoint page.

  2. Press the 'Try it' button.

  3. Authorize the request like in the "Get person info" step above.

  4. Scroll down and press 'send'.

You should receive a 200 OK response containing a list of entities, actions, functions and more.

Step 3: POST Resources

Asynchronous call

HTTP POST resources in SD Connect Framework are asynchronous resources which mean, every requests
processed asynchronously, and therefore the response will not contain the final result of processing the request.

The usual response of an asynchronous call will have an status code of 202 Accepted, and a JSON object in the content, with the necessary information to follow up the evolution of the request:

{ 
     "correlationId": "d15e23d1-17fa-4514-9e2a-ae7ae14dd80a", 
     "uri": "RequestStatuses(correlationId=d15e23d1-17fa-4514-9e2a-ae7ae14dd80a)" 
}

  • The correlationId - identifies the request, and will be the same as the X-Correlation-ID HTTP header.

  • The uri - points to the resource where the status of the request can be subsequently queried.


Exceptions

Some requests will not result in a 202 Accepted, but will be rejected instead. These cases are:

  • 400 Bad Request - indicates that the server could not understand the request due to invalid syntax.

  • 401 Unauthorized - authentication failed or user doesn't have permissions for requested operation.

  • 500 Not Found - for any unhandled exceptions.

  • 501 Not Implemented - indicates the request method is not supported by the server and cannot be handled.

Request Status

As mentioned, the usual response of an asynchronous call will most of the time have an status code of 202 Accepted, and a JSON object in the content, with the necessary information
to follow up the evolution of the request.

In order to view the actual server response in our asynchronous call, you'll just have call our RequestStatus Endpoint. with the correlationId.

The response will contain a JSON object with all the information about the current status of a request

{ 
   "@odata.context": "http://localhost:60274/$metadata#RequestStatuses", 
   "value": [ 
     { 
        "CorrelationId": "8000001b-0000-d600-b63f-84710c7967bb", 
        "CreatedDate": "2017-12-13T12:28:52.7139489Z", 
        "DeletedDate": null, 
        "EntityId": null, 
        "ExternalCorrelationKey": "", 
        "Id": "d0acf37b-fe56-4074-98b6-0086c9764970", 
        "ModifiedDate": null, 
        "ParentId": null, 
        "ReasonDescription": null, 
        "ResourceUri": "RequestStatuses?$filter=CorrelationId eq 8000001b-0000-d600-b63f-84710c7967bb", 
        "Status": "Accepted" 
     } 
   ] 
}

  • The CorrelationId - is the internal correlation identifier for the request.

  • The ExternalCorrelationKey - is the external correlation key for the request.

  • The Status - is the current request status, which may take any of the values Accepted, Failed, or Completed.

  • The ReasonDescription - is an optional textual description of the current status or result.

  • The EntityId - is the identifier of the entity affected by the request.

  • The ResourceUri - is the uri to the resource affected by the request.

General Note

Country adoption of functionality

The SD Connect API is created with the same Core Framework behind it in every country. Due to the specific features of each Local Payroll Engine, some of the functionality provided by the Core Framework might not work for every country.

Some basic features should however always be available :

  • All POST operations should be supported

  • GET operations starting from the People endpoint with a filter on External Reference or ID. In these queries expands of the entities under People.

  • GET operations starting from the Employmnets endpoint with a filter on External Reference or ID. In these queries expands of the entities under Employments.

  • GET operations on the RequestStatuses endpoint with a filter on CorrelationId

More operations are probably available. This list will be updated continuously.