The match method finds a single record by matching specific field values. This is useful for finding records by unique fields other than the ID.

Configuration Example

# spec.yml
name: Collection Name
methods:
  match:
    fields:
      - email
      - externalId
    parametersSchema:
      type: object
      properties:
        caseSensitive:
          type: boolean
          default: true

Configuration properties:

parametersSchema (DataSchema): Schema for the additional parameters
fields (array): Fields that can be used for matching

Implementation Examples

module.exports = async ({ fields, credentials, parameters }) => {
  const queryParams = {}

  // Build query from match fields
  if (fields.email) {
    queryParams.email = fields.email
  }

  const response = await makeApiRequest({
    method: "GET",
    path: "/api/contacts",
    query: queryParams,
    credentials,
  })

  // Return first matching record
  return {
    record: response.data.length > 0 ? response.data[0] : null,
  }
}

Input

Property	Type	Description
`fields`	object	Field values to match against
`credentials`	object	Authentication credentials
`parameters`	object	Method-specific parameters

Return Value

Property	Type	Description
`record`	object\|null	The matching record or null if not found

Example

// Input:
{
  "fields": {
    "email": "john@example.com"
  }
}

// Returns:
{
  "record": {
    "contact_id": "123",
    "email_address": "john@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }
}

Notes

Return record: null if no match is found
The record is automatically processed through fieldsFromApi
Use this for deduplication or finding records by natural keys
Only configured fields in the fields array can be used for matching