Look up corresponding external and DevRev records

Mapper lookup contract

Responses are unwrapped values. There is no Axios .data property. Lookups resolve to null for a missing record; other failures reject with AirSyncHttpError. Do not treat an authorization or network failure as “not found.”

This complete helper resolves one external ID for an existing DevRev object. Connectors supporting several IDs should select by their own labeling contract rather than assuming the first ID is appropriate.

import type { Mappers } from '@devrev/airsync-sdk';

export async function findExternalId(
  mappers: Mappers,
  syncUnit: string,
  devrevId: string,
): Promise<string | null> {
  const result = await mappers.getByTargetId({
    sync_unit: syncUnit,
    target: devrevId,
  });
  return result?.sync_mapper_record.external_ids[0] ?? null;
}

For an external-ID lookup, the SDK requires the DevRev target type, not the external record-type key:

import { Mappers, SyncMapperRecordTargetType } from '@devrev/airsync-sdk';

export async function findWork(mappers: Mappers, syncUnit: string, externalId: string) {
  return mappers.getByExternalId({
    sync_unit: syncUnit,
    external_id: externalId,
    target_type: SyncMapperRecordTargetType.WORK,
  });
}

Verification

Test lookup success in both directions, null on absence, and rejection on a non-404 platform failure. Check scope isolation between sync units and selection of secondary IDs. Confirm standard loading persists identities once and records external versions when your callback returns modifiedDate.

Related contracts: data loading, loop prevention, rich text references.

Mapper persistence

The SDK manages mapper writes for standard loading callbacks. Use manual persistence only for connector-owned work that requires it.

The platform maintains mappers during import. The SDK's standard loading methods create or update mappers after external writes. Do not add duplicate mapper writes to extraction or standard loading callbacks.

For a custom operation that genuinely owns a new identity link, use this public SDK shape:

import { Mappers, SyncMapperRecordStatus } from '@devrev/airsync-sdk';

export async function persistIdentity(
  mappers: Mappers,
  syncUnit: string,
  externalId: string,
  devrevId: string,
) {
  return mappers.create({
    sync_unit: syncUnit,
    external_ids: [externalId],
    targets: [devrevId],
    status: SyncMapperRecordStatus.OPERATIONAL,
  });
}

An update adds identifiers using { add: [...] }. The public update contract does not expose a remove or replace operation for these arrays. Do not create a new mapper merely because a lookup failed transiently.

Mapper record fields

Use these fields and target-type values when reading or writing mapper records.

Values in secondary_ids are not independently indexed. Include a secondary value in external_ids too if it must be found by external-ID lookup. Avoid storing secrets or customer payloads in extra_data.

OPERATIONAL identifies an active link. FILTERED records an object excluded by user filters. IGNORED identifies an external object that should not be created or updated in DevRev. These statuses are not interchangeable missing-record signals.

SDK target types

The public SyncMapperRecordTargetType enum includes:

A mapper target enum does not guarantee that a corresponding external record type is supported for import or reverse sync. Consult supported object types and the recipe for that capability.