Creating a Person

To call the API so that it performs the operations or returns the data requested by your application, you need to make a POST request to the appropriate endpoint. When creating new resources like an EmpowerID Person, you need to POST a request to the endpoint that starts the EmpowerID Workflow service, passing to the API the necessary header and request data. For creating an EmpowerID Person, this data is as follows.


Endpoint

https://{FQDN_OF_Your_EmpowerID_Web_Server}/api/services/v1/workflow/start

Headers


KeyValue
X-EmpowerID-API-KeyThe API key for the OAuth application you created above.
AuthorizationThe OAuth token you received from EmpowerID.
Content-Typeapplication/json

Request Data

Request data is sent to the API in JSON format. The data in the below request represents the minimum key/value pairs required for creating an EmpowerID Person. The API Reference includes all possible key/value pairs that can be submitted when creating people.


OutputParameters are optional, but are useful for viewing the results of the operation.


{ 
  "Name": "CreatePerson",
  "InputParameters": 
  {
    "TargetPerson" : 
    {
      "LastName": "Adams", 
      "FirstName": "Samuel", 
      "PrimaryOrgRoleOrgZoneID": "2"
    }
  },
  "OutputParameters": [{"TargetPerson": ["PersonID", "FirstName", "LastName"]}]
}


ElementDescriptionTypeRequired
NameName of the workflowStringRequired
InputParametersWorkflow inputData ObjectRequired
     TargetPersonAttributes of the personData ObjectRequired
          FirstNameFirst name of the personStringRequired
          LastNameLast name of the personStringRequired
          PrimaryOrgRoleOrgZoneIDPrimary Business Role and Location of the personIntegerRequired
OutputParametersWorkflow outputData ObjectOptional

Code Examples

In the examples, we are passing in the minimum number of parameters and requesting an output showing the PersonID, LastName and FirstName attributes of the person that is created by the operation.

cURL

Be sure to use double quotes unless you are making the request from a non-Windows OS.

Request

curl "https://{FQDN_Of_Your_EmpowerID_Web_Server}/api/services/workflow/start" \
-X POST \
-H "X-EmpowerID-API-Key: {Your_API_Key} \
-H "Authorization: Bearer {OAuth_token_you_received_from_EmpowerID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "{ \"Name\": \"CreatePerson\", \"InputParameters\": {\"TargetPerson\":{\"LastName\"" \"Adams\", 
\"FirstName\": \"Samuel\", \"PrimaryOrgRoleOrgZoneID\" \"2\" }}, \"OutputParameters\": [{\"TargetPerson\": 
[\"PersonID\", \"FirstName\", \"LastName\"]}]}"

Ajax


$.ajax({
  url: "https://sso.empowersso.com/api/services/v1/workflow/start",
  type: "POST",
 
 headers: {
    "X-EmpowerID-API-Key": "{Your_API_Key}",
    "Content-Type": "application/json",
    "Authorization": "Bearer {OAuth_token_you_received_from_EmpowerID
	}
  },
 
  data: JSON.stringify({
  	"Name": "CreatePerson",
		"InputParameters":
		{
			"TargetPerson": {
			"FirstName": "Adams",
			"LastName" : "Samuel",
			"PrimaryOrgRoleOrgZoneID": "4980"
		}
	},
	"OutputParameters": [{"TargetPerson": ["PersonID", "FirstName", "LastName"]}]	
 
  })
})

Response

If the request is successful, you should receive a JSON response that looks similar to the following:

{
  "Id": 0,
  "Name": "CreatePerson",
  "InstanceId": "db14de5f-b8e4-4e61-a6a5-d17030e4a44f",
  "CorrelationId": "00000000-0000-0000-0000-000000000000",
  "UIType": "None",
  "UIName": "",
  "UIData": null,
  "OutputParameters": {
    "TargetPerson": {
      "PersonID": 402,
      "FirstName": "Samuel",
      "LastName": "Adams"
    }
  },
  "OutputTaskParameters": null,
  "WorkflowState": "Completed",
  "DeferredUntil": "0001-01-01T00:00:00",
  "Error": null
}
  

Postman Example

  1. Open the Postman app on your machine.
  2. In Postman, open a new tab, select POST as the HTTP method and enter https://{FQDN_Of_Your_EmpowerID_Web_Server}/api/services/workflow/start.
  3. Click the Headers tab and add the above mentioned key/value pairs.




  4. Click the Body tab, select raw and then add the below JSON:

    { 
      "Name": "CreatePerson",
      "InputParameters": 
      {
        "TargetPerson" : 
        {
          "LastName": "Adams", 
          "FirstName": "Samuel", 
          "PrimaryOrgRoleOrgZoneID": "2"
        }
      },
      "OutputParameters": [{"TargetPerson": ["PersonID", "FirstName", "LastName"]}]
    }





  5. Click Send.

    If the request is successful, you should receive a JSON response that looks similar to that shown below.

    {
      "Id": 0,
      "Name": "CreatePerson",
      "InstanceId": "db14de5f-b8e4-4e61-a6a5-d17030e4a44f",
      "CorrelationId": "00000000-0000-0000-0000-000000000000",
      "UIType": "None",
      "UIName": "",
      "UIData": null,
      "OutputParameters": {
        "TargetPerson": {
          "PersonID": 381,
          "FirstName": "Samuel",
          "LastName": "Adams"
        }
      },
      "OutputTaskParameters": null,
      "WorkflowState": "Completed",
      "DeferredUntil": "0001-01-01T00:00:00",
      "Error": null
    }
      
On this page