# List all contacts

Required scopes: contact-data:read

Endpoint: GET /contacts
Version: v1
Security: http, oauth2

## Query parameters:

  - `sort` (string)
    Available sorts are first_name, last_name, created_at, custom_fields..You can sort by multiple options by separating them with a comma. To sort in descending order, use - sign in front of the sort, for example: -title.
    Example: "sort=-created_at,title"

  - `include` (string)
    Available includes are companies. You can include multiple options by separating them with a comma.

  - `page[size]` (integer)
    The number of results that will be returned per page.

  - `page[cursor]` (string)
    The cursor to start the pagination from.

  - `filter` (string)
    Allowed filter fields (with allowed operators):

| Field | Type | Operators |
|------|------|-----------|
| archived | enum: with, only, without | eq |
| first_name | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| last_name | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| birthday | date | eq, ne, neq, lt, lte, le, gt, gte, ge, in, nin, notin, isnull, isnotnull, notnull |
| email | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| email_private | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| mobile | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| mobile_private | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| telephone | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| telephone_private | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| fax | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| address_street | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| address_street2 | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| address_house | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| address_zip | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| address_state | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| address_town | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| address_country.name | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| owner.id | id | eq, ne, neq, in, nin, notin, isnull, isnotnull, notnull |
| owner.email | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| owner.external_id | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| owner.external_origin | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| client.id | id | eq, ne, neq, in, nin, notin, isnull, isnotnull, notnull |
| client.name | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| client.shortcode | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| client.external_id | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| client.external_origin | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| created_at | date | eq, ne, neq, lt, lte, le, gt, gte, ge, in, nin, notin, isnull, isnotnull, notnull |
| updated_at | date | eq, ne, neq, lt, lte, le, gt, gte, ge, in, nin, notin, isnull, isnotnull, notnull |
| external_origin | string | in, nin, notin, eq, ne, neq, contains, like, startswith, endswith, isnull, isnotnull, notnull |
| companies | Relation - id (id) - external_id (string) - company_name (string) - external_origin (string) - tax_uid (string) - iban (string) - bic (string) - phone (string) - fax (string) - email (string) - email_general (string) - homepage (string) | any, none, count, all |
| custom_fields.* — see Custom fields below | custom | eq, ne, neq, lt, lte, le, gt, gte, ge, in, nin, notin, contains, like, startswith, endswith, isnull, isnotnull, notnull |

Filtering expression. Accepts either JSON (array/tree of conditions) or a readable string DSL.

You can check the full syntax at Docs Filtering section.

Special values:
- me.id — current authenticated user id (usable on fields of type id). Example: id eq me.id
- now — current date-time. Example: dueOn lt now
- sow/eow — start/end of week. Examples: dueOn gt sow, dueOn lt eow
- som/eom — start/end of month. Examples: dueOn gt som, dueOn lt eom
- today — special date for today; with eq it expands to the whole day range. Example: dueOn eq today
- today±Nd — relative day offset. Examples: today-30d, today+5d.

Custom fields: when enabled, you can filter by custom_fields.. Example: custom_fields.my_flag eq 'yes' or custom_fields.score gte 10. Supported ops depend on the custom field type (eq, ne, in, nin, contains, startswith, endswith, isnull, isnotnull, and comparisons for numeric/date types).
    Example: "title contains \"Acme\" and (created_at >= \"2024-01-01\" or client.name contains \"Corp\")"

## Response 200 fields (application/json):

  - `data` (array, required)
    The list of items

  - `data.id` (string, required)

  - `data.external_id` (string,null, required)
    Can be used to add an identifier to the client from an external system, must be unique

  - `data.external_origin` (string,null, required)
    If originated from external system origin is added

  - `data.gender` (string,null, required)

  - `data.first_name` (string,null, required)

  - `data.last_name` (string,null, required)

  - `data.title` (string,null, required)

  - `data.title_suffix` (string,null, required)

  - `data.position` (string,null, required)

  - `data.locale` (string,null, required)

  - `data.birthday` (string,null, required)

  - `data.fax` (string,null, required)

  - `data.telephone` (string,null, required)

  - `data.telephone_private` (string,null, required)

  - `data.mobile` (string,null, required)

  - `data.mobile_private` (string,null, required)

  - `data.email` (string,null, required)

  - `data.email_private` (string,null, required)

  - `data.address_street` (string,null, required)

  - `data.address_house` (string,null, required)

  - `data.address_street2` (string,null, required)

  - `data.address_zip` (string,null, required)

  - `data.address_state` (string,null, required)

  - `data.address_town` (string,null, required)

  - `data.address_country` (any, required)

  - `data.owner` (any, required)

  - `data.client` (any, required)

  - `data.companies` (array)

  - `data.companies.vendor_identifier` (string,null, required)

  - `data.companies.company_name` (string,null, required)

  - `data.companies.tax_uid` (string,null, required)

  - `data.companies.taxation_enabled` (boolean, required)
    Can be used to indicate reverse charge ie

  - `data.companies.iban` (string,null, required)

  - `data.companies.bic` (string,null, required)

  - `data.companies.email_general` (string,null, required)

  - `data.companies.phone` (string,null, required)

  - `data.companies.homepage` (string,null, required)

  - `data.companies.invoices_by_post` (boolean, required)

  - `data.companies.invoices_by_email` (boolean, required)

  - `data.companies.business_field` (any, required)

  - `data.companies.company_size` (any, required)

  - `data.companies.company_revenue` (any, required)

  - `data.companies.person_attention_to` (string,null, required)

  - `data.companies.address_invoice_title` (string,null, required)

  - `data.companies.address_invoice_street` (string,null, required)

  - `data.companies.address_invoice_house` (string,null, required)

  - `data.companies.address_invoice_street2` (string,null, required)

  - `data.companies.address_invoice_zip` (string,null, required)

  - `data.companies.address_invoice_state` (string,null, required)

  - `data.companies.address_invoice_town` (string,null, required)

  - `data.companies.address_invoice_country` (any, required)

  - `data.companies.address_invoice_is_delivery` (boolean, required)

  - `data.companies.delivery_person_attention_to` (string,null, required)

  - `data.companies.address_delivery_title` (string,null, required)

  - `data.companies.address_delivery_street` (string,null, required)

  - `data.companies.address_delivery_house` (string,null, required)

  - `data.companies.address_delivery_street2` (string,null, required)

  - `data.companies.address_delivery_zip` (string,null, required)

  - `data.companies.address_delivery_state` (string,null, required)

  - `data.companies.address_delivery_town` (string,null, required)

  - `data.companies.address_delivery_country` (any, required)

  - `data.companies.tags` (array)

  - `data.companies.contacts` (array)

  - `data.companies.custom_fields` (object, required)
    The key is the field name for your custom field, value type depends on the field type

  - `data.companies.created_at` (string, required)

  - `data.companies.updated_at` (string,null, required)

  - `data.companies.deleted_at` (string,null, required)

  - `data.companies.contact_company` (object)
    Added included via relationship (contact -> companies or company -> contacts)

  - `links` (array, required)

  - `meta` (object, required)

  - `meta.path` (string,null, required)
    Base path for paginator generated URLs.

  - `meta.per_page` (integer, required)
    Number of items shown per page.

  - `meta.next_cursor` (string,null, required)

  - `meta.next_cursor_url` (string,null, required)

  - `meta.prev_cursor` (string,null, required)

  - `meta.prev_cursor_url` (string,null, required)

## Response 401 fields (application/json):

  - `message` (string, required)
    Error overview.