API Reference

Candidate Profiles

Manage candidate profiles containing personal information, work experience, education, skills, languages, certifications, achievements, miscellaneous details, and resumes.

Profile Object

A profile contains all the information needed to fill out job applications on behalf of a candidate. Below is the full field reference for each section of the profile object.

Name	Type	Required	Description
`resumeUrl`	`string`	Required	S3 URL of the uploaded resume file. Obtain this from the Resumes upload endpoint.

personalInformationobjectRequired

Candidate's personal and contact details.

Field	Type	Required	Description
`firstName`	`string`	Required	First name
`lastName`	`string`	Required	Last name
`email`	`string`	Required	Email address
`countryCode`	`string`	Required	Phone country code (e.g. "+1")
`phoneNumber`	`string`	Required	Phone number
`gender`	`string`	Required	Male, Female, Non-binary, or Prefer not to say
`address`	`string`	Required	Street address
`city`	`string`	Required	City
`state`	`string`	Required	State or province
`zipCode`	`string`	Required	ZIP or postal code
`country`	`string`	Required	Country
`citizenship`	`string`	Required	Citizenship status

workExperiencearrayRequired

Array of work history entries. At least one entry is required.

Field	Type	Required	Description
`jobTitle`	`string`	Required	Job title
`company`	`string`	Required	Company name
`startDate`	`string`	Required	Start date in YYYY-MM format (e.g. "2020-01")
`endDate`	`string`	Required	End date in YYYY-MM format. Set to empty string if currently working here.
`currentlyWorkHere`	`boolean`	Required	true if this is the current position, false otherwise
`workLocation`	`string`	Required	Work location (e.g. "San Francisco, CA" or "Remote")
`description`	`string`	Required	Role description or responsibilities

educationarrayRequired

Array of education entries. At least one entry is required.

Field	Type	Required	Description
`institution`	`object`	Required	Institution details: { name, location: { city, state } }
`degree`	`object`	Required	{ degreeName } — e.g. { degreeName: "B.S. Computer Science" }
`startDate`	`string`	Optional	Start date in YYYY-MM format
`endDate`	`string`	Optional	End date in YYYY-MM format
`gpa`	`string`	Optional	GPA (e.g. "3.7")

skillsarrayRequired

Array of skills. At least one entry is required.

Field	Type	Required	Description
`skill`	`string`	Required	Skill name
`experience`	`string`	Required	Years of experience (e.g. "5"). Required when a skill entry is provided.

languagesarrayOptional

Array of languages the candidate speaks. Optional section, but if an entry is provided the fields below apply.

Field	Type	Required	Description
`language`	`string`	Optional	Language name
`level`	`string`	Optional	Proficiency: Native, Fluent, Advanced, Intermediate, or Beginner

certificationsarrayOptional

Array of professional certifications. Optional section, but if an entry is provided the fields below apply.

Field	Type	Required	Description
`name`	`string`	Optional	Certification name
`issuer`	`string`	Optional	Issuing organization
`issueDate`	`string`	Optional	Issue date in YYYY-MM format
`expiryDate`	`string`	Optional	Expiry date in YYYY-MM format
`credentialId`	`string`	Optional	Credential ID
`credentialUrl`	`string`	Optional	URL to verify the credential

achievementsarrayOptional

Array of awards or achievements. Optional section, but if an entry is provided the fields below apply.

Field	Type	Required	Description
`awardTitle`	`string`	Optional	Award or achievement title
`issuer`	`string`	Optional	Issuing organization
`issuingDate`	`string`	Optional	Date awarded in YYYY-MM format
`description`	`string`	Optional	Description of the achievement

miscellaneousobjectRequired

Additional candidate information. Contains required sub-fields.

Field	Type	Required	Description
`totalExperience`	`string`	Required	Total years of professional experience (e.g. "6")
`expectedSalaryAmount`	`string`	Required	Expected salary amount (e.g. "150000")
`expectedSalaryCurrency`	`string`	Required	Currency code (e.g. "USD")
`noticePeriod`	`string`	Required	Notice period in days (e.g. "30")
`willingToRelocate`	`string`	Required	Yes, No, or Maybe
`authorisedToWork`	`string[]`	Required	Array of countries where the candidate is authorized to work (e.g. ["United States", "Canada"])
`visaRequirement`	`string`	Required	Whether visa sponsorship is needed: Yes or No
`highestEducationLevel`	`string`	Optional	High School, Associate's Degree, Bachelor's Degree, Master's Degree, Doctorate, or Other
`currentSalary`	`string`	Optional	Current salary amount
`currentSalaryCurrency`	`string`	Optional	Current salary currency code
`linkedinUrl`	`string`	Required	LinkedIn profile URL
`twitterUrl`	`string`	Optional	Twitter/X profile URL
`githubUrl`	`string`	Optional	GitHub profile URL
`portfolioUrl`	`string`	Optional	Portfolio or personal website URL
`otherUrl`	`string`	Optional	Any other relevant URL
`coverLetter`	`string`	Optional	Default cover letter text
`expectedDateOfJoining`	`string`	Optional	Earliest available start date
`drivingLicense`	`string`	Optional	Has a driving license: Yes or No
`veteranStatus`	`string`	Optional	Veteran status
`disability`	`string`	Optional	Disability disclosure
`race`	`string`	Optional	Race/ethnicity (for EEO compliance)
`securityClearanceActive`	`string`	Optional	Active security clearance: Yes or No
`companiesToExclude`	`string`	Optional	Companies to exclude from applications
`defaultExperience`	`string`	Optional	Default years of experience for skills not individually specified (e.g. "3")

