CCW API Overview

Using CCW's REST API customers and partners can build new applications and integrate with CCW in new ways, to improve their capabilities around managing a contingent workforce. CCW's APIs are HTTP-based RESTful APIs that use OAuth 2.0 for authentication and TLS 1.2 for transport layer security. This documentation explains how to access CCW's API and make requests to obtain the data you need.


Customers who want to access the CCW REST API can register their API consumer app and receive the OAuth 2.0 client credentials to use in combination with two additional layers of security - Scopes and User/Role access rights - to authenticate requests to the CCW API.

Authentication Requirement


OAuth 2.0 credentials

Includes a Client ID and Client Secret


The end points pointing to the specific module/functionality within CCW being requested

User/Role access rights

Assigned within the CCW application. Once you are authenticated by the API (see below), another layer of security determines access to the specific functionality being requested

Access Token

The first step in accessing the CCW API is to request an access token by making a call with the OAuth credentials and scope(s), as in the following example:

curl -XPOST -H "Content-type: application/json" -d '{"client_id": "<<clientID>>", "client_secret": "<<secret>>",
"scope":"ccw.candidate", "grant_type":"client_credential"}' 'Auth_Url'

For 'Auth_Url', use the following, depending on your environment:

The authorization server returns a JSON payload containing the following:




Prefixed with "Bearer"


String to be included in the authorization header when making API requests


Number of seconds until the token expires (typically 3600, or 1 hour)

API End Points

Include the access token received in calls to CCW API endpoints.

End Point format: https://<instance>/api/<resource path>


  • Candidate Confirmation: https://{hostname}/API/candidates/{id}/confirm

  • Candidate Lookup: https://{hostname}/API/candidates/search

  • Contingent Worker (CW) Lookup: https://{hostname}/API/contingent_workers

Request Headers

The following HTTP request headers are required:




Used to request access for API calls. Include the bearer token with the authentication scheme: Bearer: <Token>


Set to: application/json in all requests. JSON is the only exchange format currently supported


An identifier of 36 characters maximum, generated to enable tracking and auditing of the API request

Error Responses

Sample error response

 "error_code": "string",
 "error_summary": "string",
 "error_causes": [
   "error_sub_code": "string",
   "error_sub_code_desc": "string"

Rate limiting

CCW REST API’s do not have explicit rate limiting, however, throttling of API requests is recommended for a timely response. Coming soon, Individual API endpoints will be updated with recommended rate limiting.

Best practices

Below are some tips to ensure best results when building applications on top of CCW using our REST APIs:

  1. Avoid Schema Validation: CCW API's are constantly evolving, with new optional properties added to the API. For extensibility purposes, applications should not perform a schema validation, which can trigger errors when the API sends new properties that may not be required.

  2. Use HTTP Status Codes: Consumer applications should rely on HTTP status codes for handling API errors, rather than contents of the response body which are for diagnostic and logging purposes only.

  3. Avoid depending on order of properties in API response: CCW API's only support JSON content. The order of properties in an API response may change due to the introduction of new properties.