Search Accounts | Coperniq API

const url = 'https://api.coperniq.io/v1/accounts/search?prop1=prop1&op1=eq&value1=value1';
const options = {method: 'GET', headers: {'x-api-key': '<apiKey>'}};
try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

[
  {
    "id": 1,
    "createdAt": "2024-01-15T09:30:00Z",
    "updatedAt": "2024-01-15T09:30:00Z",
    "title": "string",
    "description": "string",
    "address": [
      "string"
    ],
    "isActive": true,
    "primaryEmail": "string",
    "primaryPhone": "string",
    "number": 1,
    "createdBy": {
      "id": 1,
      "firstName": "string",
      "lastName": "string",
      "email": "string",
      "avatarUrl": "string"
    },
    "updatedBy": {
      "id": 1,
      "firstName": "string",
      "lastName": "string",
      "email": "string",
      "avatarUrl": "string"
    },
    "custom": {},
    "accountType": "RESIDENTIAL",
    "contacts": [
      {
        "id": 1,
        "name": "string",
        "title": "string",
        "description": "string",
        "emails": [
          "string"
        ],
        "phones": [
          "string"
        ],
        "isPrimary": true
      }
    ]
  }
]

Search accounts using up to two filters (prop1/op1/value1 and optionally prop2/op2/value2), combined with logic (AND/OR).

Properties:

propX can be a standard field (e.g., status, title, city, type, accountId, etc.) or a custom property key name.
Use the property key from your company settings.
Filter by parent account with accountId. clientId is accepted as a deprecated alias for backwards compatibility.

Operators (opX):

Equality: eq, neq
Numeric/datetime comparisons: gt, gte, lt, lte
Text/string matching: contains (case-insensitive)
Lists: in, nin (CSV list in valueX)
Ranges: between (use valueX as from,to)
Existence: exists is not supported for custom properties due to performance limitations. Use eq or neq instead.

Value formats:

in/nin: lists can be provided as:
- Plain CSV: value1=OPEN,ACTIVE
- Quoted CSV (to include commas inside a value): value1="Last, First",Other
- JSON array: value1=["Last, First","Other"]
between: from,to (e.g., value1=2025-01-01,2025-12-31 or value1=10,20)
Dates should be ISO 8601 strings; numeric-like values on custom properties are matched against both numeric and text representations.

Examples:

status equals ACTIVE: ?prop1=status&op1=eq&value1=ACTIVE
custom id equals 1234: ?prop1=legacy_tool_project_id&op1=eq&value1=1234
title contains “Solar”: ?prop1=name&op1=contains&value1=Solar
status IN (ACTIVE, ON_HOLD) AND city = Austin: ?prop1=status&op1=in&value1=ACTIVE,ON_HOLD&logic=and&prop2=city&op2=eq&value2=Austin

Note: The /clients path is an alias for /accounts and will continue to work until users are individually notified and migrated.

Search accounts using up to two filters (prop1/op1/value1 and optionally prop2/op2/value2), combined with `logic` (AND/OR). Properties: - `propX` can be a standard field (e.g., `status`, `title`, `city`, `type`, `accountId`, etc.) or a custom property key name. - Use the `property key` from your company settings. - Filter by parent account with `accountId`. `clientId` is accepted as a deprecated alias for backwards compatibility. Operators (`opX`): - Equality: `eq`, `neq` - Numeric/datetime comparisons: `gt`, `gte`, `lt`, `lte` - Text/string matching: `contains` (case-insensitive) - Lists: `in`, `nin` (CSV list in `valueX`) - Ranges: `between` (use `valueX` as `from,to`) - Existence: `exists` is not supported for custom properties due to performance limitations. Use `eq` or `neq` instead. Value formats: - `in`/`nin`: lists can be provided as: - Plain CSV: `value1=OPEN,ACTIVE` - Quoted CSV (to include commas inside a value): `value1="Last, First",Other` - JSON array: `value1=["Last, First","Other"]` - `between`: `from,to` (e.g., `value1=2025-01-01,2025-12-31` or `value1=10,20`) - Dates should be ISO 8601 strings; numeric-like values on custom properties are matched against both numeric and text representations. Examples: - status equals ACTIVE: `?prop1=status&op1=eq&value1=ACTIVE` - custom id equals 1234: `?prop1=legacy_tool_project_id&op1=eq&value1=1234` - title contains "Solar": `?prop1=name&op1=contains&value1=Solar` - status IN (ACTIVE, ON_HOLD) AND city = Austin: `?prop1=status&op1=in&value1=ACTIVE,ON_HOLD&logic=and&prop2=city&op2=eq&value2=Austin` **Note:** The `/clients` path is an alias for `/accounts` and will continue to work until users are individually notified and migrated.

Authentication

x-api-keystring

API Key authentication via header

Query parameters

prop1stringRequired

First field to filter (standard or custom keyName)

op1enumRequired

Operator for prop1

value1stringRequired

Value for prop1 (comma-separated values for in/nin or between)

logicenumOptionalDefaults to and

Logical combination when both prop1 and prop2 are provided

Allowed values:

prop2stringOptional

Optional second field to filter

op2enumOptional

Operator for prop2

value2stringOptional

Value for prop2 (comma-separated values for in/nin or between)

page_sizeintegerOptional1-100Defaults to 20

Number of items per page (max 100)

pageintegerOptional>=1Defaults to 1

Page number (1-based)

order_byenumOptionalDefaults to asc

Sort order for results

Allowed values:

include_archivedbooleanOptionalDefaults to false

Whether to include archived (inactive) records in the response. By default only active records are returned.

include_contactsbooleanOptionalDefaults to false

Whether to include associated contacts in the response. Defaults to false unless explicitly set to true.

Response

List of accounts matching filters

idintegerOptional

Unique identifier

createdAtstringOptionalformat: "date-time"

Creation timestamp

updatedAtstringOptionalformat: "date-time"

Timestamp of the most recent update to the record, including changes to its custom property values.

titlestringOptional

Record title/name

descriptionstring or nullOptional

Record description

addresslist of stringsOptional

Record location/address

isActivebooleanOptional

Whether the record is active

primaryEmailstring or nullOptionalformat: "email"

Primary contact email

primaryPhonestring or nullOptional

Primary contact phone

numberintegerOptional

Record number (e.g., 1234)

createdByobject or nullOptional

User who created the record. Null when the record was created by a non-user actor (e.g. automation or a contact).

updatedByobject or nullOptional

User who last edited a field on the record, derived from the changelog. Null when the record has never been edited or the last edit was made by a non-user actor.

custommap from strings to anyOptional

Custom fields

accountTypeenum or nullOptional

Type of account (residential or commercial)

contactslist of objectsOptional

On GET requests, only populated when include_contacts=true is passed. Always populated on POST (create) and PATCH (update) responses. Ordered with the primary contact first, capped at 20 contacts.

Errors

400

Bad Request Error

401

Unauthorized Error