CentralReach APIs

Unlock the full potential of your organization with CentralReach's next-generation APIs.

Getting Started

CentralReach's Public APIs allow seamless access to crucial functionalities for managing practices, clients, staff, and more. With CentralReach's APIs, users can integrate third-party software to streamline workflows. CentralReach's API solution allows customers to connect employee data across payroll, HCM and other related systems. To access the CentralReach API services, please connect with your dedicated CentralReach representative to learn more.

CentralReach API Automate & Scale

Security

At CentralReach, the API operates using secure transport methods (HTTPS) to ensure the integrity and confidentiality of your data. Our APIs adhere to the same stringent security policies that safeguard your existing data. Moreover, API users undergo authentication via our Single Sign-On (SSO) platform, ensuring comprehensive auditability similar to other users within CentralReach.

Protocol

Our APIs at CentralReach operate through REST architecture over HTTPS, employing the application/json content type for seamless data exchange. Date properties should be transmitted in ISO-8601 UTC date format for consistency and accuracy.

Terms of Service

For detailed information regarding CentralReach APIs, including terms of use and privacy policies, please refer to our API Addendum.

Authentication

Access tokens within the CentralReach API serve as the authentication mechanism and are in the form of JSON Web Tokens (JWTs). These tokens consist of signed JSON payloads, allowing external parties to independently verify them. They contain additional metadata such as issuance time and expiration, typically asserting the identity of a singular user within the system.

 

In CentralReach, an access token denotes a specific user and organization combination through claims. There are four particularly significant claims:

 

"iss": Represents the URL of the token issuer. For instance, if the issuer is "https://login.centralreach.com", entities can access the OpenID configuration/public keys at "https://login.centralreach.com/.well-known/openid-configuration" to authenticate the token's validity. Typically, this verification is performed by entities that accept these tokens, such as the CR API, rather than consumers directly.

 

"exp": Denotes the token's expiration time, measured in seconds since the Unix epoch. Upon reaching the expiration time, the token becomes invalid for API access. Consumers must acquire a new access token to continue, as access tokens have a lifespan of one hour.

 

"sub": Signifies the subject of the token and serves as a unique user identifier.

 

"orgid": Represents the unique organization identifier (a custom CentralReach claim).

Access tokens can be programmatically generated using the OAuth 2.0 Client Credentials Grant Type flow. This is done through an HTTP POST with the following configuration:

  1. Use the “client_id” and “client_secret” provided by the CR team against the client credentials authentication flow of CentralReach's SSO service.

    curl --location 'https://login.centralreach.com/connect/token' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'client_id={CLIENT_ID}' \
    --data-urlencode 'client_secret={CLIENT_SECRET}' \
    --data-urlencode 'scope=cr-api'

  2. Use the JWT (access_token) received from the SSO service in step 1, combined with the CR API Key provisioned by the CR team.

    curl --location 'https://partners-api.centralreach.com/enterprise/v1/contacts/employee/12345' \
    --header 'x-api-key: {CR API Key}' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: {JWT}' \

Glossary

Term Definition Notes
CR API Key The API key that is issued per Organization, and is used to authorize API requests to the public API, when combined with a valid JWT. Issued by CR Implementations Team.
client_id The client_id is the first part of a credential pair that is exchanged with the SSO's provider for a JWT using the client credentials grant type. (Reference:Calling APIs with Client Credentials Grant Type) Issued by CR Implementations Team.
client_secret The client_secret is the second part of a credential pair that is exchanged with the SSO's provider for a JWT using the client credentials grant type. (Reference:Calling APIs with Client Credentials Grant Type) Issued by CR Implementations Team.
JWT Also referred to as an “access_token” in this document, it is the authentication token received from the SSO provider and is used to authenticate calls to the Public API. It can also be exchanged for a session cookie by our legacy authentication service. Issued by CR SSO service when presented with valid client_id and client_secret.

Response Codes

Response Code Description Status Action/Next Steps
200 Successful Call Authenticated N/A
400 Bad Request, empty request, invalid format Not Authenticated Review changes to the supported CR web service delivery requirements
401 Unauthorized Request, invalid credentials Not Authenticated Check username / password being used for the web service delivery
403 Insufficient permissions to view or update contact Authenticated Review the permissions of the API User
404 Not Found, Unable to find contact to update Authenticated Check user ID, First Name, Last Name, and Date of Birth fields
409 Importing a record that already exists Authenticated If updating an existing user profile, remove user creation headers
429 Rate Limit Exceeded Authenticated Request rate limit has been exceeded, please try again later
500 Internal Server Error Authenticated Review header