Automatically monitor regulatory updates to map to your internal policies, procesures and controls. Learn More
-

1558 Enforcement Actions in the U.S. over past 30 days

-

FTC enforcements decreased 55% over the past 30 days

-

SEC issued enforcements: $37,812,859 over the past 30 days

-

50 Final Rules go into effect in the next 7 days

-

49 Mortgage Lending docs published in the last 7 days

-

1670 docs with extracted obligations from the last 7 days

-

new Proposed and Final Rules were published in the past 7 days

-

11906 new docs in pro.compliance.ai within the last 7 days

-

Check out Expert In The Loop Forum OnDemand!

-

Considering RCM Solutions?  Here’s an RFP to get started.

-
NAVIGATION

Getting Started with Compliance.ai API

Registration
Authorization
Request Authentication
Error Handling
Next steps

Compliance.ai offers support for OAuth 2.0 Authentication for all of our API methods in the Compliance.ai developer API platform.

This guide provides the steps necessary to start using Compliance.ai’s Developer API with OAuth 2.0.

  • Register once
  • Authorize periodically (refresh token)
  • Authenticate each time you call the API

Registration

A Client ID (API key) and Client Secret is generated once a user has registered an account and created a new application:

  • If you haven’t already, register for an account on Compliance.ai’s developer platform by signing up here.
  • Once you are logged in:
    • Go to “My Account” on the top right of the screen
    • Select the “Application” section
    • Create a new application and add following details:
      • Application name
      • Web page about the application
      • Description
  • When an application is created, Compliance.ai team will review & approve the application.
  • After approval, the application status will change to “active”
    • The Client ID and Client Secret can be found under the “Keys” section of “My Account”, along with details of the API plan
      • Client ID is also referred to as Key or API Key
      • API Key / Client ID string will be 24 characters long
      • Client Secret string will be 10 characters long

Authorization

An access token is issued, along with other parameters, in a response to a well formatted authorization request. Please note that an authorization request will count towards the calls per day quota and Compliance.ai has accounted for 6 authorization related requests per day in each of our API subscription plans.

  • A successful response will include the following parameters:
    • Access Token
    • Token Type: bearer
    • Time to Expiration: 3600
    • Refresh Token
  • Access Token string will be 24 characters long
  • Refresh Token string will be 24 characters long

There are three ways you can generate an access token to pass along in header of the API request:

  • Generating through I/O Docs on Compliance.ai Developer Platform
  • Generating through API call directly
    • Add in the following into the authorization request:
    • Example of request and response using Postman:
      • POST /oauth2/token HTTP/1.1
      • Host: compliance.api.mashery.com
      • Content-Type: application/x-www-form-urlencoded
      • cache-control: no-cache
      • Postman-Token: 2d3b1419-9273-454d-8261-dd926960bf88
      • client_id=[]client_secret=[]grant_type=client_credentials

  • Generating through Python
    • You can download the sample code using this link.
  • Generating using Refresh Token
    • Add in the following into a Post request:
    • Example Request:
      • POST /oauth2/token HTTP/1.1
      • Host: compliance.api.mashery.com
      • Content-Type: application/x-www-form-urlencoded
      • cache-control: no-cache
      • client_id=ysszm2yk7gp5r9ernuaurgccclient_secret=w9t7t48g7Hgrant_type=refresh_tokenrefresh_token=6mh3cgqvc6d992fd45zc88ueundefined=undefined
    • Example Response:
      • “access_token”: ” “,
      • “token_type”: “bearer”,
      • “expires_in”: 3600,
      • “refresh_token”: ” “
    • Notes:
      • A new refresh token is issued along with the new access token
      • If the most recent refresh token is not included in the request, you will receive the following error:
        • “error”: “invalid_grant”,
          “error_description”: “Invalid refresh token”

Request Authentication

When making a request to any Compliance.ai API method using OAuth 2.0 authentication, include the Access Token in the Request Header as an Authorization Bearer.

  • Examples:
    • Interactive API on Compliance.ai
      • Request URL:
        • https://api.compliance.ai/v1/searchoauth?[filters]
      • Request Header:
        • accept-encoding: identity
        • Authorization: Bearer [access token]
        • X-Originating-IP:
    • Postman
        • GET /v1/searchoauth HTTP/1.1
        • Host: api.compliance.ai
        • Authorization: Bearer [access token]
        • cache-control: no-cache

 

API Calls Error Handling

The Compliance.ai API provides various endpoints.  Sometimes, when using the APIs, you may receive specific error messages in the response data. This document provides insights into the meaning of the error codes, the potential impact and resolutions that can be applied.

 

Error Code 403
Status Code 403 Forbidden
Response Header (Sample) HTTP Status Code: 403 Forbidden

Date: Thu, 15 June 2023 19:47:15 GMT

Content-Type: text/xml

Content-Length: 28

Connection: keep-alive

X-Plan-Qps-Allotted: 5

X-Plan-Qps-Current: 1

