IntegrityNext
APIs


developer.integritynext.com

IntegrityNext | REST-APIs

The IntegrityNext platform provides REST-API access to customers (with ‘Corporate’ license). These APIs apply specifically to customers which have their own processes and tools in place and want to integrate the IntegrityNext platform into their system landscape. With purchase of the ‘Corporate’ license customers receive an authentication token. With this customers are able to activate the APIs as a self-service.

IntegrityNext provides two integrations:

  • GET Supplier Compliance Data
  • POST Create and Invite New Suppliers

Definitions

Property Description
id Supplier ID defined by the customer
name Supplier name
email Email of supplier contact to complete self-assessment
invitationStatus Status of the supplier registration
invitationTopics Optional array of compliance topics the invited supplier has to answer
duns DUNS - Data Universal Numbering System by Dun & Bradstreet (D&B)
street Supplier street
postalCode Supplier postal code
city Supplier city
countryCode Supplier country (ISO-2 code)
publicProfileUrl Link to public supplier compliance profile (results per topic on a high level)
detailedProfileUrl Link to detailed supplier compliance profile (incl. answers and certificates)
socialMediaUrl Link to social media profile of supplier (findings, messages, live stream)
total Total supplier self-assessment result
abac Anti-Bribery Anti-Corruption self-assessment result
cmin Conflict Minerals self-assessment result
ecsa Blacklist and Sanctions self-assessment result
epro Environmental Protection self-assessment result
hesa Health & Safety self-assessment result
hrla Human Rights & Labour self-assessment result
isec Information Security self-assessment result
qman Quality Management self-assessment result
scre Supply Chain Responsibility self-assessment result
trps Trading Partner Security self-assessment result
isCritical Critical Social Media messages available yes/no

Endpoint

https://api.integritynext.com
Method Path Description
GET /suppliers Retrieve list of your suppliers with compliance data
POST /suppliers Create/invite new suppliers to your company

Authentication

Currently only Basic Auth with Bearer token is supported. Simply add an Authorization header with your provided token to the HTTP request, e.g.

$ curl https://api.integritynext.com/suppliers -H "Authorization: Bearer "
Note: $ is the command line prompt, curl is https://curl.haxx.se/

GET /suppliers

  • Response
  • success: 200/OK
  • success response: Array of Objects

    [ { "id": String "name": String "email": String "invitationStatus": String ("registered"|"pending") "duns": String "publicProfileUrl": URL "detailedProfileUrl": URL "socialMediaUrl": URL "address": { "street": String "postalCode": String "city": "String "countryCode": String (ISO-2 code) }, "assessment": { "total": String ("grey"|"green"|"yellow"|"red") "abac": String "cmin": String "ecsa": String "epro": String "hesa": String "hrla": String "qman": String "isec": String "scre": String "trps": String }, "socialMediaMonitoring": { "isCritical": Bool } } ]
  • error response: see section “Error Handling”
  • Example

    [ { "id": "ext-0001", "name": "Example Supplier #1", "email": "john.doe.1@acme.com", "invitationStatus": "registered", "publicProfileUrl": https://app.integritynext.com/profiles/617e732e-f8a4-... "detailedProfileUrl": https://app.integritynext.com/profiles/detailed/754e318f-cc81-... "socialMediaUrl": https://app.integritynext.com/profiles/socialmedia/754e318f-cc81-... "address": { "street": "1600 Pennsylvania Ave NW", "postalCode": "DC 20500", "city": "Washington", "countryCode": "US" }, "assessment": { "total": "green", "abac": "green", "cmin": "green", "ecsa": "grey", "epro": "green", "hesa": "yellow", "hrla": "green", "isec": "grey", "qman": "grey", "scre": "yellow", "trps": "grey" }, "socialMediaMonitoring": { "isCritical": false } }, { "id": "ext-0002", "name": "Example Supplier #2", "email": "john.doe.2@acme.com", "invitationStatus": "registered", "publicProfileUrl": https://app.integritynext.com/profiles/728f843d-e7b5-... "detailedProfileUrl": https://app.integritynext.com/profiles/detailed/643d429a-aa70-... "duns": "123456789", "address": { "street": "Platz der Republik 1", "postalCode": "11011", "city": "Berlin", "countryCode": "DE" }, "assessment": { "total": "red", "abac": "yellow", "cmin": "grey", "ecsa": "grey", "epro": "green", "hesa": "yellow", "hrla": "green", "isec": "red", "qman": "grey", "scre": "grey", "trps": "grey" }, "socialMediaMonitoring": { "isCritical": true } } ]

POST /suppliers

  • Request
  • Header “Content-Type” must be set to “application/json”
  • Body: List of suppliers

    [ { "id": String (required) "duns": String (optional) "name": String (required) "email": String (required, valid email) "address": { "street": String "postalCode": String "city": "String "countryCode": String (ISO-2 code) }, "invitationTopics": ["qman", "cmin"] } ]
  • Validation
    • id, name and email are required
    • email must be a valid Email address
    • invitationTopics is optional
      Supports the following parameters:
      abac, cmin, ecsa, epro, hesa, hrla, isec, qman, scre, trps
      See also Definitions for topic parameters.
  • Response
  • success: 200/OK
  • success response: empty
  • validation error
    • HTTP status 422/UNPROCESSABLE_ENTITY
    • error response contains details with specific validation errors (see below)

Error Handling

In case of an error, the Corporate API will always return an appropriate HTTP status code along with a JSON error response.

Possible error codes

Status Description
400 BAD_REQUEST Invalid Request data. See error response message and details
401 UNAUTHORIZED Wrong/invalid or missing credentials. See section "Authentication"
404 NOT_FOUND Resource not found. Most probably you requested the wrong URL
405 METHOD_NOT_ALLOWED When trying to access a ressource with wrong HTTP method, e.g. PUT on /suppliers
413 PAYLOAD_TO_LARGE The amount of data you sent, exceeds a specified maximum. See error response for details
415 UNSUPPORTED_MEDIA_TYPE When wrong data format is sent or "content-type" header is wrong
422 UNPROCESSABLE_ENTITY Input validation error. Please see error response details
500 INTERNAL_SERVER_ERROR Severe, unknown error

Error response

  • Definition

    [ { "timestamp": Timestamp "id": String "status": Number "statusMessage": String "message": String "details": Optional } ]
  • timestamp: ISO-formatted date-time (UTC)
  • id: a unique identifier of the error
  • status: HTTP status code (same as in response header)
  • statusMessage: HTTP status message
  • message: a brief, human readable error message
  • details: optional, may contain arbitrary information about the error, e.g. a list of validation errors (see: example 2, below)
  • Example 1: Unauthorized error

    [ { "timestamp": "2017-12-08T13:35:51.922", "id": "7ed5e52e-47f1-43d2-ad91-9833a2095e85", "status": 401, "statusMessage": "UNAUTHORIZED", "message": "Invalid credentials" } ]
  • Example 2: Validation error

    [ { "timestamp": "2017-12-08T13:42:01.902", "id": "c4e63802-bb29-49a9-944f-e4a25736fa63", "status": 422, "statusMessage": "UNPROCESSABLE_ENTITY", "message": "Validation failed. 3 errors, see details.", "details": [ { "field": "suppliers[0].name", "value": "", "errorCode": "NotEmpty", "errorMessage": "may not be empty" }, { "field": "suppliers[0].id", "value": "", "errorCode": "NotEmpty", "errorMessage": "may not be empty" }, { "field": "suppliers[1].email", "value": "test-email", "errorCode": "Email", "errorMessage": "not a well-formed email address" } ] } ]