Lookup Contact

Search for a contact by name, email, phone, or ID

POST /apis/v2/public/crm/lookupContact

Searches contacts by matching a free-text string against name, email, phone, role, and entity name. Returns the first matching contact with full related data (entity, notes, profile, and signals are always included).

Requires a valid `api_key` and `developer_secret` in the JSON request body. Requests must originate from a whitelisted IP address.

Parameters

Name	In	Type	Required	Description
`api_key`	body	`string`	Yes	Your Zyntro API key
`developer_secret`	body	`string`	Yes	Your developer secret (zdk_XXX). Issued during developer onboarding.
`org_id`	body	`string`	Yes	Your organization UUID
`search_string`	body	`string`	Yes	Free-text search term. Matched against contact ID, first name, last name, role label, primary email, secondary email, primary phone, secondary phone, and entity name.

Info: Unlike **Fetch Contact**, this endpoint does not require a `member_id`. It also automatically includes all related data (entity, notes, profile, signals) — there are no `include_*` flags.

Request Body

Content-Type: application/json

Example

json

{
    "org_id": "YOUR_ORG_ID",
    "api_key": "YOUR_API_KEY",
    "search_string": "[email protected]",
    "developer_secret": "YOUR_DEVELOPER_SECRET"
}

Code Samples

bash

curl -X POST https://app.zyntrohq.com/apis/v2/public/crm/lookupContact \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "developer_secret": "YOUR_DEVELOPER_SECRET",
    "org_id": "YOUR_ORG_ID",
    "search_string": "[email protected]"
  }'

javascript

const response = await fetch('https://app.zyntrohq.com/apis/v2/public/crm/lookupContact', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY',
    developer_secret: 'YOUR_DEVELOPER_SECRET',
    org_id: 'YOUR_ORG_ID',
    search_string: '[email protected]'
  })
});
const data = await response.json();

Response

200 Contact found

json

{
    "data": {
        "notes": [],
        "entity": {
            "entity_name": "Acme Corp",
            "entity_label": "Company",
            "entity_website": "https://acme.com"
        },
        "contact": {
            "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "contact_name": "Jane Smith",
            "contact_email": "[email protected]",
            "contact_phone": "+1-555-0123",
            "contact_stage": "Nurturing",
            "contact_source": "Website Form",
            "contact_status": "Active",
            "contact_last_name": "Smith",
            "contact_first_name": "Jane"
        },
        "signals": null,
        "contact_profile": null
    },
    "status": "success"
}

200 No matching contact

json

{
    "data": [
        "No such contact"
    ],
    "status": "error"
}

Errors

Code	Message	Resolution
`MISSING_API_KEY`	Missing service instance The `api_key` field is missing or empty.	Include your API key in the request body.
`INVALID_API_KEY`	Invalid API Key No active user matches the provided key.	Verify your API key in Me > API & Webhooks.
`IP_NOT_WHITELISTED`	IP address not whitelisted The request originated from an IP not in the key's allowed list.	Contact your client to add your IP to the developer key whitelist.
`INVALID_DEVELOPER_SECRET`	Invalid developer_secret The developer secret does not match any active key.	Verify your developer secret. If lost, have your client revoke and reissue the key.
`MISSING_DEVELOPER_SECRET`	Missing developer_secret The `developer_secret` field is missing or empty.	Include your developer secret in the request body. This is issued during developer onboarding.
`USER_INACTIVE`	User is not active The account is deactivated.	Contact your organization admin.
`MISSING_SEARCH`	Missing search string The `search_string` field is missing or empty.	Provide a search term — an email, name, phone number, or contact ID.
`MISSING_ORG_ID`	Missing org ID The `org_id` field is missing or empty.	Include your organization ID.
`NOT_FOUND`	No such contact No contact matched the search string in this organization.	Try a different search term or verify the contact exists.

Tip: This endpoint returns the **first** matching contact. If multiple contacts could match your search term (e.g., a common first name), use a more specific value like an email address or phone number to get the right result.

4 min read Updated May 26, 2026

Navigation

Lookup Contact

Parameters

Request Body

Example

Code Samples

Response

Errors