Affinda Search and Match API

openapi: 3.0.3
info:
  title: Affinda Search and Match API
  version: 3.0.0
  description: "Affinda Search and Match API \u2014 subset of the Affinda v3 Document Processing API."
servers:
- url: https://{region}.affinda.com
  description: 'Select the correct server for your instance: api (AUS/Global), api.us1 (US), or api.eu1 (EU).'
  variables:
    region:
      default: api
      description: The instance region. Use 'api' for AUS/Global, 'api.us1' for US, or 'api.eu1' for EU. You can find your
        region in the Affinda web app URL.
      enum:
      - api
      - api.eu1
      - api.us1
      x-ms-parameter-location: client
security:
- ApiKeyAuth: []
paths:
  /v3/documents/create_from_data:
    post:
      tags:
      - Search & Match
      summary: Create a document from raw data
      operationId: createDocumentFromData
      description: '

        Creates a document directly from structured resume or job description data for use in Search & Match functionality.
        This endpoint is specifically designed for programmatic document creation without file uploads.<br/>

        If you want to upload a document with a file or URL, see the main [POST /v3/documents](#post-/v3/documents) endpoint
        under the Documents tag.<br/>

        When successful, returns an `identifier` in the response for subsequent use with the [/documents/{identifier}](#get-/v3/documents/-identifier-)
        endpoint to check processing status and retrieve results.<br/>'
      responses:
        '200':
          description: Only returned when wait=True, will return the created document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '201':
          description: Only returned when wait=False, will return document uploaded and identifier created
          x-summary: Document uploaded and created, use document.meta.identifier to poll for processing status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        default:
          $ref: '#/components/responses/DefaultError'
      parameters:
      - in: query
        name: snake_case
        required: false
        description: Whether to return the response in snake_case instead of camelCase. Default is false.
        schema:
          type: boolean
      requestBody:
        description: Resume or job description data to create a document from
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentCreateFromData'
  /v3/documents/{identifier}/update_data:
    post:
      tags:
      - Search & Match
      summary: Update a document's data
      operationId: updateDocumentData
      description: 'Update data of a document.

        Only applicable for resumes and job descriptions. For other document types, please use the `PATCH /annotations/{id}`
        endpoint or the `POST /annotations/batch_update` endpoint.'
      parameters:
      - in: path
        required: true
        name: identifier
        description: Resume or Job Description identifier
        schema:
          $ref: '#/components/schemas/Identifier'
      requestBody:
        description: Resume data to update
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/ResumeData'
              - $ref: '#/components/schemas/JobDescriptionDataUpdate'
      responses:
        '200':
          description: Successfully updated resume data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
  /v3/occupation_groups:
    get:
      tags:
      - Search & Match
      summary: List occupation groups
      operationId: listOccupationGroups
      description: Returns the list of searchable occupation groups.
      responses:
        '200':
          description: Will return matching documents
          x-summary: Will return matching documents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OccupationGroup'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
  /v3/resume_search:
    post:
      tags:
      - Search & Match
      summary: Search through parsed resumes
      operationId: createResumeSearch
      description: "Searches through parsed resumes. Users have 3 options to create a search:<br /><br /> 1.\tMatch to a job\
        \ description - a parsed job description is used to find candidates that suit it<br /> 2.\tMatch to a resume - a parsed\
        \ resume is used to find other candidates that have similar attributes<br /> 3.\tSearch using custom criteria<br /><br\
        \ /> Users should only populate 1 of jobDescription, resume or the custom criteria."
      parameters:
      - $ref: '#/components/parameters/offsetParam'
      - in: query
        name: limit
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 50
          example: 20
        description: The numbers of results to return.
        x-ms-parameter-location: method
      responses:
        '201':
          description: Will return matching documents
          x-summary: Will return matching documents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResumeSearch'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
      requestBody:
        description: Search parameters
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumeSearchParameters'
  /v3/resume_search/details/{identifier}:
    post:
      tags:
      - Search & Match
      summary: Get search result of specific resume
      operationId: getResumeSearchDetail
      description: 'This contains more detailed information about the matching score of the search criteria, or which search
        criteria is missing in this resume.

        The `identifier` is the unique ID returned via the [/resume_search](#post-/resume_search) endpoint.'
      parameters:
      - in: path
        required: true
        name: identifier
        description: Resume identifier
        schema:
          type: string
          example: ELglqBbT
      responses:
        '200':
          description: Successfully retrieved detail search result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResumeSearchDetail'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
      requestBody:
        description: Search parameters
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumeSearchParameters'
  /v3/resume_search/config:
    get:
      tags:
      - Search & Match
      summary: Get the config for the logged in user's embeddable resume search tool
      operationId: getResumeSearchConfig
      description: Return configurations such as which fields can be displayed in the logged in user's embeddable resume search
        tool, what are their weights, what is the maximum number of results that can be returned, etc.
      responses:
        '200':
          description: The config for the logged in user's embedable search tool.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResumeSearchConfig'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
    patch:
      tags:
      - Search & Match
      summary: Update the config for the logged in user's embeddable resume search tool
      operationId: updateResumeSearchConfig
      description: Update configurations such as which fields can be displayed in the logged in user's embeddable resume search
        tool, what are their weights, what is the maximum number of results that can be returned, etc.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumeSearchConfig'
      responses:
        '200':
          description: Successfully updated configurations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResumeSearchConfig'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
  /v3/resume_search/embed:
    post:
      tags:
      - Search & Match
      summary: Create a signed URL for the embeddable resume search tool
      operationId: createResumeSearchEmbedUrl
      description: Create and return a signed URL of the resume search tool which then can be embedded on a web page. An optional
        parameter `config_override` can be passed to override the user-level configurations of the embeddable resume search
        tool.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                configOverride:
                  $ref: '#/components/schemas/ResumeSearchConfig'
      responses:
        '200':
          description: Successfully created a signed URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResumeSearchEmbed'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
  /v3/resume_search/match:
    get:
      tags:
      - Search & Match
      summary: Match a single resume and job description
      operationId: getResumeSearchMatch
      description: Get the matching score between a resume and a job description. The score ranges between 0 and 1, with 0
        being not a match at all, and 1 being perfect match.<br/> Note, this score will not directly match the score returned
        from POST [/resume_search/details/{identifier}](#post-/resume_search/details/-identifier-).
      parameters:
      - in: query
        name: resume
        required: true
        schema:
          type: string
        description: Identify the resume to match.
        example: ytBrHSmF
      - in: query
        name: job_description
        required: true
        schema:
          type: string
        description: Identify the job description to match.
        example: fkAmLQQz
      - in: query
        name: index
        required: false
        schema:
          type: string
        description: Optionally, specify an index to search in. If not specified, will search in all indexes.
        example: my-custom-index
      - in: query
        name: search_expression
        required: false
        schema:
          type: string
        description: Add keywords to the search criteria.
      - in: query
        name: job_titles_weight
        required: false
        schema:
          type: number
          minimum: 0
          maximum: 1
        description: How important is this criteria to the matching score, range from 0 to 1.
      - in: query
        name: years_experience_weight
        required: false
        schema:
          type: number
          minimum: 0
          maximum: 1
        description: How important is this criteria to the matching score, range from 0 to 1.
      - in: query
        name: locations_weight
        required: false
        schema:
          type: number
          minimum: 0
          maximum: 1
        description: How important is this criteria to the matching score, range from 0 to 1.
      - in: query
        name: languages_weight
        required: false
        schema:
          type: number
          minimum: 0
          maximum: 1
        description: How important is this criteria to the matching score, range from 0 to 1.
      - in: query
        name: skills_weight
        required: false
        schema:
          type: number
          minimum: 0
          maximum: 1
        description: How important is this criteria to the matching score, range from 0 to 1.
      - in: query
        name: education_weight
        required: false
        schema:
          type: number
          minimum: 0
          maximum: 1
        description: How important is this criteria to the matching score, range from 0 to 1.
      - in: query
        name: search_expression_weight
        required: false
        schema:
          type: number
          minimum: 0
          maximum: 1
        description: How important is this criteria to the matching score, range from 0 to 1.
      - in: query
        name: soc_codes_weight
        required: false
        schema:
          type: number
          minimum: 0
          maximum: 1
        description: How important is this criteria to the matching score, range from 0 to 1.
      - in: query
        name: management_level_weight
        required: false
        schema:
          type: number
          minimum: 0
          maximum: 1
        description: How important is this criteria to the matching score, range from 0 to 1.
      responses:
        '200':
          description: The matching score between the provided resume and job description.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResumeSearchMatch'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
  /v3/resume_search/suggestion_job_title:
    get:
      tags:
      - Search & Match
      summary: Get job title suggestions based on provided job title(s)
      operationId: getResumeSearchSuggestionJobTitle
      description: Provided one or more job titles, get related suggestions for your search.
      parameters:
      - in: query
        name: job_titles
        required: true
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
          example:
          - Software Developer
          - Team Lead
        description: Job title to query suggestions for
      responses:
        '200':
          description: Successfully fetched related job titles.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  example: Web Developer
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
  /v3/resume_search/suggestion_skill:
    get:
      tags:
      - Search & Match
      summary: Get skill suggestions based on provided skill(s)
      operationId: getResumeSearchSuggestionSkill
      description: Provided one or more skills, get related suggestions for your search.
      parameters:
      - in: query
        name: skills
        required: true
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
          example:
          - Javascript
          - python
        description: Skill to query suggestions for
      responses:
        '200':
          description: Successfully fetched related skills.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  example: SQL (Programming Language)
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
  /v3/job_description_search:
    post:
      tags:
      - Search & Match
      summary: Search through parsed job descriptions
      operationId: createJobDescriptionSearch
      description: Searches through parsed job descriptions. You can search with custom criterias or a resume.
      parameters:
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      responses:
        '201':
          description: Will return matching documents
          x-summary: Will return matching documents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDescriptionSearch'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
      requestBody:
        description: Search parameters
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobDescriptionSearchParameters'
  /v3/job_description_search/details/{identifier}:
    post:
      tags:
      - Search & Match
      summary: Get search result of specific job description
      operationId: getJobDescriptionSearchDetail
      description: 'This contains more detailed information about the matching score of the search criteria, or which search
        criteria is missing in this job description.

        The `identifier` is the unique ID returned via the [/job_description_search](#post-/job_description_search) endpoint.'
      parameters:
      - in: path
        required: true
        name: identifier
        description: Job Description identifier
        schema:
          type: string
          example: ELgrnBbM
      responses:
        '200':
          description: Successfully retrieved detail search result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDescriptionSearchDetail'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
      requestBody:
        description: Search parameters
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobDescriptionSearchParameters'
  /v3/job_description_search/config:
    get:
      tags:
      - Search & Match
      summary: Get the config for the logged in user's embeddable job description search tool
      operationId: getJobDescriptionSearchConfig
      description: Return configurations such as which fields can be displayed in the logged in user's embeddable job description
        search tool, what are their weights, what is the maximum number of results that can be returned, etc.
      responses:
        '200':
          description: The config for the logged in user's embeddable job description search tool.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDescriptionSearchConfig'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
    patch:
      tags:
      - Search & Match
      summary: Update the config for the logged in user's embeddable job description search tool
      operationId: updateJobDescriptionSearchConfig
      description: Update configurations such as which fields can be displayed in the logged in user's embeddable job description
        search tool, what are their weights, what is the maximum number of results that can be returned, etc.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobDescriptionSearchConfig'
      responses:
        '200':
          description: Successfully updated configurations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDescriptionSearchConfig'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
  /v3/job_description_search/embed:
    post:
      tags:
      - Search & Match
      summary: Create a signed URL for the embeddable job description search tool
      operationId: createJobDescriptionSearchEmbedUrl
      description: Create and return a signed URL of the job description search tool which then can be embedded on a web page.
        An optional parameter `config_override` can be passed to override the user-level configurations of the embeddable
        search tool.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                configOverride:
                  $ref: '#/components/schemas/JobDescriptionSearchConfig'
      responses:
        '200':
          description: Successfully created a signed URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDescriptionSearchEmbed'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
  /v3/index:
    get:
      tags:
      - Search & Match
      summary: Get list of all indexes
      operationId: getAllIndexes
      description: Returns all the indexes
      parameters:
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      - in: query
        name: document_type
        required: false
        schema:
          type: string
          enum:
          - resumes
          - job_descriptions
        description: Filter indices by a document type
        x-ms-parameter-location: method
      - in: query
        name: name
        required: false
        schema:
          type: string
        description: Filter indices by name
        x-ms-parameter-location: method
      responses:
        '200':
          description: All indexes for user
          content:
            application/json:
              schema:
                type: object
                required:
                - results
                - count
                allOf:
                - $ref: '#/components/schemas/PaginatedResponse'
                - type: object
                  properties:
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/Index'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
    post:
      tags:
      - Search & Match
      summary: Create a new index
      operationId: createIndex
      description: Create an index for the search tool
      responses:
        '201':
          description: Returns the created index
          links:
            deleteIndexName:
              operationId: deleteIndex
              parameters:
                name: $response.body#/name
            getAllIndexDocumentsName:
              operationId: getAllIndexDocuments
              parameters:
                name: $response.body#/name
            createIndexDocumentName:
              operationId: createIndexDocument
              parameters:
                name: $response.body#/name
            deleteIndexDocumentName:
              operationId: deleteIndexDocument
              parameters:
                name: $response.body#/name
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Index'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
      requestBody:
        description: Index to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndexCreate'
  /v3/index/{name}:
    patch:
      tags:
      - Search & Match
      summary: Update an index
      operationId: updateIndex
      description: Updates the specified index
      parameters:
      - in: path
        required: true
        name: name
        description: Index name
        schema:
          $ref: '#/components/schemas/Index_properties-name'
      requestBody:
        description: Index data to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndexUpdate'
      responses:
        '200':
          description: Successfully updated index data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Index'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
    delete:
      tags:
      - Search & Match
      summary: Delete an index
      operationId: deleteIndex
      description: Deletes the specified index from the database
      parameters:
      - in: path
        required: true
        name: name
        description: Index name
        schema:
          $ref: '#/components/schemas/Index_properties-name'
      responses:
        '204':
          $ref: '#/components/responses/204NoContent'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
  /v3/index/{name}/documents:
    get:
      tags:
      - Search & Match
      summary: Get indexed documents for a specific index
      operationId: getAllIndexDocuments
      description: Returns all the indexed documents for that index
      parameters:
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      - in: path
        required: true
        name: name
        description: Index name
        schema:
          type: string
          description: Unique index name
          example: all-resumes
      responses:
        '200':
          description: Successfully retrieved list of indexed documents
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  count:
                    type: integer
                    example: 1
                    minimum: 1
                    description: Number of indexed documents in result
                  next:
                    type: string
                    nullable: true
                    description: URL to request next page of results
                  previous:
                    type: string
                    nullable: true
                    description: URL to request previous page of results
                  results:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        document:
                          type: string
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
    post:
      tags:
      - Search & Match
      summary: Index a new document
      operationId: createIndexDocument
      description: Create an indexed document for the search tool
      parameters:
      - in: path
        required: true
        name: name
        description: Index name
        schema:
          type: string
          description: Unique index name
          example: my-index
      responses:
        '201':
          description: Returns the created indexed document
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  document:
                    type: string
                    example: EhglqBoT
                    description: Unique identifier for the document.
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
      requestBody:
        description: Document to index
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                document:
                  type: string
                  example: EhglqBoT
  /v3/index/{name}/documents/{identifier}:
    delete:
      tags:
      - Search & Match
      summary: Delete an indexed document
      operationId: deleteIndexDocument
      description: Delete the specified indexed document from the database
      parameters:
      - in: path
        required: true
        name: name
        description: Index name
        schema:
          type: string
          description: Unique index name
          example: my-index
      - in: path
        required: true
        name: identifier
        description: Document identifier
        schema:
          $ref: '#/components/schemas/Identifier'
      responses:
        '204':
          $ref: '#/components/responses/204NoContent'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
  /v3/index/{name}/documents/{identifier}/re_index:
    post:
      tags:
      - Search & Match
      summary: Re-index a document
      operationId: reIndexDocument
      description: 'Re-index a document.

        This is relevant if you updated the document''s data via the /annotations endpoint, and want to refresh

        the document''s data in the search index.

        '
      parameters:
      - in: path
        required: true
        name: name
        description: Index name
        schema:
          type: string
          description: Unique index name
          example: my-index
      - in: path
        required: true
        name: identifier
        description: Document identifier
        schema:
          $ref: '#/components/schemas/Identifier'
      responses:
        '200':
          description: Document successfully re-indexed
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: 'Basic authentication using an API key, e.g. `{Authorization: Bearer aff_0bb4fbdf97b7e4111ff6c0015471094155f91}`.

        You can find your API key within the Settings page of the [Affinda web app](https://app.affinda.com/). You can obtain
        an API key by [signing up for a free trial](https://app.affinda.com/auth/register).'
  schemas:
    Resume:
      allOf:
      - $ref: '#/components/schemas/Document'
      - type: object
        properti

# --- truncated at 32 KB (232 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/affinda/refs/heads/main/openapi/affinda-search-match-api-openapi.yml