Create Profile

Create a new candidate profile for a user. The profile contains all information needed to fill out job applications. See the Profile Object reference above for the full field schema.

POST/profiles

Name	Type	Required	Description
`userId`	`string`	Required	User ID this profile belongs to
`resumeUrl`	`string`	Required	S3 URL of uploaded resume. Obtain via the Resumes upload endpoint.

personalInformationobjectRequired

Candidate's personal and contact details. See Profile Object for sub-fields.

workExperiencearrayRequired

Array of work history entries. At least one required. See Profile Object for sub-fields.

educationarrayRequired

Array of education entries. At least one required. See Profile Object for sub-fields.

skillsarrayRequired

Array of skills. At least one required. See Profile Object for sub-fields.

languagesarrayOptional

Array of languages. See Profile Object for sub-fields.

certificationsarrayOptional

Array of professional certifications. See Profile Object for sub-fields.

achievementsarrayOptional

Array of awards or achievements. See Profile Object for sub-fields.

miscellaneousobjectRequired

Additional candidate information. Has required sub-fields — see Profile Object.

curl -X POST https://apply-api.boringproject.ai/api/v1/profiles \
  -H "Authorization: Bearer bp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "usr_abc123",
    "personalInformation": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "countryCode": "+1",
      "phoneNumber": "4155551234",
      "city": "San Francisco",
      "state": "CA",
      "country": "United States"
    },
    "workExperience": [
      {
        "jobTitle": "Software Engineer",
        "company": "Tech Corp",
        "startDate": "2020-01",
        "currentlyWorkHere": true,
        "workLocation": "San Francisco, CA",
        "description": "Full-stack development with React and Python"
      }
    ],
    "education": [
      {
        "institution": { "name": "State University", "location": { "city": "Berkeley", "state": "CA" } },
        "degree": { "degreeName": "B.S. Computer Science" },
        "startDate": "2016-09",
        "endDate": "2020-05",
        "gpa": "3.7"
      }
    ],
    "skills": [
      { "skill": "Python", "experience": "5" },
      { "skill": "React", "experience": "4" }
    ],
    "miscellaneous": {
      "totalExperience": "5",
      "expectedSalaryAmount": "150000",
      "expectedSalaryCurrency": "USD",
      "noticePeriod": "30",
      "willingToRelocate": "Yes",
      "authorisedToWork": ["United States"],
      "visaRequirement": "No",
      "linkedinUrl": "https://linkedin.com/in/johndoe"
    },
    "resumeUrl": "https://s3.amazonaws.com/.../resume.pdf"
  }'

Response200 OK

{
  "candidateProfileId": "prof_xyz789",
  "userId": "usr_abc123",
  "clientId": "client_xyz789",
  "isComplete": true,
  "personalInformation": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "countryCode": "+1",
    "phoneNumber": "4155551234",
    "city": "San Francisco",
    "state": "CA",
    "country": "United States"
  },
  "workExperience": [
    {
      "jobTitle": "Software Engineer",
      "company": "Tech Corp",
      "startDate": "2020-01",
      "currentlyWorkHere": true,
      "workLocation": "San Francisco, CA",
      "description": "Full-stack development with React and Python"
    }
  ],
  "education": [
    {
      "institution": { "name": "State University", "location": { "city": "Berkeley", "state": "CA" } },
      "degree": { "degreeName": "B.S. Computer Science" },
      "startDate": "2016-09",
      "endDate": "2020-05",
      "gpa": "3.7"
    }
  ],
  "skills": [
    { "skill": "Python", "experience": "5" },
    { "skill": "React", "experience": "4" }
  ],
  "languages": [
    { "language": "English", "level": "Native" },
    { "language": "Spanish", "level": "Intermediate" }
  ],
  "miscellaneous": {
    "totalExperience": "5",
    "expectedSalaryAmount": "150000",
    "expectedSalaryCurrency": "USD",
    "noticePeriod": "30",
    "willingToRelocate": "Yes",
    "authorisedToWork": ["United States"],
    "visaRequirement": "No",
    "linkedinUrl": "https://linkedin.com/in/johndoe"
  },
  "resumeUrl": "https://s3.amazonaws.com/.../resume.pdf",
  "createdAt": "2024-02-14T10:35:00Z"
}

Get Profile

Retrieve a candidate profile by its ID. Returns the full profile object including all sections — see Profile Object for the complete field reference.

GET/profiles/:profileId

Update Profile

Update an existing candidate profile. All fields are optional — only include fields you want to change. The profile will be re-validated against mandatory field requirements after update.

PUT/profiles/:profileId

Validate Profile

Check if a profile meets your client's mandatory field requirements before submitting applications. Returns a list of missing fields and validation errors.

GET/profiles/:profileId/validate

Response200 OK

{
  "candidateProfileId": "prof_xyz789",
  "isComplete": false,
  "mandatoryFields": ["personalInformation.email", "personalInformation.phone", "workExperience"],
  "missingFields": ["personalInformation.phone"],
  "validationErrors": [{ "field": "personalInformation.phone", "message": "Phone number is required" }]
}

List Profiles

Get all profiles for your client, optionally filtered by user ID or completion status.

GET/profiles

Name	Type	Required	Description
`page`	`integer`	Optional	Page number (default: 1)
`limit`	`integer`	Optional	Items per page, max 100 (default: 20)
`userId`	`string`	Optional	Filter by user ID
`isComplete`	`boolean`	Optional	Filter by completion status

Related docs

Candidate Profiles

Profile Object

Create Profile

Get Profile

Update Profile

Validate Profile

List Profiles

Continue reading

Users

Resumes

Sessions