> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revyops.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IDs and Lookups

> Which identifier to use to find a record, per object.

## Overview

RevyOps gives you more than one way to find a record. This page lists, per object, which identifiers the public API accepts and which endpoint to use for each.

## Contacts

| Identifier                    | How to look up                                                                                                                      |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Contact ID                    | `GET /public/v2/contacts/{contact_id}`                                                                                              |
| Email, LinkedIn URL, or phone | `GET /public/v2/contacts` with the `email`, `linkedin_url`, or `phone` query parameter                                              |
| First or last name            | `GET /public/v2/contacts` with the `firstname` or `lastname` query parameter                                                        |
| Company domain                | `GET /public/v2/contacts` with the `domain` query parameter (returns contacts at that company; excludes contacts without a company) |
| A custom field's value        | `GET /public/contacts/lookup-by-custom-field` with `field_name` and `field_value` (returns up to 100 matches)                       |

A contact's email, LinkedIn URL, and phone are each optional, but a contact needs at least one of them to be created. See [Create Contact](/api-reference/contacts/create-contact).

## Companies

| Identifier             | How to look up                                                                     |
| ---------------------- | ---------------------------------------------------------------------------------- |
| Company ID             | `GET /public/v2/companies/{company_id}`                                            |
| Domain                 | `GET /public/v2/companies` with the `domain` query parameter                       |
| Name                   | `GET /public/v2/companies` with the `name` query parameter                         |
| A custom field's value | `GET /public/companies/lookup-by-custom-field` with `field_name` and `field_value` |

A company's domain is its primary identifier: it's required to create a company, and it's what RevyOps uses to auto-associate a contact with a company from the contact's email address.

## People

| Identifier                                                           | How to look up                                                             |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Person ID                                                            | `GET /public/people/{person_id}`                                           |
| Exactly one of email, LinkedIn URL, or phone                         | `GET /public/people/lookup`                                                |
| Email, LinkedIn URL, phone, first name, last name, or company domain | `GET /public/people` (matches across every contact attached to the person) |

`GET /public/people/lookup` requires exactly one identifier. Use `GET /public/people` instead when you want to search across several fields at once, or don't have an exact identifier value.

## Emails

| Identifier                 | How to look up                                         |
| -------------------------- | ------------------------------------------------------ |
| Email record ID            | `GET /public/emails/{email_id}`                        |
| Contact, campaign, or type | `GET /public/emails` with the relevant query parameter |

## Looking Up by Custom Field

Contacts and companies can also be found by the value of a custom field you've defined, using:

* `GET /public/contacts/lookup-by-custom-field?field_name=...&field_value=...`
* `GET /public/companies/lookup-by-custom-field?field_name=...&field_value=...`

Both require `field_name` and `field_value` and return up to 100 matching records. This is useful when a custom field (an external CRM ID, for example) is the identifier you actually have on hand, rather than an email or domain. See [Custom Fields](/user-guide/custom-fields) for how fields are defined.

## company\_id Shortcut on Writes

When creating or updating a contact, the `company_id` field accepts either an integer company ID or a domain string. Passing a domain auto-resolves it to the matching company, so you don't have to look up the company ID yourself first.