API Endpoints

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-500, 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)
isSolutionProvider boolean No Filter to solution providers (true or false)

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",
        "jobTitle": "Head of Platform",
        "bio": "Twenty years of making databases behave.",
        "skills": ["PostgreSQL", "Kubernetes"],
        "linkedinUrl": "https://linkedin.com/in/johndoe",
        "avatarUrl": "https://cdn.example.com/john.png",
        "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
  }
}

Profile Fields

Person responses include a profile block intended for public-facing directories and websites: jobTitle, bio, skills, linkedinUrl, and avatarUrl. All are optional and may be null, except skills, which is a string array defaulting to [].

These fields are read-only; they are not accepted by POST or PATCH.

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",
  "isSolutionProvider": false,
  "isConnector": false,
  "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
isSolutionProvider boolean No Mark as a solution provider (defaults to false)
isConnector boolean No Mark as a connector (defaults to false)
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.

Accepts the same fields as Create Person, except email and firstName are optional and companyName is not supported. Changing isSolutionProvider or isConnector is recorded in the person's activity timeline.

Request Body 

{
  "firstName": "Jane",
  "phoneNumber": "+1 555-987-6543",
  "isConnector": true,
  "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://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://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://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://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
Previous
Health
Next
Companies
Introzy API Documentation