Skip to main content
A ParaAI match is a request from a hiring manager. They looked at a candidate profile and asked for that specific candidate on a specific role. Paraform sends the request to you because the candidate is in your CRM. This is different from recommended roles, where Paraform’s model suggests roles for a candidate. Here, a person asked. You need a personal key with candidates:read, roles:read, and submissions:read. A key with All read access has all three.

​
List your pending matches

GET /recruiter/paraai-recommendations returns your pending matches, oldest first.
role.urls.browse is the role page. role.urls.recruit is your workspace on the role, and is null until you’re approved on it.
When role.company.confidentialSearch is true, the company is running a confidential search. In anything a candidate sees, call the employer role.company.anonymizedName and never use role.company.name.

​
Decide what to act on

A pending match expires 7 days after it’s sent. Unresolved expired matches can pause ParaAI matching for you, so the oldest pending matches are the most urgent. Rows come back oldest first, so start at the top. daysUntilExpiry tells you how long each one has left. actionBucket says where each match stands: The endpoint is read-only. Contact, pass, and submit in the Paraform app.

​
Filter by status

status narrows the list. It’s pending by default.
Pending matches on closed roles are left out. Resolved matches stay, so you keep your history. A page holds at most 20 matches. See Pagination for paging through more. The cursor marks a position in the list, so you can contact, pass, or submit matches while you page without skipping any.

​
Read the candidate in full

Pass candidate.candidateId to GET /recruiter/candidates/{candidateId} for the candidate’s work history, education, preferences, and your CRM note:
It returns 404 if the candidate has since left your CRM. See Find a candidate and read their full profile for the fields it returns.

​
What you can read

  • Only matches sent to you. A teammate’s matches never appear, even if you’re an agency owner who can see them in the app.
  • Your fee only when you can see payment. role.feePercent is null when your agency hides payment from its members. Agency owners always see it.

​
Errors

See Errors for the envelope.