Find Contact by Email

Beta

POST/v1/sales/contacts/actions/find-by-email

Idempotent with Idempotency-Key header. Learn more

Finds the contacts that match an email address.

Only active people on accounts you have a relationship with are returned — your customers, your suppliers, or your own account. A match's relationship says how you relate to the account it belongs to. The same person can be set up on several accounts under one email, so this can return more than one match, and an email that belongs to no one you deal with simply returns no matches rather than an error.

Permissions requiredValues:customers:read

The role behind your API key or agent must grant every one of these permissions.

relationships[]optional arrayenumValues:customersupplierself

Restricts the results to matches whose relationship to your account is one of these.

Leaving it out returns matches of every relationship.

include[]optional arrayenumValues:account_useraccount_user.useraccount_user.role

Sub-objects to expand in the response. When omitted, sub-objects are returned as null.

emailstring

The email address to look up.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of contact_match

Resources in this page.

idstring

Contact match ID.

This is the matched account user's ID, so the same value also appears as account_user.id.

objectstringenumValues:contact_match

Resource type identifier.

relationshipstringenumValues:customersupplierself

How you relate to the account this contact belongs to.

customer: the account is one of your customers.
supplier: the account is one of your suppliers.
self: the account is your own.

emailstring

The email address that was matched.

account_useraccount_userExpandablenullable

The matched account user.

idstring

Account user ID.

objectstringenumValues:account_user

Resource type identifier.

statusstringenumValues:activedisabledremoved

The current state of this user's membership in the account.

active: the user can sign in to the account and occupies one of the plan's seats.
disabled: the user is locked out of the account and their sessions have been revoked, but the membership is retained.
removed: the membership has been soft-deleted; it is hidden from listings by default and can be restored with the activate action.

roleroleExpandablenullable

The role that determines what this user is permitted to do in the account.

idstring

Role ID.

objectstringenumValues:role

Resource type identifier.

namestring

Display name of the role.

Unique within the account.

typestringenumValues:adminuserscanner

The kind of role.

The type gates behavior that individual permissions do not cover, and some actions are reserved for a single role type.

admin: full administrative access. Sensitive areas such as API keys, billing, and third-party integrations are restricted to admins no matter what permissions another role holds.
user: a custom role tailored to a specific need, with its permissions defined explicitly. Roles created through the API always have this type.
scanner: the role used by shop-floor scanning stations, assigned automatically when a scanning-station user is created.
sales_rep: a role for sales representatives. Order analytics are scoped to the rep's own orders.
agent: a role assigned to an automated agent rather than a person.

ownerownernullable

Provenance of this role.

System-owned roles are platform-provided defaults shared across all accounts and cannot be updated or deleted; account-owned roles are custom to your account.

Always returned as null in this endpoint.

permissionsarray of stringnullable

Permissions granted by this role, in {permission}:{action} format, such as customers:read.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

departmentdepartmentExpandablenullable

The department this user belongs to within the account.

idstring

Department ID.

objectstringenumValues:department

Resource type identifier.

namestring

Display name of the department.

Unique within the account.

notesstringnullable

Free-form notes about the department.

locationlocationnullable

The storage location where this department operates.

Always returned as null in this endpoint.

scanning_stationslistnullable

Scanning stations in this department.

Always returned as null in this endpoint.

machineslistnullable

Machines in this department.

Always returned as null in this endpoint.

labor_rateratenullable

Hourly labor rate for work done in this department, such as a changeover technician.

Production scheduling costs changeovers with the constraint department's rate when one is set, falling back to the account-wide changeover labor rate setting.

Always returned as null in this endpoint.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last update timestamp.

useruserExpandablenullable

The underlying user profile, shared across every account this person belongs to.

idstring

User ID.

objectstringenumValues:user

Resource type identifier.

emailstringnullable

Email address the user signs in with and receives platform email at.

namestringnullable

User's full display name.

usernamestringnullable

Username the user can sign in with instead of their email address.

Usernames are unique across the whole platform, not just within your account.

email_verified_atstring (date-time)nullable

When the user verified their email address.

image_urlstringnullable

Location of the user's profile image.

For photos uploaded through the API this holds an internal path rather than a fetchable image URL; call Get User Photo URL to obtain a temporary link to the image itself.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

is_commission_eligibleboolean

Whether this user can be assigned as a sales representative on orders, territories, and targets.

Independent of the sales_rep role type, which still scopes analytics and hides cost. Users with the sales_rep role are always eligible.

last_used_atstring (date-time)nullable

When the user last accessed this account.

created_atstring (date-time)

When the account user was created.

updated_atstring (date-time)

When the account user was last updated.

accountaccountExpandablenullable

The account this contact belongs to.

idstring

Account ID.

objectstringenumValues:account

Resource type identifier.

namestring

The account's display name.

default_billing_addressaddressnullable

The address billed by default on orders for this account.

Always returned as null in this endpoint.

default_shipping_addressaddressnullable

The address shipped to by default on orders for this account.

Always returned as null in this endpoint.

brandingaccount_brandingnullable

Customer-facing branding for the account, such as the logo, support contacts, and social links.

Always returned as null in this endpoint.

portalaccount_portalnullable

The account's customer portal settings, including the portal URL slug.

Always returned as null in this endpoint.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

Responses

200

Successful response for Find Contact by Email

Find Contact by Email

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const listContactMatch = await client.sales.contacts.actions.findByEmail({
  email: 'buyer@acme-co.example',
});

