Knowledge CenterAPI References

People

A Person represents an individual contact a customer, lead, or prospect. People can be associated with a Company and linked to Notes and Tasks.

Source:apiDocs/person.md
MethodPathDescription
POST/rest/peopleCreate a new person
GET/rest/people/{id}Get a person by ID
GET/rest/peopleList people
PATCH/rest/people/{id}Update a person
DELETE/rest/people/{id}Delete a person
POST/graphqlSearch people by name
POST/rest/people

Create a new person in your workspace. Only firstName is required all other fields are optional and can be added later via PATCH.

Body

name.firstNamerequiredstring

First name

name.lastNamestring

Last name

emails.primaryEmailstring

Primary email address

phones.primaryPhoneNumberstring

Phone number without country code

phones.primaryPhoneCallingCodestring

Calling code, e.g. "+1"

linkedinLink.primaryLinkUrlstring

LinkedIn profile URL

jobTitlestring

Job title or position

citystring

City

companyIdUUID

Associated company ID

ownerIdUUID

Workspace member who owns this record

Requestcurl
curl -X POST "https://app.usedalil.ai/rest/people" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": {
      "firstName": "John",
      "lastName": "Smith"
    },
    "emails": {
      "primaryEmail": "john.smith@example.com",
      "additionalEmails": []
    },
    "phones": {
      "primaryPhoneNumber": "5551234567",
      "primaryPhoneCountryCode": "US",
      "primaryPhoneCallingCode": "+1"
    },
    "linkedinLink": {
      "primaryLinkUrl": "https://linkedin.com/in/johnsmith",
      "primaryLinkLabel": "LinkedIn",
      "secondaryLinks": []
    },
    "jobTitle": "VP Sales",
    "city": "New York",
    "companyId": "550e8400-e29b-41d4-a716-446655440000"
  }'
Response · 200
{
  "data": {
    "createPerson": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": { "firstName": "John", "lastName": "Smith" },
      "emails": { "primaryEmail": "john.smith@example.com" },
      "jobTitle": "VP Sales",
      "createdAt": "2026-04-29T10:00:00.000Z"
    }
  }
}
GET/rest/people/{id}

Retrieve a single person by their UUID. Use depth=1 to include related records like their company and assigned tasks.

Parameters

idrequiredUUID

Person ID (path parameter)

depthnumber

0 = record only · 1 = + relations · 2 = + nested (slow)

Requestcurl
curl -G "https://app.usedalil.ai/rest/people/a1b2c3d4-..." \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "depth=1"
Response · 200
{
  "data": {
    "person": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": { "firstName": "John", "lastName": "Smith" },
      "emails": { "primaryEmail": "john.smith@example.com" },
      "jobTitle": "VP Sales",
      "city": "New York",
      "company": { "id": "...", "name": "Acme Corp" }
    }
  }
}
GET/rest/people

List people in your workspace with optional filtering, sorting, and cursor-based pagination. Default page size is 60.

Parameters

limitnumber

Records per page (default 60)

starting_afterUUID

Pagination cursor pass last record's ID

order_bystring

e.g. createdAt[DescNullsLast]

filterstring

Filter expression always URL-encode

depthnumber

0 = records only (default)

Requestcurl
# 20 most recently created people
curl -G "https://app.usedalil.ai/rest/people" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "limit=20" \
  --data-urlencode "order_by=createdAt[DescNullsLast]"

# People at a specific company
curl -G "https://app.usedalil.ai/rest/people" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "filter=companyId[eq]:company-uuid" \
  --data-urlencode "depth=1"
PATCH/rest/people/{id}

Update specific fields on a person. Send only the fields you want to change omitted fields are left unchanged.

Parameters

idrequiredUUID

Person ID (path parameter)

Requestcurl
curl -X PATCH "https://app.usedalil.ai/rest/people/a1b2c3d4-..." \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobTitle": "Senior VP Sales",
    "city": "San Francisco"
  }'
DELETE/rest/people/{id}

Permanently delete a person. This action cannot be undone. Associated notes and tasks are not deleted only the relation is removed.

Parameters

idrequiredUUID

Person ID (path parameter)

Requestcurl
curl -X DELETE "https://app.usedalil.ai/rest/people/a1b2c3d4-..." \
  -H "Authorization: Bearer YOUR_API_KEY"
Response · 200
{ "data": { "deletePerson": { "id": "a1b2c3d4-..." } } }

Filter Examples

filter=companyId[eq]:company-uuid          # At a specific company
filter=jobTitle[ilike]:engineer            # Job title contains "engineer"
filter=companyId[is]:NULL                 # No company assigned
filter=emails.primaryEmail[ilike]:john@example.com
filter=linkedinLink.primaryLinkUrl[ilike]:linkedin.com/in/johnsmith
filter=createdAt[gte]:2026-01-01T00:00:00.000Z

Common Gotchas

⚠
Name is nestedUse { "name": { "firstName": "John" } } a flat firstName field is ignored.
⚠
Link fields need full structure{ primaryLinkUrl, primaryLinkLabel, secondaryLinks: [] } a bare URL string won't work.
⚠
Phone search splits the numberFilter both phones.primaryPhoneCallingCode and phones.primaryPhoneNumber separately.
⚠
Email filter is nestedUse emails.primaryEmail[ilike]:value, not primaryEmail[ilike]:value.
⚠
id[in] needs bracketsUse id[in]:[uuid1,uuid2] brackets are required or you'll get a 500.
⚠
Always URL-encode filtersFilter strings contain [ ] : characters that break raw URLs.