Skip to main content
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

PropertyTypeDescription
fieldsobjectField values to match against
credentialsobjectAuthentication credentials
parametersobjectMethod-specific parameters

​
Return Value

PropertyTypeDescription
recordobject|nullThe 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