IPQualityScore

IPQualityScore (IPQS) API Style Guide

This style guide recommends best practices for integrating and developing against the IPQualityScore (IPQS) APIs. These are not definitive rules, but are closer to loose guidelines for how we intend to develop new functionality and improve our fraud detection APIs going forward.

Best API Practices
  • Use defensive coding principals whenever possible to prevent an API response failure from negatively impacting your website's performance.
  • When writing code or storage against our API, please make every field nullable.
  • Expect new fields to appear occasionally and without notice.
  • Set reasonable timeouts on all calls depending on API type.
  • Check the "success" value on all responses, which will return "false" when your account is out of credits. It's also possible to have a soft failure which will lack the normal fields you would expect for the call.
  • Be aware as APIs may return status codes other than 200 in the event of a possible failure. Specifically 403 in the event of a rate limit and 500/502/503 in the event of a system issue.
  • Check the "message" value for guidance when you receive a failed response.
  • Make periodic calls to our account credit usage API to check your plan's available credits.
  • Do not depend on the order of each value in a response, as these can change at any time.
Breaking Changes

IPQS will not make breaking changes to existing endpoints without a minimum of 3 months notice. Notices for breaking updates shall be found on the account dashboard. Major breaking changes shall be sent via email. Changes are considered breaking if they would impact a customer which integrated our API services in accordance with these guidelines.

What is a breaking change?

Some examples of breaking changes:

  • Removing or renaming fields, arguments or accepted values.
  • Removing endpoints
  • Adding new redirects to hosted tools.
  • Changing the type of fields in the response (eg: from String to Integer)
  • Adding a new required argument
  • Changing authentication, authorization or header requirements
  • Utilizing status codes that are not on the following list: 200, 403, 500, 502 or 503
What is NOT a breaking change?

Some examples of non-breaking changes:

  • Any additive change, such as adding endpoints, adding non-required arguments, adding additional response fields, etc...
  • Changes to error messages.
  • Changing the order of fields in a response.
  • Returning a field as null instead of it's normal type. (eg: String returned as null)
  • Changing of failure status codes (IE: 500 becomes a 503)
Documentation

Documentation is available for each API endpoint. As new data points are added, each the respective documentation will also be updated to define any new fields and their possible values.