# Apivom Atlas — Ireland — CRO Web Services (Companies Registration Office)

> Apivom Atlas integration for Ireland — CRO Web Services (Companies Registration Office): 8 gateway routes over `services.cro.ie`, available through the Apivom platform (Apivom Iris workflows and the Apivom Atlas API). Auth model: caller-supplied token passed through to the vendor.

Notes for AI assistants:

- This catalog mirrors the vendor's public API surface as registered in Apivom Atlas (8 read-only, 0 write routes).
- Access is provisioned per customer. Commercialized providers are self-service in Apivom Atlas; for everything else [request a demo](https://apivom.com/en/contact?topic=demo&product=atlas).
- Credentials are always owned by the calling tenant — Apivom Atlas is a stateless gateway.

## Routes

- `GET /companies` (companies, read-only) — params: query
- `GET /companycount` (companycount, read-only) — params: query
- `GET /company/{company_num}/{company_bus_ind}` (company, read-only) — params: params, query
- `GET /company/{company_num}/{company_bus_ind}/submissions` (company-submissions, read-only) — params: params, query
- `GET /submissions` (submissions, read-only) — params: query
- `GET /submissioncount` (submissioncount, read-only) — params: query
- `GET /submission/{sub_num}/{doc_num}` (submission, read-only) — params: params
- `GET /status` (status, read-only)

## Credential model

- CRO account email (`email`) — required
- CRO API key (`apiKey`) — required — secret

## Optional

- [Apivom Atlas product page](https://apivom.com/en/products/atlas)
- [All Atlas integration guides](https://apivom.com/llms.txt)
- [Request a demo](https://apivom.com/en/contact?topic=demo&product=atlas)

## Commercial API (self-service, prepaid)

> Live Irish Companies Registration Office register: search companies and business names by name, number or address; company profile (status, type, registration date, address, Eircode, last and next annual return, last accounts date) and the filing index of each company (form and document type, received and effective dates, accounts year-end). Prepaid, per-query priced REST API. All prices are net USD (VAT-excluded); no platform fee. Authentication: per-tenant API key in the `x-api-key` header.

Instructions for AI assistants integrating this API:

- Base URL: `https://atlas.apivom.com`
- Every request MUST send the header `x-api-key: <your API key>` (issued in Apivom Atlas; rotatable at any time).
- Charges are prepaid: each successful data-returning query debits the tenant balance at the route price below. Queries that return no data are not charged.
- Repeat queries with the same parameters are served from a server-side cache FREE of charge (`"cached": true` in the response). Append `?force=true` to the query URL to bypass the cache and fetch fresh data (charged at the route price).
- HTTP 402 means the prepaid balance is insufficient — top up before retrying.
- Never place the API key in URLs or client-side code; call from your backend only.

## Endpoints

### Check prepaid balance

```
GET https://atlas.apivom.com/ie-cro-cws/api/v1/balance
```

Response: `{ "balanceMinor": "170000", "currency": "USD", "recentLedger": [...] }` — `balanceMinor` is in minor units (cents).

### Search companies — $0.05 per query

Search the register by company_name (searchType 1 exact, 2 starts with, 3 contains), company_num or address. company_bus_ind C = companies, B = business names. Up to 250 rows.

```
POST https://atlas.apivom.com/ie-cro-cws/api/v1/query/companies
Content-Type: application/json
x-api-key: <your API key>

{
  "query": {
    "max": 10,
    "company_name": "adobe systems",
    "company_bus_ind": "C"
  }
}
```

Response envelope: `{ "data": <upstream body>, "upstreamStatus": <int>, "charged": <bool>, "chargeMinor": "<minor units or null>", "cached": <bool> }` — `cached: true` responses are free. Add `?force=true` for a fresh (charged) query.

### Get a company — $0.05 per query

One company or business name by CRO number and indicator (C or B).

```
POST https://atlas.apivom.com/ie-cro-cws/api/v1/query/company
Content-Type: application/json
x-api-key: <your API key>

{
  "params": {
    "company_num": "344992",
    "company_bus_ind": "C"
  }
}
```

Response envelope: `{ "data": <upstream body>, "upstreamStatus": <int>, "charged": <bool>, "chargeMinor": "<minor units or null>", "cached": <bool> }` — `cached: true` responses are free. Add `?force=true` for a fresh (charged) query.

### Count search matches — $0.05 per query

How many rows a companies search would return.

```
POST https://atlas.apivom.com/ie-cro-cws/api/v1/query/companycount
Content-Type: application/json
x-api-key: <your API key>

{
  "query": {
    "company_name": "adobe",
    "company_bus_ind": "C"
  }
}
```

Response envelope: `{ "data": <upstream body>, "upstreamStatus": <int>, "charged": <bool>, "chargeMinor": "<minor units or null>", "cached": <bool> }` — `cached: true` responses are free. Add `?force=true` for a fresh (charged) query.

### List a company filings — $0.05 per query

Filing index of one company: submission and document numbers, form and document type, status, received and effective dates, accounts year-end. Document files are not served by the API.

```
POST https://atlas.apivom.com/ie-cro-cws/api/v1/query/company-submissions
Content-Type: application/json
x-api-key: <your API key>

{
  "query": {
    "max": 50
  },
  "params": {
    "company_num": "344992",
    "company_bus_ind": "C"
  }
}
```

Response envelope: `{ "data": <upstream body>, "upstreamStatus": <int>, "charged": <bool>, "chargeMinor": "<minor units or null>", "cached": <bool> }` — `cached: true` responses are free. Add `?force=true` for a fresh (charged) query.

### Service status — $0.05 per query

Whether the CRO services are running.

```
POST https://atlas.apivom.com/ie-cro-cws/api/v1/query/status
Content-Type: application/json
x-api-key: <your API key>

{}
```

Response envelope: `{ "data": <upstream body>, "upstreamStatus": <int>, "charged": <bool>, "chargeMinor": "<minor units or null>", "cached": <bool> }` — `cached: true` responses are free. Add `?force=true` for a fresh (charged) query.

### Get a filed document record — $0.05 per query

Metadata of one filed document (submission number and document number).

```
POST https://atlas.apivom.com/ie-cro-cws/api/v1/query/submission
Content-Type: application/json
x-api-key: <your API key>

{
  "params": {
    "doc_num": "12192980",
    "sub_num": "10278668"
  }
}
```

Response envelope: `{ "data": <upstream body>, "upstreamStatus": <int>, "charged": <bool>, "chargeMinor": "<minor units or null>", "cached": <bool> }` — `cached: true` responses are free. Add `?force=true` for a fresh (charged) query.

### Count filings — $0.05 per query

Number of filings of a company or submission.

```
POST https://atlas.apivom.com/ie-cro-cws/api/v1/query/submissioncount
Content-Type: application/json
x-api-key: <your API key>

{
  "query": {
    "company_num": 344992,
    "company_bus_ind": "C"
  }
}
```

Response envelope: `{ "data": <upstream body>, "upstreamStatus": <int>, "charged": <bool>, "chargeMinor": "<minor units or null>", "cached": <bool> }` — `cached: true` responses are free. Add `?force=true` for a fresh (charged) query.

### Search filings — $0.05 per query

Filing index by submission number or by company number and indicator.

```
POST https://atlas.apivom.com/ie-cro-cws/api/v1/query/submissions
Content-Type: application/json
x-api-key: <your API key>

{
  "query": {
    "max": 50,
    "company_num": 344992,
    "company_bus_ind": "C"
  }
}
```

Response envelope: `{ "data": <upstream body>, "upstreamStatus": <int>, "charged": <bool>, "chargeMinor": "<minor units or null>", "cached": <bool> }` — `cached: true` responses are free. Add `?force=true` for a fresh (charged) query.

## Error codes

- `401 MISSING_API_KEY` / `401 INVALID_API_KEY` — missing or unknown key
- `403 FEATURE_DISABLED` — the provider/route is not enabled for your tenant
- `402 INSUFFICIENT_BALANCE` — prepaid balance too low; top up first
- `404 PROVIDER_NOT_FOUND` / `404 ROUTE_NOT_FOUND` — unknown provider or route
- `502 UPSTREAM_ERROR` / `503 NO_CREDENTIAL` — temporary upstream problem; retry later

## Optional

- [Apivom Atlas (balance, logs, key management)](https://atlas.apivom.com/one)
- [This guide as markdown](https://atlas.apivom.com/one/docs/ie-cro-cws/llms.txt)