console.log(listContactMatch.data);

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const listContactMatch = await client.sales.contacts.actions.findByEmail({
  email: 'buyer@acme-co.example',
});

console.log(listContactMatch.data);

200 example

{
  "object": "list",
  "page_info": {
    "next_page_url": "/v1/sales/contacts/actions/find-by-email?cursor=eyJjIjoiMjAyNi0wNS0xMFQwMDowMDowMFoiLCJzIjoiYWN1c19lNXp1OGJkZTB6M2giLCJkIjoiZiJ9.Vp-pg4ZBXWJYOL5NouwXPXVqqC8QeWIT8JqDne98rbo",
    "previous_page_url": null,
    "has_next_page": true,
    "has_prev_page": false
  },
  "data": [
    {
      "id": "acus_e5zu8bde0z3h",
      "object": "contact_match",
      "relationship": "customer",
      "email": "buyer@acme-co.example",
      "account_user": {
        "id": "acus_e5zu8bde0z3h",
        "object": "account_user",
        "status": "active",
        "role": {
          "id": "rl_3xknmfqflhvb",
          "object": "role",
          "name": "Admin",
          "type": "admin",
          "owner": null,
          "permissions": [
            "customers:create",
            "customers:read",
            "customers:update",
            "customers:delete"
          ],
          "created_at": "2026-05-10T00:00:00Z",
          "updated_at": "2026-05-10T00:23:00Z"
        },
        "department": {
          "id": "dp_m0jayebxnkos",
          "object": "department",
          "name": "Fabrication",
          "notes": null,
          "location": null,
          "scanning_stations": null,
          "machines": null,
          "labor_rate": null,
          "created_at": "2026-05-10T00:00:00Z",
          "updated_at": "2026-05-10T00:23:00Z"
        },
        "user": {
          "id": "us_43irtlt2ajz6",
          "object": "user",
          "email": "jdoe@openmrp.ai",
          "name": "John Doe",
          "username": "jdoe",
          "email_verified_at": "2026-06-10T00:00:00Z",
          "image_url": "https://cdn.openmrp.ai/avatars/us_43irtlt2ajz6.jpg",
          "created_at": "2026-05-10T00:00:00Z",
          "updated_at": "2026-05-10T00:23:00Z"
        },
        "is_commission_eligible": false,
        "last_used_at": "2026-05-10T00:23:00Z",
        "created_at": "2026-05-10T00:00:00Z",
        "updated_at": "2026-05-10T00:23:00Z"
      },
      "account": {
        "id": "ac_ykxoradjoeb3",
        "object": "account",
        "name": "Acme Inc.",
        "default_billing_address": null,
        "default_shipping_address": null,
        "branding": null,
        "portal": null,
        "created_at": "2026-05-10T00:00:00Z",
        "updated_at": "2026-05-10T00:23:00Z"
      }
    }
  ]
}

{
  "object": "list",
  "page_info": {
    "next_page_url": "/v1/sales/contacts/actions/find-by-email?cursor=eyJjIjoiMjAyNi0wNS0xMFQwMDowMDowMFoiLCJzIjoiYWN1c19lNXp1OGJkZTB6M2giLCJkIjoiZiJ9.Vp-pg4ZBXWJYOL5NouwXPXVqqC8QeWIT8JqDne98rbo",
    "previous_page_url": null,
    "has_next_page": true,
    "has_prev_page": false
  },
  "data": [
    {
      "id": "acus_e5zu8bde0z3h",
      "object": "contact_match",
      "relationship": "customer",
      "email": "buyer@acme-co.example",
      "account_user": {
        "id": "acus_e5zu8bde0z3h",
        "object": "account_user",
        "status": "active",
        "role": {
          "id": "rl_3xknmfqflhvb",
          "object": "role",
          "name": "Admin",
          "type": "admin",
          "owner": null,
          "permissions": [
            "customers:create",
            "customers:read",
            "customers:update",
            "customers:delete"
          ],
          "created_at": "2026-05-10T00:00:00Z",
          "updated_at": "2026-05-10T00:23:00Z"
        },
        "department": {
          "id": "dp_m0jayebxnkos",
          "object": "department",
          "name": "Fabrication",
          "notes": null,
          "location": null,
          "scanning_stations": null,
          "machines": null,
          "labor_rate": null,
          "created_at": "2026-05-10T00:00:00Z",
          "updated_at": "2026-05-10T00:23:00Z"
        },
        "user": {
          "id": "us_43irtlt2ajz6",
          "object": "user",
          "email": "jdoe@openmrp.ai",
          "name": "John Doe",
          "username": "jdoe",
          "email_verified_at": "2026-06-10T00:00:00Z",
          "image_url": "https://cdn.openmrp.ai/avatars/us_43irtlt2ajz6.jpg",
          "created_at": "2026-05-10T00:00:00Z",
          "updated_at": "2026-05-10T00:23:00Z"
        },
        "is_commission_eligible": false,
        "last_used_at": "2026-05-10T00:23:00Z",
        "created_at": "2026-05-10T00:00:00Z",
        "updated_at": "2026-05-10T00:23:00Z"
      },
      "account": {
        "id": "ac_ykxoradjoeb3",
        "object": "account",
        "name": "Acme Inc.",
        "default_billing_address": null,
        "default_shipping_address": null,
        "branding": null,
        "portal": null,
        "created_at": "2026-05-10T00:00:00Z",
        "updated_at": "2026-05-10T00:23:00Z"
      }
    }
  ]
}

Find Contact by Email

Authorization

Query Parameters

Request Body

Returns

Responses