Contacts

Contacts are at the heart of Beamery's talent management platform. They represent individual talent profiles - whether they're candidates, employees, or alumni. This page covers how to work with contacts programmatically through our API.

The contact model

The contact model in Beamery stores comprehensive information about individuals in your talent pipeline as MongoDB documents, including their professional details, skills, experience, and engagement history.

Core Properties

Name
id
Type
string
Description
Beamery-specific unique identifier for the contact.
Name
firstName
Type
string
Description
Contact's first name.
Name
lastName
Type
string
Description
Contact's last name.
Name
fullName
Type
string
Description
Complete formatted name of the contact.
Name
headline
Type
string
Description
Professional headline or tagline.
Name
summary
Type
string
Description
Professional summary or bio.
Name
createdAt
Type
timestamp
Description
When the contact was created in the system.
Name
updatedAt
Type
timestamp
Description
When the contact was last updated.

Contact Information

Name
emails
Type
array
Description
Array of email objects, where each email entry contains:
- id Unique identifier for the email entry
- value Email address
- type Email type (e.g., "primary", "work", "personal")
- source Source of the email information
Name
phoneNumbers
Type
array
Description
Array of phone number objects, where each phone entry contains:
- id Unique identifier for the phone number entry
- value Phone number string (e.g., "07111111111")
- type Phone type ("mobile", "home", "work")
Name
links
Type
array
Description
Array of link objects, where each link entry contains:
- id Unique identifier for the link entry
- value Full URL to the social profile or website
- service Platform name (e.g., "linkedin", "twitter", "github")
- type Link type (typically "social")
- username Platform-specific username or handle
- userId Platform-specific user ID
- bio Profile bio or description text
- following Number of people the user follows (for applicable platforms)
Name
locations
Type
array
Description
Array of location objects, where each location entry contains:
- id Unique identifier for the location entry
- address Full address string (e.g., "London, UK")
- city City name
- country Full country name
- countryCode Two-letter ISO 3166-1 alpha-2 country code (e.g., "GB", "US")
- geometry GeoJSON geometry object with coordinates
  - type Always "Point" for contact locations
  - coordinates Array of [longitude, latitude] coordinates
Name
primaryLocation
Type
string
Description
ID of the primary location entry.

Example Structure

{
  "emails": [
    {
      "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
      "value": "john.doe@example.com",
      "type": "primary",
      "source": "manual"
    }
  ],
  "phoneNumbers": [
    {
      "id": "f8e9d0c1-b2a3-4567-8901-23456789cdef",
      "value": "07111111111",
      "type": "mobile"
    }
  ],
  "links": [
    {
      "id": "89b5494d-9217-4169-b847-e26a0964cb5c",
      "value": "https://www.linkedin.com/in/matthew-w-noble",
      "service": "linkedin",
      "type": "social",
      "username": "fIRG3DU0aG",
      "userId": "fIRG3DU0aG",
      "bio": "Matthew is a data scientist and PC enthusiast...",
      "following": 500
    }
  ],
  "locations": [
    {
      "id": "2c4d6e8f-a1b2-4c3d-9e0f-123456789abc",
      "address": "London, UK",
      "city": "London",
      "country": "United Kingdom",
      "countryCode": "GB",
      "geometry": {
        "type": "Point",
        "coordinates": [-0.12, 51.5]
      }
    }
  ],
  "primaryLocation": "2c4d6e8f-a1b2-4c3d-9e0f-123456789abc"
}

Professional Experience

Name
experiences
Type
array
Description
Array of experience objects, where each experience entry contains:
- id Unique identifier for the experience entry
- title Job title or position
- company Company name where the person worked
- location Geographic location of the job
- startDate Employment start date
- endDate Employment end date (null if current)
- isCurrent Boolean indicating if this is the current role
- description Job description or responsibilities
- skills Array of skill objects used or developed in this role, each containing:
  - id Skill ID from the company job architecture graph
  - value Skill name or label
Name
primaryExperience
Type
string
Description
ID of the primary/current experience entry.

Example Structure

