Discrepancies:

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="description" content=""> <meta name="author" content=""> <link rel="icon" href="../../favicon.ico"> <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script> <script src='/js/jquery.wiggle.min.js' type='text/javascript'></script> <script src="/js/explorer.js" type="text/javascript"></script> <link href="/css/xcode.css" type="text/css" media="screen" rel="stylesheet"> <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css" integrity="sha384-1q8mTJOASx8j1Au+a5WDVnPi2lkFfwwEAa8hDDdjZlpLegxhjVME1fgjWPGmkzs7" crossorigin="anonymous"> <link href="/css/style.css" rel="stylesheet"> <link href="/css/govstrap.css" rel="stylesheet"> <link href="/css/govstrap_extra.css" rel="stylesheet"> <link href="/css/developer.css" rel="stylesheet"> <link href="https://fonts.googleapis.com/css?family=Open+Sans:400,600" rel="stylesheet"> <link href='https://maxcdn.bootstrapcdn.com/font-awesome/4.6.3/css/font-awesome.min.css' rel='stylesheet' type='text/css'>  <script src='/js/highlight.pack.js' type='text/javascript'></script> <script>hljs.initHighlightingOnLoad();</script> <title>Discrepancies: </title> </head> <body > <nav class="navbar navbar-fixed-top shadow"> <div class="container-fluid"> <div class="row"> <div class="1 col-lg-1 hidden-xs hidden-sm hidden-md"></div> <div class="col-xs-12 col-sm-12 col-md-12 col-lg-10"> <div class="navbar-header"> <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar"> <span class="sr-only">Toggle navigation</span> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </button> <a class="navbar-brand" href="/discrepancies/reference">Companies House</a> <span class="api-title">Discrepancies</span> </div> <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1"> <ul class="nav navbar-nav navbar-right"> <li> <a href="/">All APIs</a> </li> </ul> </div> </div> <div class="col-lg-1 hidden-xs hidden-sm hidden-md"></div> </div> </div> </nav> <div class="container-fluid"> <div class="row"> <div class="hidden-md col-lg-1 hidden-xs hidden-sm"></div> <div class="col-xs-12 col-sm-12 col-md-12 col-lg-10 main-body"> <div class="body-header body-header-content"> <ul id="SIN" class="nav navbar-nav navbar-right userbar deactivate"> <li> <span class="user_info" id="email"></span>: </li> <li><a href="/developer/applications">Applications</a></li> <li> <a href="/developer/signout">Sign out</a> </li> </ul> <ul id="SOUT" class="nav navbar-nav navbar-right userbar deactivate"> <li><a href="/developer/signin">Sign in</a></li> </ul> <ul id="ERROR" class="nav navbar-nav navbar-right userbar deactivate"> <li id="placeholder"></li> </ul> </div> <div class="row"> <div class="col-xs-12 col-sm-3 col-md-3 col-lg-3"> <script> $(document).ready(function(){ $('.items').hide(); var $pagename=decodeURI( window.location.pathname ); var $parent=$('ul[id="navigation"]'); var $element=$parent.find('a[href$="'+$pagename+'"]'); if( $element.length == 0 ) { $pagename = sessionStorage.lastpage; $element=$parent.find('a[href$="'+$pagename+'"]'); } sessionStorage.lastpage = $pagename; var api_id = $element.data('outer'); var toggler = $("#toggle"+api_id); var outerul = $("#ul"+api_id); outerul.addClass('in'); toggler.addClass('open'); toggler.removeClass('collapsed'); $element.addClass('nav-selected'); $parent.removeClass('hide'); }); </script> <div class="side-nav affix"> <ul class="nav nav-sidebar hide" id="navigation"> <li> <a href="/discrepancies/guides/overview">Discrepancies Overview</a> </li> <li> <a id="togglepersons-with-significant-control" class="nav-toggle collapsed" data-toggle="collapse" data-target="#ulpersons-with-significant-control">Persons with significant control</a> <ul class="nav collapse nav-inner" id="ulpersons-with-significant-control"> <li><a data-outer="persons-with-significant-control" href="/discrepancies/reference/persons-with-significant-control">Summary</a></li> <li><a data-outer="persons-with-significant-control" href="/discrepancies/reference/persons-with-significant-control/create-discrepancy">create discrepancies</a></li> <li><a data-outer="persons-with-significant-control" href="/discrepancies/reference/persons-with-significant-control/create-psc-discrepancy-report">create report</a></li> <li><a data-outer="persons-with-significant-control" href="/discrepancies/reference/persons-with-significant-control/update-psc-discrepancy-report">update report</a></li> </ul> </li> <li> <a id="togglediscrepancies_spec" class="nav-toggle collapsed" data-toggle="collapse" data-target="#uldiscrepancies_spec">OpenAPI specification</a> <ul class="nav collapse nav-inner" id="uldiscrepancies_spec"> <li><a data-outer="discrepancies_spec" href="/api.ch.gov.uk-specifications/swagger-2.0/spec/pscDiscrepancies.json">Download</a></li> </ul> </li> </ul> </div> </div> <div class="col-xs-12 col-sm-9 col-md-9 col-lg-9 main"> <h1 class="page-header"><a name="overview" class="anchor" href="#overview" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>Overview</h1> <p>Companies House Discrepancies service allows 3rd party software to report discrepancies to Companies House</p> <p>Discrepancies initially exposes one API Service:</p> <ul> <li><code>Persons with Significant Control</code>. This API provides the specific reporting functionality for discrepancies involving Persons with Significant Control. A report can be created, and multiple discrepancies can be added before submitting the report to Companies House.</li> </ul> <h1 class="page-header"><a name="authentication" class="anchor" href="#authentication" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a> Authentication</h1> <p>Discrepancies requires software to integrate with Companies House OAuth 2.0 Service and cannot be done with a simple API key using <code>Basic</code> authentication.</p> <p>For a detailed guide on this integration see <a href="https://developer-specs.company-information.service.gov.uk/companies-house-identity-service/guides/ServerWeb" rel="nofollow">Authenticating Web Server Apps with OAuth 2.0</a></p> <p>The Persons with Significant Control API will have additional security. Users will be required to obtain the appropriate PSC Discrepancy scope and API endpoints check that the end user has the appropriate permissions associated to their <code>client_id</code> and <code>client_secret</code>. Please ask any Obliged Entities wishing to file via your software to contact Companies House by emailing pscdiscrepancyapi@companieshouse.gov.uk and request that the appropriate permissions are associated with their user credentials. This requirement does not apply in live sandbox.</p> <h2 class="sub-header"><a name="scopes" class="anchor" href="#scopes" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a> Scopes</h2> <p>All Discrepancies software will need to sign their users in to Companies House with one or more <code>scopes</code>.</p> <ul> <li><p><code>https://identity.company-information.service.gov.uk/user/profile.read</code> is required for Discrepancies and grants permission to read the users profile data.</p></li> <li><p><code>https://identity.company-information.service.gov.uk/psc-discrepancy-reports.write-full</code> is required for Persons with Significant Control submissions</p></li> </ul> <p>Combining multiple scopes is done by space separating them as one string so the requested scope for Discrepancies for Persons with Significant Control submissions should be:</p> <ul> <li><code>https://identity.company-information.service.gov.uk/user/profile.read</code> <code>https://api.company-information.service.gov.uk/psc-discrepancy-reports.write-full</code></li> </ul> <h1 class="page-header"><a name="report-discrepancies" class="anchor" href="#report-discrepancies" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a> Report Discrepancies</h1> <h2 class="sub-header"><a name="creating-a-report" class="anchor" href="#creating-a-report" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a> Creating A Report</h2> <p>The first step in any Persons with Significant Control submission will be to create a report. This is done with a POST request to <code>/psc-discrepancy-reports</code>.</p> <h2 class="sub-header"><a name="creating-discrepancies" class="anchor" href="#creating-discrepancies" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a> Creating Discrepancies</h2> <p>Once a report has been created, your software will have a <code>discrepancy-report-id</code> to use for creating discrepancies. To create discrepancies using the Person with Significant Control API, your software will need to use the <code>discrepancy-report-id</code> to construct the URL.</p> <p><code>/psc-discrepancy-reports/{discrepancy-report-id}/discrepancies</code></p> <p>Making a valid POST request to this URL will add the discrepancies to the report.</p> <h2 class="sub-header"><a name="updating-a-report" class="anchor" href="#updating-a-report" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a> Updating a Report</h2> <p>Once a report has been created it can be updated by making a <code>PUT</code> request to <code>/psc-discrepancy-reports</code> where the request body sets the status field to <code>INCOMPLETE</code> e.g.</p> <p><code>PUT https://api.company-information.service.gov.uk/psc-discrepancy-reports/{discrepancy-report-id}</code> with a request body:</p> <pre><code><code>{ "status":"INCOMPLETE" } </code></code></pre> <h2 class="sub-header"><a name="completing-a-report" class="anchor" href="#completing-a-report" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a> Completing a Report</h2> <p>Once a report has one or more discrepancies added to it, it must be completed before it can be submitted to Companies House. A report can be completed by making a <code>PUT</code> request to <code>/psc-discrepancy-reports</code> where the request body sets the status field to <code>COMPLETE</code> e.g.</p> <p><code>PUT https://api.company-information.service.gov.uk/psc-discrepancy-reports/{discrepancy-report-id}</code> with a request body:</p> <pre><code><code>{ "status":"COMPLETE" } </code></code></pre> <p>Once a report has been completed, it can no longer be modified by the end user or any third-party software. The discrepancies can no longer be changed either.</p> <h2 class="sub-header"><a name="example" class="anchor" href="#example" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a> Example</h2> <p>Each endpoint is documented with examples within the developer site.</p> <h1 class="page-header"><a name="testing" class="anchor" href="#testing" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a> Testing</h1> <h2 class="sub-header"><a name="sandbox-environment" class="anchor" href="#sandbox-environment" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a> Sandbox Environment</h2> <p>When testing any software that integrates with the Companies House Discrepancies service, you will be able to test using our Sandbox environment.</p> <ul> <li>Sandbox API: <code>https://api-sandbox.company-information.service.gov.uk</code></li> <li>Sandbox Identity/OAuth Service: <code>https://identity-sandbox.company-information.service.gov.uk</code></li> <li>Sandbox Test Data API: <code>https://test-data-sandbox.company-information.service.gov.uk</code></li> </ul> <p>The services above allow all Discrepancy functions and related Public Data APIs functions (such as <code>GET /company/{company_number}</code>) for test companies.</p> <h2 class="sub-header"><a name="test-api-clients" class="anchor" href="#test-api-clients" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a> Test API Clients</h2> <p>The Sandbox environment does not allow use of <code>Live</code> API clients that have been created in the Companies House Developer Hub.</p> <p>In order to use the sandbox environment, you will need to create <code>Test</code> API clients and configure your software to use those instead.</p> <p>This may include a test web client and test API key if your software uses both. For instance, a web client to integrate with the OAuth service and API key to call public data functions.</p> <h2 class="sub-header"><a name="test-data-api" class="anchor" href="#test-data-api" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a> Test Data API</h2> <p>The Sandbox test data api allows test companies with Persons with Significant Control to be generated on demand for use in the sandbox environment. This service is not available in the Live environment.</p> <h1 class="page-header"><a name="moving-to-live" class="anchor" href="#moving-to-live" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a> Moving To Live</h1> <p>Once your software has passed testing and you are ready to move to Live, there are a few things that will need to change in your software. Ideally, these items will be configurable with properties files, environment variables, database lookups or some other mechanism that does not require code changes:</p> <ul> <li>The Companies House API domain</li> <li>The Companies House Identity/OAuth Service domain</li> <li>Your Client ID and Client Secret combination</li> <li>Your API key</li> </ul> <h2 class="sub-header"><a name="live-responses" class="anchor" href="#live-responses" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a> Live Responses</h2> <p>In the Live environment, responses will not be mocked. This means that all submissions will be sent to Companies House for review and if valid will be accepted on to the public register.</p> </div> </div> </div> <div class="col-lg-1 hidden-xs hidden-sm hidden-md"></div> </div> </div> <div id="footer" class="footer"> <div class="container-fluid"> <div class="row"> <div class="col-lg-1 hidden-xs hidden-sm hidden-md"></div> <div class="col-xs-12 col-sm-12 col-md-12 col-lg-10"> <ul class="nav navbar-nav"> <li><a href="http://www.companieshouse.gov.uk/legal/termsAndConditions.shtml">Policies</a></li> <li><a href="https://find-and-update.company-information.service.gov.uk/help/cookies">Cookies</a></li> <li><a href="http://forum.aws.chdev.org">Forum</a></li> <li><a href="https://find-and-update.company-information.service.gov.uk/help/contact-us">Contact us</a></li> </ul> </div> <div class="col-lg-1 hidden-xs hidden-sm hidden-md"></div> </div> </div> </div> <script src="/js/userbar.js"></script> <script> $(document).ready(function(){ apiExplorer.setBeforeSendCallback( function( request ) { var apiKey = apiExplorer.readApiKey(); var accessToken = apiExplorer.readAccessToken(); var basicAuth = apiExplorer.getBasicAuthentication(); if( accessToken != "" ) { request.headers = {Authorization: "Bearer "+accessToken}; } else if( apiKey != "" ) { request.params = {key: apiKey}; } else if( basicAuth != "" ) { request.headers = {Authorization: "Basic "+basicAuth}; } }); }); </script> </body> <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/js/bootstrap.min.js" integrity="sha384-0mSbJDEHialfmuBBQP6A4Qrprq5OVfW37PRR3j5ELqxss1yVqOtnepnHVP9aJ7xS" crossorigin="anonymous"></script> </html>

CINXE.COM

Discrepancies: