This document will show you how to use Signifyd's REST API to authenticate, make requests, and retrieve data.

Download OpenAPI specification:Download

All responses to and from the API will be in JSON.

If you are a Signifyd customer and would like to access Enterprise API documentation, please log in here and navigate to the Resource Center within Developer Tools.

Versioning

We only update the version of our API when a non backwards-compatible change is made.

Signifyd considers the following changes to be backwards-compatible:

  • Adding new optional request parameter(s) to an existing API endpoint.
  • Adding a new value to an enum field.
  • Adding new fields to existing API responses.
  • Changing the order of fields in an existing API response.
  • Adding a brand new API resource.
  • Adding a new webhook event. Your integration should handle unfamiliar webhook events gracefully.
  • Changing the length of UUIDs (though we don't change lengths that often!).
  • Changing the format of error messages, and other human readable strings.

Response Codes

We use conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, invalid syntax, etc.), and codes in the 5xx range indicate an error with Signifyd's servers.

CodeDescription
200Success - Request completed.
201Success - New resource created.
202Success - The request has been accepted, but not yet processed.
204Success - No content to return.
400Bad Request - The request could not be parsed, generally due to bad syntax.
401Unauthorized - The request could not be authenticated due to missing or invalid credentials.
403Forbidden - You do not have permission to access to the resource.
404Not Found - The resource doesn't exist.
409Conflict - The with state of the resource on server. Can occur with (too rapid) PUT requests.
429The request was not accepted because the application has exceeded the rate limit.
500Internal Server Error - An internal error occurred in Signifyd.
503Service Unavailable - The server is currently unavailable. Check the status page for reported outages.
504Gateway Timeout - The request could not complete in time.

Dates

Our API uses the ISO8601 date format for complete date plus hours, minutes, seconds and timezone offset.

         yyyy-MM-dd'T'HH:mm:ssZ
For UTC: 2015-11-03T13:21:58+00:00
For PST: 2015-11-03T13:21:58-08:00

Required vs Needed

If a parameter is marked as required, it means the API call will fail with a 400 status code if the parameter is not included in the request.

If a parameter is marked as needed, the API call will not fail, but not including it will prevent you from receiving liability coverage unless otherwise noted in your legal contract for a liability-shift service.

Before going live with our service, such that you receive a liability shift, you are expected to validate that needed fields are included completely and accurately. Throughout the terms of your service, you are expected to ensure that needed fields are sent to Signifyd.

Sensitive Data Protection Layer

In order to prevent the unintended receipt of sensitive data, Signifyd has implemented various protocols at the API layer that will reject requests which are identified to contain unwanted sensitive data. Upon receipt of a request containing unwanted sensitive data, Signifyd's API will immediately reject the request with a 400 HTTP status code and indicate the motive for the request rejection with the following error message:

Potentially sensitive data detected. Refer to Signifyd API documentation for more information about our Sensitive Data Protection Layer.

The sensitive data itself is not logged or persisted within Signifyd's system in any way, and we actively monitor our system for detection of unwanted sensitive data from our customers.