# Search

Search for a company in a specific jurisdiction's government registry. The search is processed asynchronously: you submit a search request and receive a `searchId`, then poll for results.

## Submit a Company Search

### Request

```
POST https://api.revolutio.systems/search
```

**Headers**

| Header          | Value              |
| --------------- | ------------------ |
| `Content-Type`  | `application/json` |
| `Authorization` | `Bearer <idToken>` |

**Body**

```json
{
  "identifier": "HRB 246975",
  "jurisdiction": "DE"
}
```

| Field                | Type    | Required | Description                                                           |
| -------------------- | ------- | -------- | --------------------------------------------------------------------- |
| `identifier`         | string  | Yes      | The company registration number or search term                        |
| `jurisdiction`       | string  | Yes      | ISO country code or sub-jurisdiction code (e.g., `GB`, `US-DE`, `CH`) |
| `include`            | object  | No       | Optional flags to request additional data                             |
| `include.financials` | boolean | No       | Set to `true` to include financial data in the result                 |

### Response

{% tabs %}
{% tab title="200 OK" %}

```json
{
  "_id": "abc123searchId",
  "caseId": "xyz789caseId",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "searchInputs": {
    "identifier": "HRB 246975",
    "jurisdiction": "DE"
  },
  "status": "PENDING",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}
```

| Field          | Type   | Description                                     |
| -------------- | ------ | ----------------------------------------------- |
| `_id`          | string | Unique search ID. Use this to poll for results. |
| `caseId`       | string | Case ID grouping related searches               |
| `status`       | string | `PENDING`, `COMPLETED`, or `FAILED`             |
| `searchInputs` | object | Echo of your search parameters                  |
| `createdAt`    | string | ISO 8601 timestamp                              |
| {% endtab %}   |        |                                                 |

{% tab title="400 Bad Request" %}

```json
{
  "error": "Missing identifier and/or jurisdiction input"
}
```

Or if the jurisdiction is not supported:

```json
{
  "error": "Unsupported jurisdiction: XX"
}
```

{% endtab %}

{% tab title="402 Payment Required" %}

```json
{
  "error": "Insufficient volume remaining. Please top up.",
  "volume_remaining": 0
}
```

{% endtab %}

{% tab title="403 Forbidden" %}

```json
{
  "error": "Insufficient subscription: you are not subscribed to search in this jurisdiction",
  "jurisdiction": "DE",
  "hint": "Check your subscription coverage or contact support"
}
```

{% endtab %}

{% tab title="429 Too Many Requests" %}

```json
{
  "error": "Rate limit exceeded"
}
```

{% endtab %}
{% endtabs %}

## Get Search Status / Results

Poll for the result of an asynchronous search.

### Request

```
GET https://api.revolutio.systems/search/{searchId}/status
```

**Headers**

| Header          | Value              |
| --------------- | ------------------ |
| `Authorization` | `Bearer <idToken>` |

**Path Parameters**

| Parameter  | Type   | Description                                  |
| ---------- | ------ | -------------------------------------------- |
| `searchId` | string | The search ID returned from the POST request |

### Response

{% tabs %}
{% tab title="200 OK (Completed)" %}

```json
{
  "_id": "abc123searchId",
  "caseId": "xyz789caseId",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "searchInputs": {
    "identifier": "HRB 246975",
    "jurisdiction": "DE"
  },
  "status": "COMPLETED",
  "updatedAt": "2025-01-15T10:30:05.000Z",
  "result": {
    "_id": "entity-uuid",
    "legalName": "EXAMPLE GMBH",
    "legalForm": "Gesellschaft mit beschrankter Haftung",
    "companyStatus": "Active",
    "countryOfRegistration": "DE",
    "jurisdiction": "DE",
    "registrationDate": "2020-03-15",
    "addresses": [...],
    "identifiers": [...],
    "relationships": [...],
    "activities": [...],
    "capital": {...},
    "otherNames": [...]
  }
}
```

The `result` field contains an [Entity](/revolutio-api/data-models/entity.md) object with full company details. See [Data Models](/revolutio-api/data-models/data-models.md) for the complete schema.
{% endtab %}

{% tab title="200 OK (Pending)" %}

```json
{
  "_id": "abc123searchId",
  "caseId": "xyz789caseId",
  "status": "PENDING",
  "searchInputs": {
    "identifier": "HRB 246975",
    "jurisdiction": "DE"
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}
```

The search is still processing. Poll again after a few seconds.
{% endtab %}

{% tab title="200 OK (Failed)" %}

```json
{
  "_id": "abc123searchId",
  "caseId": "xyz789caseId",
  "status": "FAILED",
  "result": {
    "error": "Timeout while fetching registry data"
  },
  "searchInputs": {
    "identifier": "HRB 246975",
    "jurisdiction": "DE"
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:30.000Z"
}
```

{% endtab %}

{% tab title="404 Not Found" %}

```json
{
  "error": "Search not found"
}
```

{% endtab %}
{% endtabs %}

## Polling Strategy

We recommend polling with exponential backoff:

{% stepper %}
{% step %}

### Wait 2 seconds

Wait 2 seconds after submitting the search.
{% endstep %}

{% step %}

### Poll status endpoint

Poll `GET /search/{searchId}/status`.
{% endstep %}

{% step %}

### If pending, wait 3 seconds

If `status` is `PENDING`, wait 3 seconds and poll again.
{% endstep %}

{% step %}

### Increase interval up to 10 seconds

Continue increasing the interval up to a maximum of 10 seconds between polls.
{% endstep %}

{% step %}

### Stop when completed or failed

Stop after `status` is `COMPLETED` or `FAILED`.
{% endstep %}
{% endstepper %}

### Example (cURL)

```bash
# Submit search
RESPONSE=$(curl -s -X POST https://api.revolutio.systems/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"identifier": "12345678", "jurisdiction": "GB"}')

SEARCH_ID=$(echo $RESPONSE | jq -r '._id')

# Poll for results
sleep 3
curl -s https://api.revolutio.systems/search/$SEARCH_ID/status \
  -H "Authorization: Bearer $TOKEN" | jq .
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://equinoxe-systems.gitbook.io/revolutio-api/search.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.