# Lookup Fields API
> Request selected person fields from email, phone, profile URL, or name.
**Base URL:** `https://api.nyne.ai`
**Endpoint:** `https://api.nyne.ai/person/lookup-fields`

---

## Overview
Request a targeted set of person fields instead of a full enrichment response. The response uses the same outer format as enrichment and includes only fields requested by the caller. POST queues the lookup and returns a request ID. GET returns the current or final status.
### What You Get
- **Targeted Fields:** Request only the fields or profile URL keys needed for the workflow.- **Flexible Inputs:** Use email, phone, profile URL, or name. Company, city, and state can improve name matching.- **Queued Workflow:** POST starts a lookup request and GET returns the current or final status.- **Clear Not Found:** No matching data returns HTTP 404 with status not_found instead of failed.
## Authentication

All requests require header authentication:

```
X-API-Key: YOUR_API_KEY
X-API-Secret: YOUR_API_SECRET
```

## Rate Limits

| Limit | Value |
|-------|-------|
| Per Minute | 60 requests |
| Per Hour | 1000 requests |
| Monthly | Varies by plan |

### Response Headers

Responses from endpoints that perform rate-limit checks include both legacy and standard rate-limit headers:

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Active per-minute or per-hour limit |
| `X-RateLimit-Remaining` | Remaining requests in the active window |
| `X-RateLimit-Reset` | Unix timestamp when the active window resets |
| `RateLimit-Limit` | Active per-minute or per-hour limit |
| `RateLimit-Remaining` | Remaining requests in the active window |
| `RateLimit-Reset` | Seconds until the active window resets |
| `Retry-After` | Seconds to wait before retrying; present on HTTP `429` rate-limit responses |

Monthly quota responses include quota-specific headers when available:

| Header | Description |
|--------|-------------|
| `X-Quota-Limit` | Monthly request or credit limit |
| `X-Quota-Used` | Amount used in the current billing cycle |
| `X-Quota-Remaining` | Amount remaining in the current billing cycle |
| `X-Quota-Reset` | Unix timestamp when the current billing cycle resets |

## Credit Usage

- **Email Lookup Fields:** 3 credits per requested email field such as best_work_email or best_personal_email
- **Phone Lookup Field:** 3 credits per requested mobile field
- **Other Lookup Fields:** 3 credits per other requested field or requested profile URL item
> Credits are summed across requested lookup-field catalog items. For example, requesting best_work_email and mobile uses the email-field price plus the phone-field price. Validation errors and status checks are not charged.
---

## POST /person/lookup-fieldsCreate a lookup request for selected person fields. Provide email, phone, social_media_url, or name. If only name is provided, company, city, and state can improve match quality.
### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | No | Email address |
| `phone` | string | No | Phone number |
| `social_media_url` | string | No | Profile URL |
| `name` | string | No | Full name. Required when email, phone, and social_media_url are absent. |
| `company` | string | No | Company context for name lookup |
| `city` | string | No | City context for name lookup |
| `state` | string | No | State context for name lookup |
| `fields` | array or string | No | Field selectors to return. Supported: displayname, firstname, lastname, best_work_email, best_personal_email, mobile, address, location, headline, current_company, current_title, photo_url. |
| `profile_urls` | array or string | No | Profile URL keys to return under social_profiles. Keys must start with a letter and may contain lowercase letters, numbers, and underscores. Maximum 10. |
| `probability_score` | boolean | No | Return match probability when available |
| `callback_url` | string | No | URL to receive results asynchronously |

> **Required:** At least one of email, phone, social_media_url, or name is required. At least one item in fields or profile_urls is required.
### Request Examples

**With Advanced Features:**

```json
{
  "name": "Jane Example",
  "company": "Example Company",
  "city": "San Francisco",
  "state": "CA",
  "fields": ["current_company", "current_title"],
  "probability_score": true
}
```

**Basic Request:**

```json
{
  "email": "person@example.org",
  "fields": ["current_company", "current_title"]
}
```

**Name-Based Lookup:**

```json
{
  "name": "Jane Example",
  "company": "Example Company",
  "fields": ["best_work_email", "current_company", "current_title"],
  "profile_urls": ["linkedin"],
  "probability_score": true
}
```
Name-only lookups return the best available match. Add company or location context when the name is common.
### Code Examples

**cURL:**

```bash
curl -X POST https://api.nyne.ai/person/lookup-fields \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "person@example.org",
    "fields": ["best_work_email", "mobile"]
  }'
```

### Response Example

```json
{
  "success": true,
  "data": {
    "request_id": "abc123...",
    "status": "queued",
    "completed": false,
    "result": null,
    "error": null
  }
}
```

---

## GET /person/lookup-fields
Check the status of a request.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `request_id` | string | Yes | The request ID returned by POST /person/lookup-fields |

### Request Example

```
GET /person/lookup-fields?request_id=abc123...
```

### Response Example

```json
{
  "success": true,
  "data": {
    "request_id": "abc123...",
    "status": "completed",
    "completed": true,
    "result": {
      "best_work_email": "person@company.example",
      "fullphone": [
        {
          "fullphone": "(555) 123-4567",
          "phone_type": "mobile",
          "type": "mobile"
        }
      ],
      "organizations": [
        {
          "name": "Example Company",
          "title": "VP Technology",
          "endDate": "Present",
          "endDate_formatted": {
            "is_current": true
          }
        }
      ],
      "social_profiles": {
        "linkedin": {
          "url": "https://www.linkedin.com/in/person"
        }
      }
    },
    "error": null
  }
}
```

---

## Response Format

All API responses follow a consistent JSON format. All fields in enrichment results are **optional** and only included when data is available:
- The result object contains only requested fields and requested social profile URLs that were found.- The mobile selector returns phone data in fullphone format. Current company and title selectors return organization data in organizations format.- No matching data returns HTTP 404 with status not_found, not failed. This is a completed lookup response.- Status checks do not charge credits.
---

## Error Codes

| HTTP Code | Error Code | Description |
|-----------|------------|-------------|
| 400 | `missing_parameters` | No lookup input was provided |
| 400 | `invalid_fields` | Unsupported field requested |
| 400 | `invalid_profile_urls` | Unsupported profile URL key format |
| 400 | `invalid_callback_url` | Callback URL could not be used |
| 401 | `invalid_credentials` | API key or secret is incorrect |
| 402 | `insufficient_credits` | Not enough credits available |
| 403 | `access_denied` | The request is not available to the authenticated account |
| 403 | `subscription_required` | The account does not include access to this API |
| 404 | `request_not_found` | Status request ID was not found |
| 429 | `rate_limit_exceeded` | Rate limit exceeded |

---

## Related APIs
- **Person Enrichment API** - Full person profile lookup -> `https://api.nyne.ai/documentation/person/enrichment`
- **Person Search API** - Search for people by criteria -> `https://api.nyne.ai/documentation/person/search`