> ## Documentation Index
> Fetch the complete documentation index at: https://api.jobaffinity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Look up candidates by email or phone

> Finds visible candidates by normalized email or phone. The email is lowercased and trimmed; the phone is parsed to E.164. At least one criterion must survive normalization, otherwise the answer is 400. Criteria that could not be normalized are listed in `rejected_criteria`, and each item reports which criteria it matched in `matched_on`.



## OpenAPI

````yaml /api-reference/openapi.json get /candidate/lookup
openapi: 3.0.3
info:
  title: JobAffinity REST API
  version: '1.13'
  description: >
    JobAffinity REST API for managing jobs, candidates, applications, and
    recruitment processes.


    ## Authentication

    All endpoints require HTTP Basic Authentication.


    ## Versioning

    Current version: 1.13


    See `/restapi/changelog` for version history and changes.
  contact:
    name: JobAffinity API Support
servers:
  - url: https://jobaffinity.fr/restapi/v1
    description: REST API v1
  - url: https://jobaffinity.fr/restapi
    description: REST API root (for changelog)
security:
  - basicAuth: []
tags:
  - name: API Info
    description: API metadata and changelog
  - name: Account
    description: Authenticated user identity and organisation membership
  - name: Jobs
    description: Job listings and details
  - name: Candidates
    description: Candidate information
  - name: Applications
    description: Job applications
  - name: Processes
    description: Recruitment processes and steps
  - name: Notes
    description: Candidate notes
  - name: Templates
    description: Recorded email templates
  - name: Questionnaires
    description: Questionnaire answers
  - name: Webhooks
    description: Webhook tasks
  - name: Job Application Submission
    description: >-
      Submit candidate applications to a job posting via the apply URL provided
      in the job feed. The authentication token is embedded in the URL — no
      additional credentials are required.
paths:
  /candidate/lookup:
    get:
      tags:
        - Candidates
      summary: Look up candidates by email or phone
      description: >-
        Finds visible candidates by normalized email or phone. The email is
        lowercased and trimmed; the phone is parsed to E.164. At least one
        criterion must survive normalization, otherwise the answer is 400.
        Criteria that could not be normalized are listed in `rejected_criteria`,
        and each item reports which criteria it matched in `matched_on`.
      operationId: lookupCandidates
      parameters:
        - name: email
          in: query
          description: Email to look up. Lowercased and trimmed before matching.
          schema:
            type: string
            format: email
        - name: phone
          in: query
          description: Phone to look up. Parsed to E.164 before matching.
          schema:
            type: string
      responses:
        '200':
          description: Matching candidates (up to 50)
          content:
            application/json:
              schema:
                type: object
                properties:
                  _status:
                    type: string
                    enum:
                      - OK
                  _self:
                    type: string
                    format: uri
                  normalized_email:
                    type: string
                    nullable: true
                    description: >-
                      The email after normalization, or null when it could not
                      be normalized.
                  normalized_phone:
                    type: string
                    nullable: true
                    description: >-
                      The phone after E.164 parsing, or null when it could not
                      be parsed.
                  rejected_criteria:
                    type: array
                    description: Criteria that were supplied but could not be normalized.
                    items:
                      type: string
                      enum:
                        - email
                        - phone
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/CandidateLookupItem'
        '400':
          description: No supplied criterion survived normalization
        '401':
          $ref: '#/components/responses/UnauthorizedError'
components:
  schemas:
    CandidateLookupItem:
      type: object
      properties:
        id:
          type: integer
          description: Candidate identifier
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        email_secondary:
          type: string
          format: email
        office_phone:
          type: string
        mobile_phone:
          type: string
        home_phone:
          type: string
        matched_on:
          type: array
          description: Which supplied criteria this candidate matched.
          items:
            type: string
            enum:
              - email
              - phone
  responses:
    UnauthorizedError:
      description: Authentication information is missing or invalid
      headers:
        WWW-Authenticate:
          schema:
            type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication with API credentials

````