API Reference

Candidate Profiles

Create, retrieve, update, and validate candidate profiles. A profile represents all the information needed to apply for jobs on behalf of a candidate.

Profile Object

A candidate profile contains the personal details, work history, education, skills, and other information used to complete job applications. The following sections describe every field in the profile object.

Name	Type	Required	Description
`resumeUrl`	`string`	Required	URL of the candidate's resume file. You can use the Resumes upload endpoint to get a hosted URL, or provide any publicly accessible URL.

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")
`phoneNumberNumber`	`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`	Optional	End date in YYYY-MM format. Omit or set to null 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, California" 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`	Required	Language name. Required when a language entry is provided.
`level`	`string`	Required	Proficiency level. Required when a language entry is provided: 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

Creates a new candidate profile for a given user. Each profile stores the information required to complete job applications — personal details, work history, education, skills, and a resume. Refer to the Profile Object section above for the complete field reference.

POST/profiles

Name	Type	Required	Description
`userId`	`string`	Required	User ID this profile belongs to
`resumeUrl`	`string`	Required	URL of the candidate's resume file. Use the Resumes upload endpoint for a hosted URL, or provide any publicly accessible URL.

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",
  "updatedAt": null
}

Get Profile

Retrieves a candidate profile by its ID. Returns the complete profile object with all sections populated.

GET/profiles/:profileId

curl https://apply-api.boringproject.ai/api/v1/profiles/prof_xyz789 \
          -H "Authorization: Bearer bp_live_..."

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",
    "gender": "Male",
    "address": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94105",
    "country": "United States",
    "citizenship": "US Citizen"
  },
  "workExperience": [
    {
      "jobTitle": "Software Engineer",
      "company": "Tech Corp",
      "startDate": "2020-01",
      "endDate": null,
      "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" }
  ],
  "certifications": [],
  "achievements": [],
  "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",
  "updatedAt": null
}

Update Profile

Updates an existing candidate profile. Include only the fields you want to change — all fields are optional. After the update, the profile is automatically re-validated against your mandatory field requirements and the `isComplete` flag is recalculated.

PUT/profiles/:profileId

curl -X PUT https://apply-api.boringproject.ai/api/v1/profiles/prof_xyz789 \
          -H "Authorization: Bearer bp_live_..." \
          -H "Content-Type: application/json" \
          -d '{
            "personalInformation": {
              "city": "New York",
              "state": "NY"
            },
            "miscellaneous": {
              "expectedSalaryAmount": "180000",
              "willingToRelocate": "No"
            }
          }'

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",
    "gender": "Male",
    "address": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "United States",
    "citizenship": "US Citizen"
  },
  "workExperience": [
    {
      "jobTitle": "Software Engineer",
      "company": "Tech Corp",
      "startDate": "2020-01",
      "endDate": null,
      "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" }
  ],
  "certifications": [],
  "achievements": [],
  "miscellaneous": {
    "totalExperience": "5",
    "expectedSalaryAmount": "180000",
    "expectedSalaryCurrency": "USD",
    "noticePeriod": "30",
    "willingToRelocate": "No",
    "authorisedToWork": ["United States"],
    "visaRequirement": "No",
    "linkedinUrl": "https://linkedin.com/in/johndoe"
  },
  "resumeUrl": "https://s3.amazonaws.com/.../resume.pdf",
  "createdAt": "2024-02-14T10:35:00Z",
  "updatedAt": "2024-02-15T09:00:00Z"
}

Validate Profile

Checks whether a profile satisfies all mandatory field requirements before submitting applications. Returns the list of required fields, any that are missing, and specific validation errors. Use this to surface incomplete profiles to your users before they attempt to apply.

GET/profiles/:profileId/validate

curl https://apply-api.boringproject.ai/api/v1/profiles/prof_xyz789/validate \
          -H "Authorization: Bearer bp_live_..."

Response200 OK

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

List Profiles

Returns a paginated list of all candidate profiles for your account. You can filter results by user ID or completion status to find specific profiles.

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

curl "https://apply-api.boringproject.ai/api/v1/profiles?page=1&limit=20&userId=usr_abc123&isComplete=true" \
          -H "Authorization: Bearer bp_live_..."

Response200 OK

{
  "data": [
    {
      "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 }
      ],
      "education": [
        { "institution": { "name": "State University" }, "degree": { "degreeName": "B.S. Computer Science" } }
      ],
      "skills": [{ "skill": "Python", "experience": "5" }],
      "languages": [],
      "certifications": [],
      "achievements": [],
      "miscellaneous": {
        "totalExperience": "5",
        "expectedSalaryAmount": "150000",
        "expectedSalaryCurrency": "USD",
        "linkedinUrl": "https://linkedin.com/in/johndoe"
      },
      "resumeUrl": "https://s3.amazonaws.com/.../resume.pdf",
      "createdAt": "2024-02-14T10:35:00Z",
      "updatedAt": null
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 5, "totalPages": 1 }
}

Related docs

Candidate Profiles

Profile Object

Create Profile

Get Profile

Update Profile

Validate Profile

List Profiles

Continue reading

Users

Resumes

Sessions