{
  "experiences": [
    {
      "id": "3f4a5b6c-7d8e-4901-b234-56789abcdef0",
      "title": "Senior Python Developer",
      "company": "TechCorp",
      "location": "San Francisco, CA",
      "startDate": "2021-03-01",
      "endDate": null,
      "isCurrent": true,
      "description": "Leading backend development for cloud services",
      "skills": [
        {
          "id": "4d5e6f7a-8b9c-4012-9345-6789abcdef01",
          "value": "Python"
        },
        {
          "id": "8f9e0d1c-2b3a-4567-a890-123456789bcd",
          "value": "Django"
        },
        {
          "id": "2a3b4c5d-6e7f-4890-b123-456789abcdef",
          "value": "AWS"
        }
      ]
    },
    {
      "id": "9e8d7c6b-5a49-4382-9f10-123456789abc",
      "title": "Python Developer",
      "company": "StartupXYZ",
      "location": "Remote",
      "startDate": "2018-06-01",
      "endDate": "2021-02-28",
      "isCurrent": false,
      "description": "Full-stack development using Django",
      "skills": [
        {
          "id": "4d5e6f7a-8b9c-4012-9345-6789abcdef01",
          "value": "Python"
        },
        {
          "id": "1b2c3d4e-5f6a-4789-9012-3456789abcde",
          "value": "JavaScript"
        },
        {
          "id": "5f6a7b8c-9d0e-4123-8456-789abcdef012",
          "value": "React"
        }
      ]
    }
  ],
  "primaryExperience": "3f4a5b6c-7d8e-4901-b234-56789abcdef0"
}

Education Background

Name
education
Type
array
Description
Array of education objects, where each education entry contains:
- id Unique identifier for the education entry
- institution Name of the educational institution
- degree Degree type (Bachelor's, Master's, PhD, etc.)
- field Field of study or major
- startDate Education start date
- endDate Education end date (graduation date)
- grade GPA or grade achieved
- activities Extracurricular activities or achievements
Name
primaryEducation
Type
string
Description
ID of the primary education entry.

Example Structure

{
  "education": [
    {
      "id": "b5c6d7e8-f9a0-4123-8456-789abcdef012",
      "institution": "UC Berkeley",
      "degree": "Bachelor of Science",
      "field": "Computer Science",
      "startDate": "2014-09-01",
      "endDate": "2018-05-15",
      "grade": "3.8",
      "activities": ["Computer Science Club", "Hackathon Winner"]
    },
    {
      "id": "7a8b9c0d-e1f2-4345-a678-90123456789f",
      "institution": "Stanford University",
      "degree": "Master of Science",
      "field": "Machine Learning",
      "startDate": "2018-09-01",
      "endDate": "2020-06-15",
      "grade": "3.9",
      "activities": ["AI Research Lab", "Teaching Assistant"]
    }
  ],
  "primaryEducation": "b5c6d7e8-f9a0-4123-8456-789abcdef012"
}

Skills and Expertise

Name
skills
Type
array
Description
Array of skill objects, where each skill entry contains:
- id Skill ID from the company job architecture graph (maps to Beamery knowledge graph ID)
- value Skill name or label

Example Structure

{
  "skills": [
    {
      "id": "4d5e6f7a-8b9c-4012-9345-6789abcdef01",
      "value": "Python"
    },
    {
      "id": "8f9e0d1c-2b3a-4567-a890-123456789bcd",
      "value": "Machine Learning"
    },
    {
      "id": "2a3b4c5d-6e7f-4890-b123-456789abcdef",
      "value": "Data Analysis"
    }
  ]
}

Languages

Name
languages
Type
array
Description
Array of language objects, where each language entry contains:
- id Unique identifier for the language entry
- value Language name (e.g., "Japanese", "Spanish", "French")
- proficiency Proficiency level ("Basic", "Intermediate", "Advanced", "Native")
- languageCode Two-letter ISO 639-1 language code (e.g., "ja", "es", "fr")

Example Structure

{
  "languages": [
    {
      "id": "8175469f-5b75-410f-abe8-5d18daa424a3",
      "value": "Japanese",
      "proficiency": "Basic",
      "languageCode": "ja"
    },
    {
      "id": "6e7f8a9b-0c1d-4234-9567-89abcdef0123",
      "value": "Spanish",
      "proficiency": "Intermediate",
      "languageCode": "es"
    },
    {
      "id": "0d1e2f3a-4b5c-4678-a901-23456789cdef",
      "value": "French",
      "proficiency": "Advanced",
      "languageCode": "fr"
    }
  ]
}

Categorization and Metadata

Name
tags
Type
array
Description
Array of tag objects, where each tag entry contains:
- id Unique identifier for the tag entry
- value Tag name or label (e.g., "Data Science", "Senior", "Remote")
Name
sources
Type
array
Description
Array of source objects, where each source entry contains:
- id Unique identifier for the source (optional)
- value Where the contact was sourced from, such as a job board, website, or other resources (optional)
Name
pools
Type
array
Description
Array of talent pool IDs the contact belongs to.

