ℹ️ This article is for developers and technical teams working with the Famly Public API
If you sync Famly with another system, such as a CRM, a funding portal, or your own database, you need a reliable way to say "this child in Famly is this record over there". External system references do exactly that. Each reference is a small pair: the name of your system, and the ID the child or site has in it.
You can store as many references as you need on a child or a site, one per system. Later you can look a child up by that ID, so you never have to keep your own mapping table.
What a reference looks like
Every reference has two parts:
system - the name of the external system, for example, HUBSPOT or MY_FUNDING_PORTAL
foreignId - the record's ID in that system
You choose the system name. Pick one spelling and stick to it across your integration, since the lookup matches on it. Famly also has a few built-in names for systems we connect to, such as KITA_PLANER and HUBSPOT, and you'll see those in the data when a site uses one of those integrations.
The Public API lives at the GraphQL endpoint /v1/graphql and takes your access token in the X-Famly-Accesstoken header, as described in our getting started guide.
References on Sites
Sites have had external system references for a while, and you'll find them on every site in the Public API.
query {
sites {
list {
result {
siteId
title
externalSystemsReferences {
foreignId
system
}
}
}
}
}
A few things to know:
Site references are read-only in the Public API. Add, edit, or delete them in the Famly app under Settings → Site settings → External IDs
System can be null on a site reference that was added without a system name. Treat null the same as "unknown"
References on Children
Children can carry the same kind of references, and here you can read them, set them, and search by them.
Reading a child's references
Ask for externalSystemsReferences on any child, in any of the children queries.
query {
children {
listBySiteIds(siteIds: ["<site id>"]) {
result {
id
name
externalSystemsReferences {
foreignId
system
}
}
next
}
}
}
A child with no references returns an empty list. On children, system is never null. A reference that was stored without a system name comes back as UNKNOWN.
Finding a child by its ID in your system
This is the part that saves you a mapping table. Give the lookup your system's name and the ID, and Famly returns the matching children.
query {
children {
listByExternalSystemReference(system: "MY_FUNDING_PORTAL", foreignId: "FP-10482") {
result {
id
name
externalSystemsReferences {
foreignId
system
}
}
}
}
}
Here is how the lookup behaves:
It searches every site your access token can view children in, so you don't pass site IDs
It includes past and future children, not only the ones active today. A record in your system can always be resolved, even after the child has left
Both system and foreignId are matched case-insensitively, and surrounding whitespace is ignored
Famly does not force IDs to be unique. If two children carry the same reference, you get both. Design for a list, not a single result
The result is not paginated. next is always null
Pass UNKNOWN as the system to find references that never recorded one