Certification Assignments

You can assign, update, delete, and retrieve details about certification assignments using operations against the /v1/commons/persons/certifications resource.

Prerequisites

A person's person ID is the same as the personKey and employee ID, and is not the same as the person number.

The person in this example has a person ID of 100 and a person number of 20190.

Example

In this example, we retrieve a list of available certifications and then assign, verify, update, and delete a person's certification assignments.

Retrieve available certifications

Call GET /v1/scheduling/certifications to retrieve a list of all available certifications. The response returned will resemble the example below.

[
    {
        "id": 1,
        "name": "Ground Staff Services",
        "abbreviation": "GSS",
        "active": true,
        "deleted": false,
        "version": 1
    },
    {
        "id": 2,
        "name": "Project Management",
        "abbreviation": "Proj",
        "active": true,
        "deleted": false,
        "version": 1
    },
    {
        "id": 3,
        "name": "Quality Management",
        "abbreviation": "Qua",
        "active": true,
        "deleted": false,
        "version": 1
    },
    {
        "id": 4,
        "name": "Server Platform",
        "abbreviation": "Ser",
        "active": true,
        "deleted": false,
        "version": 1
    }
]

Create the assignment

The create request:

uses personId in the URL and personIdentity in the request body to identify the person using their person ID and person number, respectively
uses certification within assignments to define the certification to assign
uses effectiveDate and expirationDate to define the effective date and the expiration date of the assignment

Note: You must pass Person ID in the URL, but you may specify either a person ID or a person number in the personIdentity object. You must include all of the information above to make a successful request. Unlike many assignments, expiration date is required.

Example request

Call PUT /v1/commons/persons/certifications/100 with the following request payload.

{
  "personIdentity": {
    "personNumber": "20190"
  },
  "assignments": [
    {
      "certification": {
        "qualifier": "Project Management"
      },
      "effectiveDate": "2020-02-20",
      "expirationDate": "2021-02-19"
    }
  ]
}

Example response

A success response returns HTTP status code 200 and a response body similar to the following example.

{
    "personIdentity": {
        "personKey": 100,
        "personNumber": "20190"
    },
    "assignments": [
        {
            "certification": {
                "qualifier": "Project Management"
            },
            "effectiveDate": "2020-02-20",
            "expirationDate": "2021-02-19"
        }
    ]
}

Verify the assignment

To verify, you can call GET /v1/commons/persons/certifications?person_number={personNumber} or GET /v1/commons/persons/certifications/{personId}.

Calling GET /v1/commons/persons/certifications?person_number=20190 or GET /v1/commons/persons/certifications/100 returns:

{
    "personIdentity": {
        "personKey": 100,
        "personNumber": "20190"
    },
    "assignments": [
        {
            "certification": {
                "id": 2,
                "qualifier": "Project Management"
            },
            "proficiencyLevel": {
                "id": -1,
                "qualifier": "ANY"
            },
            "effectiveDate": "2020-02-20",
            "expirationDate": "2021-02-19"
        }
    ]
}

Update the assignment

To update the person's certification assignments by adding an addition certification, call PUT /v1/commons/persons/certifications/100 with the following request payload.

Note that this PUT operation replaces all existing certification assignments with the request body. If you want to continue to include a person's previously assigned certifications, be sure to include them in the update's request body as shown in the example below.

Example request

{
  "personIdentity": {
    "personNumber": "20190"
  },
  "assignments": [
    {
      "certification": {
        "qualifier": "Project Management"
      },
      "effectiveDate": "2020-02-20",
      "expirationDate": "2021-02-19"
    },
    {
      "certification": {
        "qualifier": "Quality Management"
      },
      "effectiveDate": "2020-03-20",
      "expirationDate": "2021-03-19"
    }
  ]
}

Example response

{
    "personIdentity": {
        "personKey": 100,
        "personNumber": "20190"
    },
    "assignments": [
        {
            "certification": {
                "qualifier": "Project Management"
            },
            "effectiveDate": "2020-02-20",
            "expirationDate": "2021-02-19"
        },
        {
            "certification": {
                "qualifier": "Quality Management"
            },
            "effectiveDate": "2020-03-20",
            "expirationDate": "2021-03-19"
        }
    ]
}

Delete an assignment

To delete a certification assignment associated with a person, call POST /v1/commons/persons/certifications/apply_delete and specify the unwanted certification assignments in the request.

For our example, to remove the Quality Management certification, submit the following request payload.

Example request

{
  "personIdentity": {
    "personNumber": "20190"
  },
  "assignments": [
    {
      "certification": {
        "qualifier": "Quality Management"
      },
      "effectiveDate": "2020-03-20",
      "expirationDate": "2021-03-19"
    }
  ]
}

Example response

{
    "personIdentity": {
        "personKey": 100,
        "personNumber": "20190"
    },
    "assignments": [
        {
            "certification": {
                "qualifier": "Project Management"
            },
            "effectiveDate": "2020-02-20",
            "expirationDate": "2021-02-19"
        }
    ]
}