People
The People API allows you to create, read, update people (contacts) and trigger AI-powered profile enrichment. Supports custom fields and nested notes.
List People
GET /api/people
Retrieves a paginated list of people visible to the authenticated user.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
limit |
integer | No | Number of people to return (1-100, default: 50) |
offset |
integer | No | Number of people to skip (default: 0) |
search |
string | No | Search by name or email |
companyId |
string | No | Filter by company ID (UUID) |
Response
Success Response (200)
{
"success": true,
"data": {
"people": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "john@acme.com",
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "+1 555-123-4567",
"address": "123 Main St, San Francisco, CA 94102",
"isFullUser": false,
"customFields": {
"cf_department": "Engineering"
},
"company": {
"id": "company-uuid",
"name": "Acme Inc",
"industry": "Technology"
},
"createdAt": "2024-01-15T10:00:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z"
}
],
"total": 150,
"limit": 50,
"offset": 0,
"hasMore": true
}
}
Create Person
POST /api/people
Creates a new person in your organization.
Request Body
{
"email": "john@acme.com",
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "+1 555-123-4567",
"address": "123 Main St, San Francisco, CA 94102",
"companyName": "Acme Inc",
"customFields": {
"cf_department": "Engineering"
}
}
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
email |
string | Yes | Valid email address |
firstName |
string | Yes | First name (1-100 characters) |
lastName |
string | No | Last name (max 100 characters) |
phoneNumber |
string | No | Phone number (max 50 characters) |
address |
string | No | Full address (max 500 characters) |
companyId |
string | No | Link to existing company (UUID) |
companyName |
string | No | Auto-create company with this name |
customFields |
object | No | Custom field key-value pairs |
Response
Success Response (201)
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "john@acme.com",
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "+1 555-123-4567",
"address": "123 Main St, San Francisco, CA 94102",
"isFullUser": false,
"customFields": {
"cf_department": "Engineering"
},
"company": {
"id": "company-uuid",
"name": "Acme Inc"
},
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z"
},
"message": "Person created successfully"
}
Error Response (409)
{
"success": false,
"error": "A person with this email already exists in your organization"
}
Get Person
GET /api/people/{id}
Retrieves details for a specific person including custom fields.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Person UUID |
Response
Success Response (200)
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "john@acme.com",
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "+1 555-123-4567",
"address": "123 Main St, San Francisco, CA 94102",
"latitude": 37.7749,
"longitude": -122.4194,
"isConnector": false,
"isSolutionProvider": false,
"isFullUser": false,
"customFields": {
"cf_department": "Engineering",
"cf_lead_source": "Conference"
},
"company": {
"id": "company-uuid",
"name": "Acme Inc",
"industry": "Technology",
"website": "https://acme.com"
},
"createdAt": "2024-01-15T10:00:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z"
}
}
Update Person
PATCH /api/people/{id}
Updates an existing person. Only provided fields are updated. Custom fields are merged with existing values.
Request Body
{
"firstName": "Jane",
"phoneNumber": "+1 555-987-6543",
"customFields": {
"cf_department": "Product"
}
}
Response
Success Response (200)
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "john@acme.com",
"firstName": "Jane",
"lastName": "Doe",
"phoneNumber": "+1 555-987-6543",
"customFields": {
"cf_department": "Product",
"cf_lead_source": "Conference"
}
},
"message": "Person updated successfully"
}
Note: Email cannot be changed for people with active user accounts.
Enrich Person
POST /api/people/{id}/enrich
Triggers AI enrichment for a person. The enrichment job runs asynchronously and updates the person's profile with professional information gathered from public sources.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Person UUID |
Response
Success Response (200)
{
"success": true,
"data": {
"jobId": "job_abc123",
"personId": "550e8400-e29b-41d4-a716-446655440000",
"personName": "John Doe",
"personEmail": "john@acme.com"
},
"message": "Enrichment job created for John Doe"
}
Error Response (400)
{
"success": false,
"error": "Person email is required for enrichment"
}
Example Usage
# List people with search
curl -X GET "https://beta-api.introzy.com/api/people?search=john&limit=10" \
-H "Authorization: Bearer introzy_your_api_key"
# Create a new person with custom fields
curl -X POST "https://beta-api.introzy.com/api/people" \
-H "Authorization: Bearer introzy_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"email": "jane@acme.com",
"firstName": "Jane",
"lastName": "Smith",
"companyName": "Acme Inc",
"customFields": {
"cf_department": "Sales"
}
}'
# Update a person
curl -X PATCH "https://beta-api.introzy.com/api/people/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer introzy_your_api_key" \
-H "Content-Type: application/json" \
-d '{"phoneNumber": "+1 555-123-4567"}'
# Trigger enrichment
curl -X POST "https://beta-api.introzy.com/api/people/550e8400-e29b-41d4-a716-446655440000/enrich" \
-H "Authorization: Bearer introzy_your_api_key"
Related Endpoints
- Notes — Manage notes on people via
GET/POST /api/people/{personId}/notes - Custom Fields — Define custom field schemas via
GET/POST /api/people/custom-fields