Example Structure

{
  "tags": [
    {
      "id": "b8f8119d-c129-4017-a444-d75713ebd143",
      "value": "Data Science"
    },
    {
      "id": "4c5d6e7f-8a9b-4012-9345-6789abcdef01",
      "value": "Senior"
    },
    {
      "id": "8b9c0d1e-2f3a-4567-a890-123456789bcd",
      "value": "Remote"
    }
  ],
  "sources": [
    {
      "id": "1a2b3c4d-5e6f-4789-9012-3456789abcde",
      "value": "LinkedIn"
    },
    {
      "id": "5f6a7b8c-9d0e-4123-8456-789abcdef012",
      "value": "Job Board"
    }
  ],
  "pools": [
    "507f191e-810c-4972-9de8-60ea12345678",
    "507f191e-810c-4972-9de8-60eb87654321"
  ]
}

Custom Fields

Name
customFields
Type
array
Description
Array of custom field objects with flexible structure:
- id: Field identifier
- type: Field type (text, number, date, boolean, select, etc.)
- value: Field value
- label: Human-readable field label
- options: Available options for select fields

System Fields

Name
archived
Type
boolean
Description
Whether the contact is archived.
Name
stage
Type
string
Description
Current stage in the talent pipeline.
Name
owner
Type
string
Description
User ID of the contact owner.
Name
lastActivity
Type
timestamp
Description
Timestamp of last interaction or update.

GET/v1/contacts

List contacts

Retrieve a paginated list of contacts from your Beamery CRM. Use filters to narrow down results based on various criteria.

Query parameters

Name
limit
Type
integer
Description
Number of contacts to return (default: 20, max: 100).
Name
offset
Type
integer
Description
Number of contacts to skip for pagination.
Name
search
Type
string
Description
Search contacts by name, email, or skills.
Name
tags
Type
array
Description
Filter by specific tags.
Name
pools
Type
array
Description
Filter by talent pool IDs.
Name
stage
Type
string
Description
Filter by pipeline stage.
Name
updatedAfter
Type
timestamp
Description
Only return contacts updated after this date.

Request

GET

/v1/contacts

curl https://frontier.beamery.com/v1/contacts \
  -H "Authorization: Bearer your_access_token" \
  -G \
  -d limit=10 \
  -d search="python developer"

Response

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "email": "sarah.chen@example.com",
      "firstName": "Sarah",
      "lastName": "Chen",
      "currentRole": "Senior Python Developer",
      "currentCompany": "TechCorp",
      "location": {
        "id": "l5e6f7g8-h9i0-1234-jklm-567890123456",
        "address": "San Francisco, CA, USA",
        "city": "San Francisco",
        "country": "United States",
        "countryCode": "US",
        "geometry": {
          "type": "Point",
          "coordinates": [-122.4194, 37.7749]
        }
      },
      "skills": ["Python", "Django", "AWS", "PostgreSQL"],
      "tags": ["python", "senior", "active"],
      "lastActivity": "2024-01-15T10:30:00Z",
      "createdAt": "2023-06-20T14:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 156,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

GET/v1/contacts/{id}

Get a contact

Retrieve detailed information about a specific contact by their ID.

Path parameters

Name
id
Type
string
Description
The contact's unique identifier.

Request

GET

/v1/contacts/507f1f77bcf86cd799439011

curl https://frontier.beamery.com/v1/contacts/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer your_access_token"

Response

