CCW API Overview
CCW's REST API allows customers and partners to build new applications and integrate with CCW in new ways to improve their capabilities around managing a contingent workforce.
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.
Authentication
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 | Description |
|---|---|
| OAuth 2.0 credentials | Includes a Client ID and Client Secret |
| Scopes | 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:
- Sandbox: https://sso-stg1.coupahost.
com/as/token.oauth2 - Production: https://sso-prd1.coupahost.
com/as/token.oauth2
The authorization server returns a JSON payload containing the following:
| Property | Value |
|---|---|
| token_type | Prefixed with "Bearer" |
| access_token | String to be included in the authorization header when making API requests |
| expires_in | 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>
Examples:
- 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:
| Header | Description |
|---|---|
| Authorization | Used to request access for API calls. Include the bearer token with the authentication scheme: Bearer: <Token> |
| Content-Type | Set to: application/json in all requests. JSON is the only exchange format currently supported |
| X-Correlation-id | 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:
- 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.
- 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.
- 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.