Skip to main content

contacts.create

Add a contact

Request
POST/api/v1/contacts
Scope required
contacts:write
Effect
Changes data. Send an Idempotency-Key if you might retry it.
Acts on
Acts on the account’s own job search.
MCP tool
contacts_create
Environment
Live and sandbox alike.
Request body
JSON.

What it does

Creates a contact and links them to the companies and applications you name. A company named without an id is created if this account has no company by that name, so an agent importing a list of people does not have to look each company up first. Every application id must be one this account owns. Send an `Idempotency-Key` header if a retry must not create a second copy of the same person. Change them afterwards with `contacts.update`.

Request body

applicationIds
array of string, optional
category
string or null, optional
companies
array of object, optional
id
string or null, optional
name
string, required
email
string or null, optional
firstName
string, required
lastName
string or null, optional
notes
string or null, optional
phone
string or null, optional
source
string or null, optional

Response

applications
array of object, required
companyName
string, required
id
string, required
title
string, required
category
string or null, required
companies
array of object, required
id
string, required
name
string, required
createdAt
string, required
email
string or null, required
firstName
string, required
id
string, required
lastName
string or null, required
notes
string or null, required
phone
string or null, required
source
string or null, required
updatedAt
string, required

Examples

Record the recruiter for a role already applied to

Record the recruiter for a role already applied to — request
curl -s -X POST https://www.jobapplicationtracking.com/api/v1/contacts \
  -H "Authorization: Bearer $JAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "firstName": "Dana",
  "lastName": "Okafor",
  "email": "dana@acme.example",
  "category": "Recruiter",
  "source": "LinkedIn",
  "notes": "Owns hiring for the platform team.",
  "companies": [
    {
      "id": "co_42",
      "name": "Acme"
    }
  ],
  "applicationIds": [
    "app_123"
  ]
}'
Record the recruiter for a role already applied to — response
{
  "id": "ct_42",
  "firstName": "Dana",
  "lastName": "Okafor",
  "email": "dana@acme.example",
  "phone": null,
  "category": "Recruiter",
  "source": "LinkedIn",
  "notes": "Owns hiring for the platform team.",
  "companies": [
    {
      "id": "co_42",
      "name": "Acme"
    }
  ],
  "applications": [
    {
      "id": "app_123",
      "title": "Staff Engineer",
      "companyName": "Acme"
    }
  ],
  "createdAt": "2026-01-04T09:30:00.000Z",
  "updatedAt": "2026-02-11T17:05:00.000Z"
}

Related operations