> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts

> List, retrieve, search, and enrich contacts in your PG:AI workspace

## List Contacts

Retrieve a paginated list of contacts across your organization.

<ParamField query="page" type="integer" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="limit" type="integer" default="25">
  Number of contacts to return per page.
</ParamField>

**Permission:** `contacts:read`

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.getpg.ai/public-api/v1/contacts?page=1&limit=25" \
    -H "x-api-key: your_api_key"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "deb3474b-5836-492c-aca4-4e0ccc8afbae",
        "full_name": "Iain Donachie",
        "first_name": "Iain",
        "last_name": "Donachie",
        "current_job_title": "Head of Gift Cards UK & Ireland, Tesco",
        "linkedin_url": "https://www.linkedin.com/in/iain-donachie-6bb3406",
        "location": "Edinburgh, Scotland, United Kingdom",
        "country": "United Kingdom"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 25,
      "total": 1
    }
  }
  ```
</ResponseExample>

***

## Get Contact

Retrieve detailed information about a specific contact by ID, including work experience, education, and skills.

<ParamField path="contact_id" type="string" required>
  The unique identifier (UUID) of the contact.
</ParamField>

**Permission:** `contacts:read`

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.getpg.ai/public-api/v1/contacts/{contact_id}" \
    -H "x-api-key: your_api_key"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "deb3474b-5836-492c-aca4-4e0ccc8afbae",
    "full_name": "Iain Donachie",
    "first_name": "Iain",
    "last_name": "Donachie",
    "current_job_title": "Head of Gift Cards UK & Ireland, Tesco",
    "linkedin_url": "https://www.linkedin.com/in/iain-donachie-6bb3406",
    "location": "Edinburgh, Scotland, United Kingdom",
    "country": "United Kingdom",
    "headline": "Senior Product Leader with 18 years' experience driving strategic growth in Payments & Financial services.",
    "summary": "",
    "emails": [],
    "phones": [],
    "skills": [
      "Sales Planning",
      "P&L Management",
      "Banking",
      "Project Management",
      "Marketing Strategy"
    ],
    "company": {
      "name": "Gift Card & Voucher Association (GCVA)",
      "linkedin_id": "5010524"
    },
    "experience": [
      {
        "job_id": "9cc6abde-af26-4184-8f24-3caa4f96eb0a",
        "company_id": "304599c3-212f-4122-b84a-d655a1455d31",
        "company": "Tesco",
        "title": "Head of Gift Cards UK & Ireland, Tesco",
        "location": "Edinburgh, Scotland, United Kingdom",
        "start_date": "2025-02-01T00:00:00.000Z",
        "end_date": null,
        "is_current": true
      }
    ],
    "education": [
      {
        "degree": "BA Honours",
        "field_of_study": "Economics",
        "school": "University of Paisley",
        "start_year": 1993,
        "end_year": 1998
      }
    ],
    "created_at": "2026-04-01T12:47:07.324Z",
    "updated_at": null
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 404 theme={null}
  {
    "error": {
      "type": "not_found",
      "code": "contact_not_found",
      "message": "Contact not found"
    }
  }
  ```
</ResponseExample>

***

## Search Contacts

<Note>
  **Beta** — Search across all contacts in your workspace. Pass an empty body `{}` to return all contacts with pagination.
</Note>

<ParamField body="name" type="string">
  Filter contacts by name (partial match).
</ParamField>

<ParamField body="job_title" type="string">
  Filter contacts by job title.
</ParamField>

<ParamField body="company_id" type="string">
  Filter contacts by associated company UUID.
</ParamField>

<ParamField body="location" type="string">
  Filter contacts by location.
</ParamField>

<ParamField body="page" type="integer" default="1">
  Page number for pagination.
</ParamField>

<ParamField body="per_page" type="integer" default="25">
  Number of contacts per page.
</ParamField>

**Permission:** `contacts:read`

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.getpg.ai/public-api/v1/contacts/search" \
    -H "x-api-key: your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "job_title": "Chief Revenue Officer",
      "per_page": 10
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "contacts": [
      {
        "id": "deb3474b-5836-492c-aca4-4e0ccc8afbae",
        "full_name": "Iain Donachie",
        "current_job_title": "Head of Gift Cards UK & Ireland, Tesco",
        "linkedin_url": "https://www.linkedin.com/in/iain-donachie-6bb3406",
        "location": "Edinburgh, Scotland, United Kingdom"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 10,
      "total": 42,
      "total_pages": 5
    }
  }
  ```
</ResponseExample>

***

## Enrich Contact

<Note>
  **Beta** — Queue an enrichment job to discover phone numbers and email addresses for a contact. Returns `202 Accepted` immediately; poll `GET /operations/{public_operation_id}` for completion.
</Note>

<ParamField path="contact_id" type="string" required>
  The unique identifier (UUID) of the contact to enrich.
</ParamField>

**Permission:** `contacts:write`

<Warning>
  Enrichment consumes credits. A `402` response means your organization has insufficient credits.
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.getpg.ai/public-api/v1/contacts/{contact_id}/enrich/contact_info" \
    -H "x-api-key: your_api_key" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "public_operation_id": "op_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "accepted"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 402 theme={null}
  {
    "error": {
      "type": "payment_required",
      "code": "insufficient_credits",
      "message": "Your organization has insufficient credits to complete this enrichment."
    }
  }
  ```
</ResponseExample>