Look up a company by ACN in PHP

What you build: a PHP script (or the function inside it) that takes an ACN and prints the company’s name and status from the ASIC companies register, signing each call with the published PHP signing example. No SDK: one curl call with a bearer token.

Before you start: a development app, then a production app

npx comms-id init makes a development key in .env.local and prints its public key. In the Companion App, register it as a development app, enable Company for it, and put the app id in .env.local as COMMS_ID_CLIENT_ID. This key reaches only the TEST service (https://api-test.comms.id): the same API, errors and authentication as LIVE, with synthetic replies.
When it works in TEST, npx comms-id key --worker <your worker> makes the production key straight into your server’s COMMS_ID_PRIVATE_JWK secret and prints the public key; register it as a production app with Company enabled. Going live changes only the environment and the key: nothing in the code below.

A .env.local never holds a production key, and a browser never holds any key.

The code

Copy the published signing example sign.php next to this file; it needs PHP’s sodium extension (bundled since 7.2) and curl.

lookup.php:

<?php
// Look up a company by ACN from PHP: sign a token with the published example (sign.php, next
// to this file) and call the Company API. Usage: php lookup.php <acn>
// Environment: COMMS_ID_CLIENT_ID, COMMS_ID_PRIVATE_JWK and, for TEST, COMMS_ID_BASE_URL.
require __DIR__ . '/sign.php';

function comms_id_company_lookup(string $acn): array {
    $base = rtrim(getenv('COMMS_ID_BASE_URL') ?: 'https://api.comms.id', '/'); // TEST: https://api-test.comms.id
    $token = comms_id_token(trim(getenv('COMMS_ID_CLIENT_ID')), json_decode(getenv('COMMS_ID_PRIVATE_JWK'), true),
        'asic-registers', 'asic-registers:read');
    $ch = curl_init("$base/company/v1/lookup");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode(['acn' => $acn]),
        CURLOPT_HTTPHEADER => ["authorization: Bearer $token", 'content-type: application/json'],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
    ]);
    $body = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    if ($body === false) {
        throw new RuntimeException('Comms.ID did not answer');
    }
    $reply = json_decode($body, true);
    if ($status !== 200) {
        // { code, message, retryable, requestId }: a 503 is retryable; a 404 means no such ACN.
        throw new RuntimeException("Company lookup failed: {$reply['code']} ({$reply['message']})", $status);
    }
    return $reply;
}

if (PHP_SAPI === 'cli' && realpath($argv[0]) === __FILE__) {
    $reply = comms_id_company_lookup($argv[1]);
    $record = $reply['records'][0] ?? null;
    echo $record === null ? "No company has that ACN.\n" : "{$record['name']} (ACN {$record['acn']}): {$record['status']}\n";
    echo "Source: {$reply['attribution']}\n";
}

comms_id_token signs an EdDSA token for the Company audience (asic-registers) and scope (asic-registers:read), the values in the operation’s OpenAPI document under x-comms-id-auth. A new token is made for each call; it lives two minutes.

TEST first

export COMMS_ID_CLIENT_ID=app_...            # your development app
export COMMS_ID_PRIVATE_JWK='{"kty":"OKP",...}'
export COMMS_ID_BASE_URL=https://api-test.comms.id
php lookup.php 001234567   # the published example ACN: a found company
php lookup.php 000000404   # TEST's documented 404: "Company lookup failed: NOT_FOUND"
php lookup.php 000000503   # TEST's documented outage: a retryable 503

LIVE

Unset COMMS_ID_BASE_URL (the default is https://api.comms.id) and use the production app’s id and key. The script does not change.

Reference: Company API. The reply carries the snapshot’s generation and attribution; records is empty when no company has that ACN.