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 Ensure the Authorization header is formatted correctly as:
Authorization: Bearer <token>
403 Forbidden Not Authenticated Missing or incorrect API Key in Header, verify that it is correct
500 Internal Server Error Not Authenticated Review header, expired JWT Token, request new token
400 Bad Request, empty request, invalid format Authenticated Review endpoint validations based on the error message received
403 Insufficient permissions to view or update contact Authenticated Review the permissions of the API User for that particular endpoint
404 Not Found, Unable to find contact to update Authenticated Make sure the API User is connected to the requested contactID, check contact ID
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

Places of Service

ID Code Formatted
1 1 01 - Pharmacy
2 3 03 - School
3 4 04 - Homeless Shelter
4 5 05 - Indian Health Service Free-standing Facility
5 6 06 - Indian Health Service Provider-based Facility
6 7 07 - Tribal 638 Free-standing Facility
7 8 08 - Tribal 638 Provider-based Facility
8 9 09 - Prison/Correctional Facility
9 11 11 - Office
10 12 12 - Home
11 13 13 - Assisted Living Facility
12 14 14 - Group Home
13 15 15 - Mobile Unit
14 16 16 - Temporary Lodging
15 20 20 - Urgent Care Facility
16 21 21 - Inpatient Hospital
17 22 22 - On Campus-Outpatient Hospital
18 23 23 - Emergency Room – Hospital
19 24 24 - Ambulatory Surgical Center
20 25 25 - Birthing Center
21 26 26 - Military Treatment Facility
22 31 31 - Skilled Nursing Facility
23 32 32 - Nursing Facility
24 33 33 - Custodial Care Facility
25 34 34 - Hospice
26 41 41 - Ambulance - Land
27 42 42 - Ambulance – Air or Water
28 49 49 - Independent Clinic
29 50 50 - Federally Qualified Health Center
30 51 51 - Inpatient Psychiatric Facility
31 52 52 - Psychiatric Facility-Partial Hospitalization
32 53 53 - Community Mental Health Center
33 54 54 - Intermediate Care Facility/Individuals with Intellectual Disabilities
34 55 55 - Residential Substance Abuse Treatment Facility
35 56 56 - Psychiatric Residential Treatment Center
36 57 57 - Non-residential Substance Abuse Treatment Facility
37 60 60 - Mass Immunization Center
38 61 61 - Comprehensive Inpatient Rehabilitation Facility
39 62 62 - Comprehensive Outpatient Rehabilitation Facility
40 65 65 - End-Stage Renal Disease Treatment Facility
41 71 71 - Public Health Clinic
42 72 72 - Rural Health Clinic
43 81 81 - Independent Laboratory
44 99 99 - Other Place of Service
45 2 02 - Telehealth Provided Other than in Patient's Home
46 17 17 - Walk-in Retail Health Clinic
49 58 58 - Non-residential Opioid Treatment Facility
50 10 10 - Telehealth Provided in Patient's Home
51 18 18 - Place of Employment-Worksite
52 19 19 - Off Campus-Outpatient Hospital

Custom Identifiers

ID Description
1 UCI - UCI Number
2 Vendor # - Vendor Number
3 StudentId - Student Id
4 CAQH # - CAQH Number
5 0B - State License Number
6 1A - Blue Cross Provider Number
7 1B - Blue Shield Provider Number
8 1C - Medicare Provider Number
9 1D - Medicaid Provider Number
10 1G - Provider UPIN Number
11 1H - CHAMPUS ID
12 1J - Facility ID Number
13 B3 - PPO Number
14 BQ - HMO Number
15 EI - Employer ID
16 FH - Clinic Number
17 G2 - Provider Commercial Number
18 G3 - Predetermination of Benefits ID
19 G5 - Provider Site Number
20 LU - Location Number
21 N5 - Plan Network Number
22 TJ - Federal taxpayer's Identification Number
23 X4 - Clinical Laboratory Improvement Amendment Number
24 X5 - State Industrial Accident Provider Number
25 the BHPN - Vendor ID (Direct) - the BHPN - Vendor ID (Direct)
26 the BHPN - Vendor ID (Indirect) - the BHPN - Vendor ID (Indirect)
27 the BHPN - Vendor Name (Direct) - the BHPN - Vendor Name (Direct)
28 the BHPN - Vendor Name (Indirect) - the BHPN - Vendor Name (Indirect)
29 the BHPN - Rendering Provider ID - the BHPN - Rendering Provider ID
31 Location - Location for Invoice
32 ATAP Vendor # - ATAP - Vendor Number
33 ATAP Care Manager - ATAP - Care Manager
34 the BHPN - Vendor ID (Telehealth) - the BHPN - Vendor ID (Telehealth)
35 the BHPN - Vendor Name (Telehealth) - the BHPN - Vendor Name (Telehealth)
36 Enrollment # - Enrollment Number