{
  "id": "507f1f77bcf86cd799439011",
  "email": "sarah.chen@example.com",
  "firstName": "Sarah",
  "lastName": "Chen",
  "phone": "+1-415-555-0123",
  "currentRole": "Senior Python Developer",
  "currentCompany": "TechCorp",
  "location": {
    "id": "l5e6f7g8-h9i0-1234-jklm-567890123456",
    "address": "San Francisco, CA 94105, USA",
    "city": "San Francisco",
    "country": "United States",
    "countryCode": "US",
    "geometry": {
      "type": "Point",
      "coordinates": [-122.4194, 37.7749]
    }
  },
  "skills": ["Python", "Django", "AWS", "PostgreSQL", "Docker", "Kubernetes"],
  "experiences": [
    {
      "company": "TechCorp",
      "role": "Senior Python Developer",
      "startDate": "2021-03-01",
      "current": true,
      "description": "Leading backend development for cloud services"
    },
    {
      "company": "StartupXYZ",
      "role": "Python Developer",
      "startDate": "2018-06-01",
      "endDate": "2021-02-28",
      "description": "Full-stack development using Django"
    }
  ],
  "education": [
    {
      "institution": "UC Berkeley",
      "degree": "BS Computer Science",
      "graduationYear": 2018
    }
  ],
  "tags": ["python", "senior", "active", "high-potential"],
  "pools": ["507f191e810c19729de860ea", "507f191e810c19729de860eb"],
  "source": "LinkedIn",
  "stage": "Engaged",
  "lastActivity": "2024-01-15T10:30:00Z",
  "createdAt": "2023-06-20T14:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

POST/v1/contacts

Create a contact

Create a new contact in your Beamery CRM. The system will automatically deduplicate based on email address.

Request body

Name
email
Type
string
Description
Contact's email address (used for deduplication).
Name
firstName
Type
string
Description
Contact's first name.
Name
lastName
Type
string
Description
Contact's last name.
Name
phone
Type
string
Description
Contact's phone number.
Name
currentRole
Type
string
Description
Current job title.
Name
currentCompany
Type
string
Description
Current employer.
Name
location
Type
object
Description
Location details.
Name
skills
Type
array
Description
List of skills.
Name
tags
Type
array
Description
Custom tags for the contact.
Name
source
Type
string
Description
How the contact was sourced.

Request

POST

/v1/contacts

curl https://frontier.beamery.com/v1/contacts \
  -X POST \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "currentRole": "Data Scientist",
    "currentCompany": "DataCorp",
    "skills": ["Python", "Machine Learning", "TensorFlow"],
    "location": {
      "id": "l6f7g8h9-i0j1-2345-klmn-678901234567",
      "address": "New York, NY, USA",
      "city": "New York",
      "country": "United States",
      "countryCode": "US",
      "geometry": {
        "type": "Point",
        "coordinates": [-74.0060, 40.7128]
      }
    },
    "source": "Job Board",
    "tags": ["data-science", "senior"]
  }'

Response

{
  "id": "507f1f77bcf86cd799439012",
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "currentRole": "Data Scientist",
  "currentCompany": "DataCorp",
  "skills": ["Python", "Machine Learning", "TensorFlow"],
  "location": {
    "id": "l6f7g8h9-i0j1-2345-klmn-678901234567",
    "address": "New York, NY, USA",
    "city": "New York",
    "country": "United States",
    "countryCode": "US",
    "geometry": {
      "type": "Point",
      "coordinates": [-74.0060, 40.7128]
    }
  },
  "source": "Job Board",
  "tags": ["data-science", "senior"],
  "stage": "New",
  "createdAt": "2024-01-20T15:30:00Z",
  "updatedAt": "2024-01-20T15:30:00Z"
}

PATCH/v1/contacts/{id}

Update a contact

Update an existing contact's information. Only include the fields you want to update.

Path parameters

Name
id
Type
string
Description
The contact's unique identifier.

Request body

Include only the fields you want to update. All fields from the create endpoint are available.

Request

PATCH

/v1/contacts/507f1f77bcf86cd799439011

curl https://frontier.beamery.com/v1/contacts/507f1f77bcf86cd799439011 \
  -X PATCH \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "currentRole": "Lead Python Developer",
    "skills": ["Python", "Django", "AWS", "PostgreSQL", "Team Leadership"],
    "tags": ["python", "senior", "active", "high-potential", "leadership"]
  }'

Response

{
  "id": "507f1f77bcf86cd799439011",
  "email": "sarah.chen@example.com",
  "firstName": "Sarah",
  "lastName": "Chen",
  "currentRole": "Lead Python Developer",
  "currentCompany": "TechCorp",
  "skills": ["Python", "Django", "AWS", "PostgreSQL", "Team Leadership"],
  "tags": ["python", "senior", "active", "high-potential", "leadership"],
  "updatedAt": "2024-01-20T16:00:00Z"
}

DELETE/v1/contacts/{id}

Delete a contact

Permanently delete a contact from your Beamery CRM. This action cannot be undone.

Path parameters

Name
id
Type
string
Description
The contact's unique identifier.

Deleting a contact will also remove them from all pools and delete all associated activities and history.

Request

DELETE

/v1/contacts/507f1f77bcf86cd799439011

curl https://frontier.beamery.com/v1/contacts/507f1f77bcf86cd799439011 \
  -X DELETE \
  -H "Authorization: Bearer your_access_token"

Response

{
  "success": true,
  "message": "Contact successfully deleted"
}