X-Plan-Quota-Allotted: 2

X-Plan-Quota-Current: 33

X-Plan-Quota-Reset: Friday, June 16, 2023 12:00:00 AM GMT

X-Error-Detail-Header: Account Over Rate Limit

X-Mashery-Error-Code: ERR_403_DEVELOPER_OVER_RATE
Response Body <h1>Developer Over Rate</h1>
Description Receiving the 403 Forbidden error with the message “Developer Over Rate” indicates that the associated API key / token has exceeded the provisioned rate limit for API requests. Compliance.ai imposes certain limits on the number of requests associated with specific API keys over specific timeframes. These restrictions are based on performance requirements and the associated API key’s licensing requirements
Impact Exceeding the rate limit results in the API rejecting further requests until the rate limit resets. In this scenario, this endpoint has been called 33 times when the rate limit is only 2 per day. The API will reject subsequent requests until the rate limit is reset.
Resolution
  1. API requests must wait until the rate limit resets, which is specified in the response headers as “X-Plan-Quota-Reset”. For example:”X-Plan-Quota-Reset: Friday, June 16, 2023 12:00:00 AM GMT.”Once the rate limit resets, API requests can resume within the defined rate limit.
  2. Increase your licensed quota: Contact Compliance.ai client success team (support@compliance.ai) to review various API licensing options that could provide additional API capacity: more frequent API invocations, additional documents (meta data) returned, etc.
Error Code 504
Status Code 504 Gateway Timeout
Response Header (Sample) Date: Fri, 16 June 2023 20:37:25 GMT

Content-Type: text/xml

Content-Length: 24

Connection: keep-alive

X-Plan-Qps-Allotted: 1

X-Plan-Qps-Current: 2

X-Plan-Quota-Allotted: 5000

X-Plan-Quota-Current: 57

X-Plan-Quota-Reset: Saturday, June 17, 2023 12:00:00 AM GMT

X-Mashery-Error-Code: ERR_504_GATEWAY_TIMEOUT
Response Body <h1>Gateway Timeout</h1>
Description Receiving a “Gateway Timeout” error implies that the API key or token you are using has reached its limit regarding the number of requests it can make within a given timeframe.
Impact Your API calls will not be processed successfully and may result in errors or incomplete responses. If your application heavily relies on the API, the error can disrupt service or functionality. In this scenario, this endpoint has been called twice a second when the Throttle limit is one call per second.
Resolution
  1. Review Throttle Limits: Understand the throttle limits the API provider sets for your API key/token. Determine if the current limits are appropriate for your application’s needs.
  2. Optimize API Usage: Analyze your application’s API usage patterns and consider optimizing your requests to reduce the number of calls or optimize the payload to minimize data transfer.
  3.  Retry After Delay: If the error is intermittent, it could be due to temporary overload or high traffic. Retry the request after a brief delay to see if the issue is resolved.
  4. Upgrade API Plan: If you consistently exceed the throttle limits, consider upgrading your API plan or contacting Compliance.ai’s client success team (support@compliance.ai) to discuss increasing the throttle limits for your specific use case.
Error Code 401
Status Code 401 Unauthorized
Response Header (Sample) Date: Fri, 16 June 2023 19:56:54 GMT

Content-Type: text/xml

Content-Length: 27

Connection: keep-alive

Www-Authenticate: Bearer realm=”api.compliance.ai”, error=”invalid_token”

X-Error-Detail-Header: Account Inactive

X-Mashery-Error-Code: ERR_403_DEVELOPER_INACTIVE
Response Body <h1>Developer Inactive</h1>
Description The 401 Unauthorized error indicates that the request lacks valid authentication credentials or the provided credentials are invalid. In this case, the response includes the header “Www-Authenticate” with the value “Bearer realm= “api.compliance.ai”, error= “invalid_token” to indicate that the bearer token used for authentication is either missing or invalid. The response body “<h1>Developer Inactive</h1>” provides additional information, specifying that the developer associated with the token is inactive.
Impact
  1. Access Denied: The API request is rejected as the authentication credentials are invalid.
  2. Limited Functionality: Without proper authentication, access to protected resources or certain API functionality is restricted or completely blocked.
  3. Service Disruption: If your application heavily relies on the API, the error can disrupt its regular operation or cause failures in specific features or functionalities.
Resolution
  1. Verify Token Validity: Check the bearer token used for authentication and ensure it is valid. This may involve verifying the token expiration, signature, or other required parameters.
  2. Obtain New Credentials: If the token is invalid or expired, obtain a new valid bearer token from the API provider or authentication service.
  3. Review Authentication Mechanism: Ensure that the authentication mechanism used in your application aligns with the requirements specified by the API provider. This may involve updating authentication headers, implementing OAuth flows, or using API keys as required.

Next Steps

Contact us to schedule a demo and discuss integration options in detail.

If you’re a developer, join our Developer Program to learn more and begin using our interactive API.

X