Custom Data Fields

How to add custom fields for Candidate Search & Match.

While Affinda returns a wide range of data from resumes as standard, often customers will have other additional data typically not found in these documents that they would like to include in search criteria. Examples of this may include salary expectations, availability, or recruiters’ notes from interviews.

Affinda has functionality available for users to add custom data to candidate records and then to be able to search across this, either via API or through the Search UI.

Adding custom data

To be able to add custom data to a candidate, the data point needs to be first created for your Organization. Custom data points can be any of the following types:

• Boolean (true / false)
• Date
• Number
• String

To create these data points, get in touch with the Affinda team who will add the fields to your Organization.

Once created, custom data can be added in two ways.

1. Creating a new record

Create a new candidate record by sending a resume data object (i.e. without parsing a document) that includes the custom data field.

For more information, see Adding and Updating Candidates Data.

2. Updating an existing candidate record

Creating an initial annotation

To populate the custom fields, customers can add annotations using the Post Annotations API.

Required details include:

• Document: The unique identifier for the document to be updated
• Page Index: Set to 0 where the data point doesn’t exist on the document
• Field: Custom field’s unique identifier
• Parsed Value: The post-processed value (e.g., “AU” for Australia)

After successful submission of the annotation request, the response includes an annotation ID (e.g., “id”: 176932535). Store this ID for any future updates to the annotation value. The custom field’s value is then updated in the document, which can be viewed in the Affinda web application.

Updating annotation value

To update annotation values after initial creation, use the Patch Annotations API. Required details include:

• **Annotation ID: **Created after the first document patch
• Document: The unique identifier for the document to be updated
• Page Index: Set to 0 where the data point doesn’t exist on the document
• Parsed Value: The post-processed value (e.g., “AU” for Australia)

Searching via API

Once added, the custom fields can then be easily searched via the API.

• Use the standard [search endpoint] [LINK]
• Specifying the custom fields to search within the request, where:
  • “filterType” is either ‘equals’ or ‘range’
  • “dataPoint” is the custom field name
  • “value” is the search criteria

If the filter type is range, the value can be expressed in formats like the following:

• [“gte”: “2022-12-01”, “lte”: “2022-12-31”] – between 1-Dec-22 and 31-Dec-22
• [“lte”: “2022-12-31”] – before 31-Dec-22
• [“gte”: “2022-12-01”] – on or after 1-Dec-22

Searching via the Search UI

Custom fields can be searched through the Search UI by updating the embeddable URL configuration. For more information, see Customising and Embedding the Search UI.