Candidate Lookup API

CCW's Candidate Lookup API is used to query for data about candidates who've been submitted to one or more CCW requisitions. Lookup criteria such as candidate first/last names, status, eligibility to be confirmed (as a contingent worker) and more, can be requested via the CCW Candidate Lookup API. Any candidate data matching the specific lookup criteria is returned.

The base URL to access the CCW Candidate Lookup API is: https://<instance>/api/candidates/search

Refer to the CCW API Overview to learn how to authenticate and submit POST requests to CCW APIs. Requests should include the following elements:

Request Headers

Request headers are required for authentication purposes. See Request Headers section of CCW's API Overview documentation for details.

Request Body

Meta and Data objects both must be passed in the API request body:

Meta

Metadata section defines the number of results returned, to ensure faster performance. Includes:

• Limit : Defines the maximum number of results, between 1 and 50, to be returned in a single API request (i.e., the number of results on a page)
  • Defaults to 50 results if the value for Limit is empty or greater than 50
  • Returns an error if the value for Limit is less than 1
• Offset : Defines the record at which the request should start; e.g., limit=30, offset=51 returns the next 30 records starting with record 51.
  • Defaults to 0 if the value for Offset is empty
  • Returns an error if the value for Offset is less than 0.

Data

One or more specific lookup parameters to be requested (at least one non-empty parameter must be sent).

The following table defines all Data parameters that can be passed within the Candidate Lookup API request body:

Example Request

POST /api/candidates/search
HOST: <CCW FQDN>
Authorization: Bearer <token>
Accept: "application/json"
Correlation-Id: Z098Jth56Nkio343YY1vXt

{
    "meta":{
        "limit":"number",
        "offset":"number"
    }
    "data":{
        "id":"number",
        "number":"string",
        "first_name":"string",
        "last_name":"string",
        "email":"string",
        "ccw_id":"number",
        "status":"string",
        "external_reference_number":"string",
        "requisition_number":"string",
        "hiring_manager_first_name":"string",
        "hiring_manager_last_name":"string",
        "onboarding_eligibility_met":"string",
        "confirmation_eligibility_met":"string",
        "supplier_name":"string"
    }
}

API Response

Candidate(s) matching all lookup parameters sent in the API request body are returned. The following table defines all parameters that may be included with candidates in the response from CCW to a successful API request:

Example Responses

Following is an example of a successful response, where at least one candidate matched the lookup criteria.

Notes:

• total_count: overall number of candidates that matched the lookup criteria in the API request
• has_more: true or false, indicating if there are more candidates that match the lookup criteria, in addition to those included in the response

{
  "meta": {
    "total_count": 1,
    "has_more": false
  },
  "data": [{
          "candidate":{
             "id":622757,
             "number":"CCW_CS_13897",
             "first_name":"Cedric",
             "last_name":"Daniels",
             "email":"cedric.daniels@coupa.com",
             "ccw_id":"23230203",
             "supplier":{
                "id":526,
                "name":"Test Supplier.Inc",
                "number":"483735",
                "contact": {
                    "first_name":"Lester",
                    "last_name":"Freeman",
                    "email":"lester.freeman@supplierssample.com"
                }
             },
             "requisition":{
                "id":"174011",
                "number":"RS-REQ-27130",
                "type":"Create Requisition",
                "job_code":"",
                "job_title":"Clerical",
                "work_location_code":"04872",
                "work_location_name":"04872-Craftsman CA",
                "type_of_service":"Clerical/Professional",
                "rate_type":"Per Hour"
             },
             "hiring_manager_user_name": "100DuChloe1.DuCollins1.1@coupadev.com",
             "hiring_manager_first_name": "DuCollins1.1",
             "hiring_manager_last_name": "100DuChloe1",
             "hiring_manager_email": "100DuChloe1.DuCollins1.1@coupadev.com",
             "engagement_type": "Regular",
             "employment_type": "1099",
             "status": "wo-accepted",
             "submitted_date": "2020-07-28T14:36:22Z",
             "cw_number": "RS-CW-059713",
             "number": "RS-CS-0060176",
             "short_listed": false,
             "work_email": "",
             "date_available": null,
             "submitted_to_other_requirements": false,
             "onboarding_status": "initiated",
             "onboarding_eligibility_met": 1,
             "confirmation_eligibility_met": false,
             "statement_of_works": [],
             "work_orders":[
              {
                "id":224583,
                "number":"RS-WO-059860",
                "active":"true",
                "contract_start_date":"2020-07-01T04:00:00Z",
                "contract_end_date":"2020-12-31T05:00:00Z"
                "external_reference_number": ""
              }
            ]
          }
        ],
        "meta": {
        "total_count": 1,
        "has_more": false
    }
}

Following is an example of a response where no candidates met the lookup criteria:

{   
  "meta": {     
    "total_count": 0,     
    "has_more": false   
  },   
  "data":[] 
}

Valid Candidate Statuses

Following are the valid candidate status values that may be passed in a request to CCW's Candidate API:

Error Codes

When an API request fails, the response will include one of the following error codes: