RErecruitwithatlas
People

Add a work experience to a person

Changed on

Use this endpoint to add a single work-experience entry to an existing person.

Provide the company name (and optionally its website domain and/or LinkedIn company id) — Atlas resolves or creates the matching Company and links it. A match on the exact domain or LinkedIn company id links to that Company even when the supplied name differs. A different subdomain of a domain an existing Company already holds (e.g. jobs.acme.com when the Company has careers.acme.com) links only when the names are similar, and a companyLinkedinId sent with it is not added to that Company. Otherwise the experience is stored without a Company link, or, when a companyLinkedinId no Company holds is also sent, linked to a new Company with only that LinkedIn id. Supplying companyId instead links the exact existing Company and skips matching entirely. Sending companyId: null stores the employment as text only — the companyName is kept and no Company is matched or created (companyDomain / companyLinkedinId are then rejected with 422). The role, start date, and (optionally) end date and description complete the entry.

Unlike the bulk experience data on POST /api/v1/people (which is created asynchronously), this endpoint creates the experience synchronously and returns it. Adding an experience recalculates the person's headline.

post/api/v1/people/{id}/experiences

Request

Path parameters

idstring uuid required

Atlas person ID

Example:123e4567-e89b-12d3-a456-426614174000

Request body

companyNamestring required

Company name

companyIdstring uuid nullable

Chooses how the experience is linked to a company; when present (id or null) it takes precedence over companyName matching. Omitted: the company is resolved from companyName (plus companyDomain / companyLinkedinId), and a new one is created when none matches. An Atlas company ID: links that exact existing company — no company is created and name/domain/LinkedIn matching is skipped; an ID outside your agency returns 422. null: no company link — on create the employment is stored as text only (the companyName is kept, no company is matched or created, and companyDomain / companyLinkedinId must be omitted, else 422); on update the current company is unlinked.

companyLinkedinIdstring nullable

Company LinkedIn ID

companyDomainstring nullable

Company website domain (bare domain; full URLs are accepted and normalized to their hostname)

rolestring required

Job title/role

descriptionstring nullable

Role description

startDatestring required

Start date (YYYY-MM-DD)

endDatestring nullable

End date (YYYY-MM-DD, null = current)

Example request

{
  "companyName": "Dunder Mifflin",
  "companyId": "550e8400-e29b-41d4-a716-446655440000",
  "companyLinkedinId": "12345678",
  "companyDomain": "dundermifflin.com",
  "role": "Regional Manager",
  "description": "Responsible for managing Scranton branch.",
  "startDate": "2021-04-01"
}

Response

Experience created

status'ok' required

Example response

{
  "data": {
    "companyName": "Dunder Mifflin",
    "companyId": "550e8400-e29b-41d4-a716-446655440000",
    "companyLinkedinId": "12345678",
    "companyDomain": "dundermifflin.com",
    "role": "Regional Manager",
    "startDate": "2021-04-01"
  }
}

Changes