UKG Pro ATS

Authentication

User needs to perform following steps to integrate with UKG Pro Recruiting through Knit.

1. Get the credentials from UKG support
2. Get applicant source id

1. Get the credentials from UKG support

The UKG Identity team registers the Partner or Customer Integration App with Recruiting , using an offline process. For the integration to connect to the correct UKG Pro Recruiting APIs, integration developers need the following required authentication information:

• Client ID - Unique identifier of the identity client provided by UKG customer support.
• Client Secret - A client secret associated with the client ID provided by UKG customer support.
• Identity Server - Identity server associate with customer tenant provided by UKG customer support. E.g - signin.ukg.net, signin.ultipro.com etc.

Identify tenant and recruiting application domain -

You must login to UKG Pro Recruiting and examine the URL in browser address bar. The customer’s {tenant} value follows the first slash after the domain name.

Here you can clearly identify Recruiting Domain (Application URL) and Tenant.

2. Get applicant source id

The user needs to get applicant source id for creating applications. There are two steps -

1. Add your app as applicant source (Optional if already added) - User needs to add your app as applicant source with any given name.
2. Copy the applicant source id Copy the id generated for applicant source and input while doing integration with Knit.

🚧

Applicant source is important for creating applications and helps user to identify the candidates which are created by you.

Creating application with UKG Pro Recruiting

You need to use Create application API with additional fields inside "metaData" key in body parameter.

Screening Questions

A job posting or Opportunity in UKG Pro Recruiting can include screening questions. The use of
screening questions is optional. The UKG Pro API does allow you to send an application
without including responses to the screening questions, but this creates the application with
empty answers to the screening questions.

There are three types of questions -

1. Multiple Choice Questions - upto 260 answer choices with upto 400 character as choice text.
2. Text Field Questions - text field where upto 4000 characters can be entered.
3. Number Range Questions - text field where a whole number between 1 to 999,999,999 can be chosen.

If you wish to add screening questions responses while creating applications there are two steps -

1. Fetch screening questions - screening questions can be fetched through Knit's passthrough API. The API path for fetching screening questions for given job opportunity is - api/opportunities/{opportunity-id}/screening-questions. .

Below example shows sample curl request for fetching screening questions. Response inside body will be stringified Json

curl --request POST \
     --url https://api.getknit.dev/v1.0/passthrough \
     --header 'Authorization: Bearer API_KEY' \
     --header 'X-Knit-Integration-Id: Integration-ID' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "method": "GET",
  "path": "api/opportunities/{jobId}/screening-questions"
}
'

{
  "success": true,
  "data": {
    "response": {
      "body": [
        {
          "id": "0af112ef-18a9-4c2d-9930-5f3c5abc6d48",
          "library_question": {
            "id": "1d172377-300c-40ca-bdec-c6944dcda090"
          },
          "type": "Text",
          "question": {
            "en_us": "What is your full legal name?"
          },
          "score": 0,
          "ordinal": 1,
          "is_active": true,
          "links": [
            {
              "href": "https://service2.ultipro.com/talent/recruiting/v2/SEA1002SICM/api/opportunities/6eb841e4-670f-493e-92cc-5f46114a8be9/screening-questions/0af112ef-18a9-4c2d-9930-5f3c5abc6d48",
              "rel": "self"
            }
          ]
        }
      ],
      "headers": {
        "Access-Control-Expose-Headers": "link",
        "Content-Type": "application/json; charset=utf-8",
        // ... (other headers)
      }
    }
  }
}

Screening question Response- The sample responses for different type of screening questions response is given below. "response" key contains candidate response and their value may vary based on type of question.

 {
    "id": "0af112ef-18a9-4c2d-9930-5f3c5abc6d48",
    "response": "Alice",
     "question": {
                "type": "Text",
                "text": {
                    "en_us": "What is your full legal name?"
                },
                "potential_score": 0
            }
   }

2.Collect Question Responses and send it in Create application API - Once you get the responses for the screening questions , use these in create application API.

Possible Errors while creating application -

The application creation process involves two steps:
i. Creating a candidate profile with the provided details.
ii. Adding the created candidate to a specific job (applying for the job).

During the application creation process, you may encounter errors related to -

1. Duplicate candidate creation - While attempting to create an application, it may encounter a potential failure during the second step, specifically when adding a candidate to a job. This failure could result from various reasons, such as a mismatch in screening questions responses. Consequently, this could lead to the unintentional creation of the candidate in UKG Pro. Subsequently, if a user attempts to retry the request, they may encounter an error indicating that the candidate already exists in the system.

Possible error messages -

[
    {
        "type": 0,
        "message_code": "validation_V16ErrorCode10111",
        "member_names": []
    }
]

Resolution - Since candidate is already has been created then we can fetch candidate Id by Passthrough Request Below example is given for fetching candidate by email.

curl --request POST \
     --url https://api.getknit.dev/v1.0/passthrough \
     --header 'Authorization: Bearer API Key \
     --header 'X-Knit-Integration-Id: Integration-Id' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "method": "POST",
  "path": "api/candidates-lookup",
  "body": "{\"email\":\"[email protected]\"}"
}

{
  "success": true,
  "data": {
    "response": {
      "body": "{\r\n  \"id\": \"3ba27024-67d7-4b55-870f-a5b2d54ef826\"\r\n}",
      "headers": {
        "Access-Control-Expose-Headers": "link",
        "Content-Type": "application/json; charset=utf-8",
        "Date": "Fri, 17 Nov 2023 10:38:33 GMT",
        "Server": "Microsoft-IIS/10.0",
        "X-Correlation-Id": "ba5ff20d-0d37-43ba-b732-46827f64cc81",
        "X-Powered-By": "ASP.NET",
        "X-Ratelimit-Limit": "0",
        "X-Ratelimit-Remaining": "0",
        "X-Ratelimit-Reset": "0",
        "X-Tyk-Api-Expires": "Thu, 02 Jan 3000 15:04:00 UTC",
        "Transfer-Encoding": "chunked",
        "Strict-Transport-Security": "max-age=63072000"
      }
    }
  }
}

2. Screening Questions Errors - If any job has enabled screening questions. Then screening questions response must me sent inside metaData key while creating application.

• Incorrect No of question response - All active screening questions which are active must be sent along with their response during application creation. The below attached error is sent when there is mismatch in screening questions response.

[
    {
        "type": 0,
        "message_code": "validation_IncorrectNumberOfQuestionResponses",
        "member_names": []
    }
]

Resolution: Check and validate following things to fix this.

1. Filter screening questions where is_active parameter is true.
2. The question ids from get screening questions API should match with those sent in screening questions response during create application API.