The Signa API organizes trademark data around four core entity types. Each has its own namespace on the SDK client with retrieve(), list(), and relationship methods.
Trademarks
Retrieve
Fetch a single trademark by its Signa ID. Returns the full detail tier including owners, classifications, attorneys, media, and Madrid coverage.
const tm = await signa.trademarks.retrieve('tm_abc123');
console.log(tm.mark_text); // "SIGNA"
console.log(tm.status.primary); // "active"
console.log(tm.owners); // [{ id: 'own_...', name: 'Signa Inc.' }]
console.log(tm.classifications); // [{ nice_class: 9, ... }]
const tm = await signa.trademarks.retrieve('tm_abc123', {
include: ['history'],
});
// The 50 most recent events are inlined
for (const event of tm.history) {
console.log(event.event_date, event.event_type, event.description);
}
History
Full prosecution event history for a trademark, paginated:
const events = await signa.trademarks.history('tm_abc123');
for await (const event of events) {
console.log(event.event_date, event.event_type);
}
Changes
Version-level change tracking — what fields changed between ingestion versions:
const changes = await signa.trademarks.changes('tm_abc123');
for await (const change of changes) {
console.log(change.changed_at, change.fields_changed);
}
const related = await signa.trademarks.related('tm_abc123');
for await (const rel of related) {
console.log(rel.trademark.mark_text, rel.relationship_type);
}
Proceedings
Oppositions, cancellations, and other proceedings linked to a trademark:
const procs = await signa.trademarks.proceedings('tm_abc123');
for await (const proc of procs) {
console.log(proc.proceeding_type, proc.status);
}
Madrid Coverage
For Madrid Protocol registrations — list the designated territories:
const coverage = await signa.trademarks.coverage('tm_abc123');
for await (const territory of coverage) {
console.log(territory.jurisdiction_code, territory.status);
}
const imageUrl = await signa.trademarks.media('tm_abc123', 'med_def456');
// Returns a redirect URL to the media file
Source
Provenance metadata — where the data came from and when it was last synced:
const source = await signa.trademarks.source('tm_abc123');
console.log(source.office_code); // "uspto"
console.log(source.source_type); // "bulk_daily"
console.log(source.last_synced_at); // "2025-04-14T..."
Suggest
Autocomplete suggestions as the user types:
const suggestions = await signa.trademarks.suggest({ q: 'appl' });
for (const s of suggestions.data) {
console.log(s.mark_text, s.office_code);
}
Owners
Retrieve
Fetch an owner with aliases, identifiers, address, and stats:
const owner = await signa.owners.retrieve('own_abc123');
console.log(owner.name); // "Apple Inc."
console.log(owner.country_code); // "US"
console.log(owner.stats); // { trademark_count: 1234, ... }
console.log(owner.companies?.[0]?.ticker); // "AAPL"
List
Search and filter owners:
const owners = await signa.owners.list({
q: 'Apple',
country_code: 'US',
publicly_traded: true,
});
for await (const owner of owners) {
console.log(owner.name, owner.trademark_count);
}
Owner’s Trademarks
List all trademarks owned by a specific entity:
const marks = await signa.owners.trademarks('own_abc123', {
status: 'registered',
});
for await (const tm of marks) {
console.log(tm.mark_text, tm.filing_date);
}
Corporate Relationships
Corporate parent/child relationships derived from GLEIF data:
const related = await signa.owners.related('own_abc123');
for await (const rel of related) {
console.log(rel.related_owner.name, rel.relationship_type);
// "Alphabet Inc.", "parent"
}
Attorneys
Retrieve
Fetch an attorney with firm linkage, stats, and top clients:
const attorney = await signa.attorneys.retrieve('att_abc123');
console.log(attorney.name);
console.log(attorney.firm); // { id: 'firm_...', name: '...' }
console.log(attorney.stats); // { trademark_count, ... }
List
Search attorneys by name or firm:
const attorneys = await signa.attorneys.list({ q: 'Smith' });
for await (const att of attorneys) {
console.log(att.name, att.firm?.name);
}
Attorney’s Trademarks
const marks = await signa.attorneys.trademarks('att_abc123');
for await (const tm of marks) {
console.log(tm.mark_text);
}
Attorney’s Clients
List the owners (clients) represented by this attorney:
const clients = await signa.attorneys.clients('att_abc123');
for await (const client of clients) {
console.log(client.owner.name, client.trademark_count);
}
Firms
Retrieve
const firm = await signa.firms.retrieve('firm_abc123');
console.log(firm.name);
console.log(firm.attorney_count);
console.log(firm.stats);
List
const firms = await signa.firms.list({ q: 'Morrison' });
for await (const firm of firms) {
console.log(firm.name, firm.attorney_count);
}
Firm’s Attorneys
const attorneys = await signa.firms.attorneys('firm_abc123', {
sort: '-trademark_count',
});
for await (const att of attorneys) {
console.log(att.name, att.trademark_count);
}
Firm’s Trademarks
const marks = await signa.firms.trademarks('firm_abc123');
for await (const tm of marks) {
console.log(tm.mark_text, tm.office_code);
}
Resolved Entities
Resolved entities (ent_*) are the cross-office identity over per-office owner records — one company linked across USPTO, EUIPO, CIPO, and the rest. Public-company facts (ticker, lei) are served through the entity.
Retrieve
const entity = await signa.entities.retrieve('ent_abc123');
console.log(entity.name); // "8x8, Inc."
console.log(entity.entity_id_type); // "resolved"
console.log(entity.ticker); // "EGHT"
console.log(entity.members.length); // 5 — one per office, with link evidence
ent_<owner-uuid> for an owner that has since been linked resolves to the real entity (the returned id may differ from the one requested).
List
// Find a company once, across all offices
const entities = await signa.entities.list({ q: '8x8', publicly_traded: true });
for await (const e of entities) {
console.log(e.name, e.ticker, e.member_count);
}
Entity’s Trademarks
// The global portfolio — marks across ALL member owners
const marks = await signa.entities.trademarks('ent_abc123', {
status_primary: 'active',
});
Entity’s Family
// GLEIF-curated direct parent + subsidiaries
const family = await signa.entities.family('ent_abc123');
console.log(family.parent?.name); // "8x8 Holdings" (or null)
console.log(family.children.length); // direct subsidiaries
Owner detail also exposes the entity link: owner.entity_id /
owner.entity_id_type, plus inherited publicly_traded / ticker / lei /
has_lei and a companies_source flag (entity vs direct).
Proceedings
Standalone access to opposition, cancellation, and other tribunal proceedings:
Retrieve
const proc = await signa.proceedings.retrieve('prc_abc123');
console.log(proc.proceeding_type); // "opposition"
console.log(proc.status); // "pending"
console.log(proc.parties);
List
// Proceedings for a specific trademark
const procs = await signa.proceedings.list({ trademark_id: 'tm_abc123' });
// Filter by type and status
const oppositions = await signa.proceedings.list({
proceeding_type: 'opposition',
status: 'pending',
});
Cross-Entity Suggest
Search across all entity types in a single call — useful for building omnisearch UIs:
const suggestions = await signa.suggest.crossEntity({ q: 'apple' });
for (const s of suggestions.data) {
console.log(s.entity_type, s.text); // "trademark", "APPLE" / "owner", "Apple Inc."
}
// Limit to a specific type — 'entity' returns resolved entities (ent_*) only,
// excluding singleton owners (which would duplicate the 'owner' leg).
const entitySuggestions = await signa.suggest.crossEntity({
q: 'apple',
type: 'entity',
});
